Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/conversion/lexical_cast.htm @ 29

Last change on this file since 29 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 10.9 KB
Line 
1<!-- saved from url=(0022)http://internet.e-mail -->
2<!doctype html public "-//W3C//DTD HTML Transitional 4.0//EN">
3<html>
4        <head>
5                <title>lexical_cast</title>
6                <meta name="author" content="Kevlin Henney, mailto:kevlin@curbralan.com">
7                <meta name="generator" content="Microsoft FrontPage 5.0">
8        </head>
9        <body bgcolor="#FFFFFF" text="#000000">
10                <h1><img src="../../boost.png" alt="boost.png (6897 bytes)" align="center" width="277" height="86">Header
11                        <a href="../../boost/lexical_cast.hpp">boost/lexical_cast.hpp</a></h1>
12                <ul type="square">
13                        <li>
14                                <a href="#motivation">Motivation</a></li>
15                        <li>
16                                <a href="#examples">Examples</a></li>
17                        <li>
18                                <a href="#synopsis">Synopsis</a></li>
19                        <li>
20                                <a href="#lexical_cast"><code>lexical_cast</code></a></li>
21                        <li>
22                                <a href="#bad_lexical_cast"><code>bad_lexical_cast</code></a></li>
23                        <li>
24                                <a href="#changes">Changes</a></li>
25                </ul>
26                <hr>
27                <h2><a name="motivation">Motivation</a></h2>
28                Sometimes a value must be converted to a literal text form, such as an <code>int</code>
29                represented as a <code>string</code>, or vice-versa, when a <code>string</code> 
30                is interpreted as an <code>int</code>. Such examples are common when converting
31                between data types internal to a program and representation external to a
32                program, such as windows and configuration files.
33                <p>
34                The standard C and C++ libraries offer a number of facilities for performing
35                such conversions. However, they vary with their ease of use, extensibility, and
36                safety.
37                <p>
38                        For instance, there are a number of limitations with the family of standard C
39                        functions typified by <code>atoi</code>:
40                        <ul type="square">
41                                <li>
42                                        Conversion is supported in one direction only: from text to internal data type.
43                                        Converting the other way using the C library requires either the inconvenience
44                                        and compromised safety of the <code>sprintf</code> function, or the loss of
45                                        portability associated with non-standard functions such as <code>itoa</code>.
46                                </li>
47                                <li>
48                                        The range of types supported is only a subset of the built-in numeric types,
49                                        namely <code>int</code>, <code>long</code>, and <code>double</code>.
50                                </li>
51                                <li>
52                                        The range of types cannot be extended in a uniform manner. For instance,
53                                        conversion from string representation to <code>complex</code> or <code>rational</code>.
54                                </li>
55                        </ul>
56                        The standard C functions typified by <code>strtol</code> have the same basic
57                        limitations, but offer finer control over the conversion process. However, for
58                        the common case such control is often either not required or not used. The <code>scanf</code>
59                family of functions offer even greater control, but also lack safety and ease
60                of use.
61                <p>
62                        The standard C++ library offers <code>stringstream</code> for the kind of
63                        in-core formatting being discussed. It offers a great deal of control over the
64                        formatting and conversion of I/O to and from arbitrary types through text.
65                        However, for simple conversions direct use of <code>stringstream</code> can be
66                        either clumsy (with the introduction of extra local variables and the loss of
67                        infix-expression convenience) or obscure (where <code>stringstream</code>
68                objects are created as temporary objects in an expression). Facets provide a
69                comprehensive concept and facility for controlling textual representation, but
70                their perceived complexity and high entry level requires an extreme degree of
71                involvement for simple conversions, and excludes all but a few programmers.
72                <p>
73                        The <code>lexical_cast</code> function template offers a convenient and
74                        consistent form for supporting common conversions to and from arbitrary types
75                        when they are represented as text. The simplification it offers is in
76                        expression-level convenience for such conversions. For more involved
77                        conversions, such as where precision or formatting need tighter control than is
78                        offered by the default behavior of <code>lexical_cast</code>, the conventional <code>
79                                stringstream</code> approach is recommended. Where the conversions are
80                        numeric to numeric, <code><a href="../numeric/conversion/doc/numeric_cast.html">numeric_cast</a></code>
81                        may offer more reasonable behavior than <code>lexical_cast</code>.
82                <p>
83                        For a good discussion of the options and issues involved in string-based
84                        formatting, including comparison of <code>stringstream</code>, <code>lexical_cast</code>,
85                        and others, see Herb Sutter's article, <a href="http://www.gotw.ca/publications/mill19.htm">
86                                <i>The String Formatters of Manor Farm</i></a>.
87                <p>
88                        <hr>
89                        <h2><a name="examples">Examples</a></h2>
90                        The following example treats command line arguments as a sequence of numeric
91                        data: <blockquote>
92                                <pre>int main(int argc, char * argv[])
93{
94    using boost::lexical_cast;
95    using boost::bad_lexical_cast;
96
97    std::vector&lt;short&gt; args;
98
99    while(*++argv)
100    {
101        try
102        {
103            args.push_back(lexical_cast&lt;short&gt;(*argv));
104        }
105        catch(bad_lexical_cast &amp;)
106        {
107            args.push_back(0);
108        }
109    }
110    ...
111}
112</pre>
113                        </blockquote>The following example uses numeric data in a string expression: <blockquote>
114                                <pre>void log_message(const std::string &amp;);
115
116void log_errno(int yoko)
117{
118    log_message(&quot;Error &quot; + boost::lexical_cast&lt;std::string&gt;(yoko) + &quot;: &quot; + strerror(yoko));
119}
120</pre>
121                        </blockquote>
122                        <hr>
123                        <h2><a name="synopsis">Synopsis</a></h2>
124                        Library features defined in <a href="../../boost/lexical_cast.hpp"><code>&quot;boost/lexical_cast.hpp&quot;</code></a>:
125                        <blockquote>
126                                <pre>namespace boost
127{
128    class <a href="#bad_lexical_cast">bad_lexical_cast</a>;
129    template&lt;typename Target, typename Source&gt;
130      Target <a href="#lexical_cast">lexical_cast</a>(const Source&amp; arg);
131}
132</pre>
133                        </blockquote>Unit test defined in <a href="lexical_cast_test.cpp"><code>&quot;lexical_cast_test.cpp&quot;</code></a>.
134                <p>
135                        <hr>
136                        <h2><a name="lexical_cast"><code>lexical_cast</code></a></h2>
137                        <blockquote>
138                                <pre>template&lt;typename Target, typename Source&gt;
139  Target lexical_cast(const Source&amp; arg);
140</pre>
141                        </blockquote>Returns the result of streaming <code>arg</code> into a
142                        standard library string-based stream and then out as a <code>Target</code> object.
143                        Where <code>Target</code> is either <code>std::string</code>
144                        or <code>std::wstring</code>, stream extraction takes the whole content
145                        of the string, including spaces, rather than relying on the default
146                        <code>operator&gt;&gt;</code> behavior.
147                        If the conversion is unsuccessful, a <a href="#bad_lexical_cast">
148                                <code>bad_lexical_cast</code></a> exception is thrown.
149                <p>
150                        The requirements on the argument and result types are:
151                        <ul type="square">
152                                <li>
153                                        <code>Source</code> is <i>OutputStreamable</i>, meaning that an <code>operator&lt;&lt;</code>
154                                        is defined that takes a <code>std::ostream</code> or <code>std::wostream</code> object on the
155                                        left hand side and an instance of the argument type on the right.
156                                </li>
157                                <li>
158                                        <code>Target</code> is <i>InputStreamable</i>, meaning that an <code>operator&gt;&gt;</code>
159                                        is defined that takes a <code>std::istream</code> or <code>std::wistream</code> object on the left hand side
160                                        and an instance of the result type on the right.
161                                </li>
162                                <li>
163                                        Both <code>Source</code> and <code>Target</code> are <i>CopyConstructible</i> [20.1.3].
164                                </li>
165                                <li>
166                                        <code>Target</code> is <i>DefaultConstructible</i>, meaning that it is possible
167                                        to <i>default-initialize</i> an object of that type [8.5, 20.1.4].
168                                </li>
169                        </ul>
170                        The character type of the underlying stream is assumed to be <code>char</code> unless
171                        either the <code>Source</code> or the <code>Target</code> requires wide-character
172                        streaming, in which case the underlying stream uses <code>wchar_t</code>.
173                        <code>Source</code> types that require wide-character streaming are <code>wchar_t</code>,
174                        <code>wchar_t *</code>, and <code>std::wstring</code>. <code>Target</code> types that
175                        require wide-character streaming are <code>wchar_t</code> and <code>std::wstring</code>.
176                        <p>
177                        Where a higher degree of control is required over conversions, <code>std::stringstream</code>
178                        and <code>std::wstringstream</code> offer a more appropriate path. Where non-stream-based conversions are
179                        required, <code>lexical_cast</code>
180                is the wrong tool for the job and is not special-cased for such scenarios.
181                <p>
182                        <hr>
183                        <h2><a name="bad_lexical_cast"><code>bad_lexical_cast</code></a></h2>
184                        <blockquote>
185                                <pre>class bad_lexical_cast : public std::bad_cast
186{
187public:
188    ... // <i>same member function interface as</i> std::exception
189};
190</pre>
191                        </blockquote>Exception used to indicate runtime <a href="#lexical_cast"><code>lexical_cast</code></a>
192                failure.
193                        <hr>
194               
195<h2><a name="changes">Changes</a></h2>
196<h3>June 2005:</h3>
197<ul type="square">
198  <li>Call-by-const reference for the parameters. This requires partial specialization
199    of class templates, so it doesn't work for MSVC 6, and it uses the original
200    pass by value there.<br>
201  </li>
202  <li>The MSVC 6 support is deprecated, and will be removed in a future Boost
203    version. </li>
204</ul>
205<h3>Earlier:</h3>
206       
207<ul type="square">
208  <li>The previous version of <code>lexical_cast</code> used the default stream
209    precision for reading and writing floating-point numbers. For numerics that
210    have a corresponding specialization of <code>std::numeric_limits</code>, the
211    current version now chooses a precision to match. <br>
212  <li>The previous version of <code>lexical_cast</code> did not support conversion
213    to or from any wide-character-based types. For compilers with full language
214    and library support for wide characters, <code>lexical_cast</code> now supports
215    conversions from <code>wchar_t</code>, <code>wchar_t *</code>, and <code>std::wstring</code> 
216    and to <code>wchar_t</code> and <code>std::wstring</code>. <br>
217  <li>The previous version of <code>lexical_cast</code> assumed that the conventional
218    stream extractor operators were sufficient for reading values. However, string
219    I/O is asymmetric, with the result that spaces play the role of I/O separators
220    rather than string content. The current version fixes this error for <code>std::string</code> 
221    and, where supported, <code>std::wstring</code>: <code>lexical_cast&lt;std::string&gt;("Hello,
222    World")</code> succeeds instead of failing with a <code>bad_lexical_cast</code> 
223    exception. <br>
224  <li>The previous version of <code>lexical_cast</code> allowed unsafe and meaningless
225    conversions to pointers. The current version now throws a <code>bad_lexical_cast</code> 
226    for conversions to pointers: <code>lexical_cast&lt;char *&gt;("Goodbye, World")</code> 
227    now throws an exception instead of causing undefined behavior.
228</ul>
229        <p>
230                        <hr>
231                       
232<div align="right"><small><i>&copy; Copyright Kevlin Henney, 2000&#150;2005</i></small></div>
233        </body>
234</html>
Note: See TracBrowser for help on using the repository browser.