libs/conversion/lexical_cast.htm

   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="#faq">Frequently Asked Questions</a></li>
  25                         <li>
  26                                 <a href="#references">References</a></li>
  27                         <li>
  28                                 <a href="#changes">Changes</a></li>
  29                 </ul>
  30                 <hr>
  31                 <h2><a name="motivation">Motivation</a></h2>
  32                 Sometimes a value must be converted to a literal text form, such as an <code>int</code>
  33                 represented as a <code>string</code>, or vice-versa, when a <code>string</code>
  34                 is interpreted as an <code>int</code>. Such examples are common when converting
  35                 between data types internal to a program and representation external to a
  36                 program, such as windows and configuration files.
  37                 <p>
  38                 The standard C and C++ libraries offer a number of facilities for performing
  39                 such conversions. However, they vary with their ease of use, extensibility, and
  40                 safety.
  41                 <p>
  42                         For instance, there are a number of limitations with the family of standard C
  43                         functions typified by <code>atoi</code>:
  44                         <ul type="square">
  45                                 <li>
  46                                         Conversion is supported in one direction only: from text to internal data type.
  47                                         Converting the other way using the C library requires either the inconvenience
  48                                         and compromised safety of the <code>sprintf</code> function, or the loss of
  49                                         portability associated with non-standard functions such as <code>itoa</code>.
  50                                 </li>
  51                                 <li>
  52                                         The range of types supported is only a subset of the built-in numeric types,
  53                                         namely <code>int</code>, <code>long</code>, and <code>double</code>.
  54                                 </li>
  55                                 <li>
  56                                         The range of types cannot be extended in a uniform manner. For instance,
  57                                         conversion from string representation to <code>complex</code> or <code>rational</code>.
  58                                 </li>
  59                         </ul>
  60                         The standard C functions typified by <code>strtol</code> have the same basic
  61                         limitations, but offer finer control over the conversion process. However, for
  62                         the common case such control is often either not required or not used. The <code>scanf</code>
  63                 family of functions offer even greater control, but also lack safety and ease
  64                 of use.
  65                 <p>
  66                         The standard C++ library offers <code>stringstream</code> for the kind of
  67                         in-core formatting being discussed. It offers a great deal of control over the
  68                         formatting and conversion of I/O to and from arbitrary types through text.
  69                         However, for simple conversions direct use of <code>stringstream</code> can be
  70                         either clumsy (with the introduction of extra local variables and the loss of
  71                         infix-expression convenience) or obscure (where <code>stringstream</code>
  72                 objects are created as temporary objects in an expression). Facets provide a
  73                 comprehensive concept and facility for controlling textual representation, but
  74                 their perceived complexity and high entry level requires an extreme degree of
  75                 involvement for simple conversions, and excludes all but a few programmers.
  76                 <p>
  77                         The <code>lexical_cast</code> function template offers a convenient and
  78                         consistent form for supporting common conversions to and from arbitrary types
  79                         when they are represented as text. The simplification it offers is in
  80                         expression-level convenience for such conversions. For more involved
  81                         conversions, such as where precision or formatting need tighter control than is
  82                         offered by the default behavior of <code>lexical_cast</code>, the conventional <code>
  83                                 stringstream</code> approach is recommended. Where the conversions are
  84                         numeric to numeric, <code><a href="../numeric/conversion/doc/html/boost_numericconversion/improved_numeric_cast__.html">numeric_cast</a></code>
  85                         may offer more reasonable behavior than <code>lexical_cast</code>.
  86                 <p>
  87                         For a good discussion of the options and issues involved in string-based
  88                         formatting, including comparison of <code>stringstream</code>, <code>lexical_cast</code>,
  89                         and others, see Herb Sutter's article, <a href="http://www.gotw.ca/publications/mill19.htm">
  90                                 <i>The String Formatters of Manor Farm</i></a>.
  91                 <p>
  92                         <hr>
  93                         <h2><a name="examples">Examples</a></h2>
  94                         The following example treats command line arguments as a sequence of numeric
  95                         data: <blockquote>
  96                                 <pre>int main(int argc, char * argv[])
  97 {
  98     using boost::lexical_cast;
  99     using boost::bad_lexical_cast;
 100
 101     std::vector&lt;short&gt; args;
 102
 103     while(*++argv)
 104     {
 105         try
 106         {
 107             args.push_back(lexical_cast&lt;short&gt;(*argv));
 108         }
 109         catch(bad_lexical_cast &amp;)
 110         {
 111             args.push_back(0);
 112         }
 113     }
 114     ...
 115 }
 116 </pre>
 117                         </blockquote>The following example uses numeric data in a string expression: <blockquote>
 118                                 <pre>void log_message(const std::string &amp;);
 119
 120 void log_errno(int yoko)
 121 {
 122     log_message(&quot;Error &quot; + boost::lexical_cast&lt;std::string&gt;(yoko) + &quot;: &quot; + strerror(yoko));
 123 }
 124 </pre>
 125                         </blockquote>
 126                         <hr>
 127                         <h2><a name="synopsis">Synopsis</a></h2>
 128                         Library features defined in <a href="../../boost/lexical_cast.hpp"><code>&quot;boost/lexical_cast.hpp&quot;</code></a>:
 129                         <blockquote>
 130                                 <pre>namespace boost
 131 {
 132     class <a href="#bad_lexical_cast">bad_lexical_cast</a>;
 133     template&lt;typename Target, typename Source&gt;
 134       Target <a href="#lexical_cast">lexical_cast</a>(const Source&amp; arg);
 135 }
 136 </pre>
 137                         </blockquote>Unit test defined in <a href="lexical_cast_test.cpp"><code>&quot;lexical_cast_test.cpp&quot;</code></a>.
 138                 <p>
 139                         <hr>
 140                         <h2><a name="lexical_cast"><code>lexical_cast</code></a></h2>
 141                         <blockquote>
 142                                 <pre>template&lt;typename Target, typename Source&gt;
 143   Target lexical_cast(const Source&amp; arg);
 144 </pre>
 145                         </blockquote>Returns the result of streaming <code>arg</code> into a
 146                         standard library string-based stream and then out as a <code>Target</code> object.
 147                         Where <code>Target</code> is either <code>std::string</code>
 148                         or <code>std::wstring</code>, stream extraction takes the whole content
 149                         of the string, including spaces, rather than relying on the default
 150                         <code>operator&gt;&gt;</code> behavior.
 151                         If the conversion is unsuccessful, a <a href="#bad_lexical_cast">
 152                                 <code>bad_lexical_cast</code></a> exception is thrown.
 153                 <p>
 154                         The requirements on the argument and result types are:
 155                         <ul type="square">
 156                                 <li>
 157                                         <code>Source</code> is <i>OutputStreamable</i>, meaning that an <code>operator&lt;&lt;</code>
 158                                         is defined that takes a <code>std::ostream</code> or <code>std::wostream</code> object on the
 159                                         left hand side and an instance of the argument type on the right.
 160                                 </li>
 161                                 <li>
 162                                         <code>Target</code> is <i>InputStreamable</i>, meaning that an <code>operator&gt;&gt;</code>
 163                                         is defined that takes a <code>std::istream</code> or <code>std::wistream</code> object on the left hand side
 164                                         and an instance of the result type on the right.
 165                                 </li>
 166                                 <li>
 167                                         <code>Target</code> is <i>CopyConstructible</i> [20.1.3].
 168                                 </li>
 169                                 <li>
 170                                         <code>Target</code> is <i>DefaultConstructible</i>, meaning that it is possible
 171                                         to <i>default-initialize</i> an object of that type [8.5, 20.1.4].
 172                                 </li>
 173                         </ul>
 174                         The character type of the underlying stream is assumed to be <code>char</code> unless
 175                         either the <code>Source</code> or the <code>Target</code> requires wide-character
 176                         streaming, in which case the underlying stream uses <code>wchar_t</code>.
 177                         <code>Source</code> types that require wide-character streaming are <code>wchar_t</code>,
 178                         <code>wchar_t *</code>, and <code>std::wstring</code>. <code>Target</code> types that
 179                         require wide-character streaming are <code>wchar_t</code> and <code>std::wstring</code>.
 180                         <p>
 181                         Where a higher degree of control is required over conversions, <code>std::stringstream</code>
 182                         and <code>std::wstringstream</code> offer a more appropriate path. Where non-stream-based conversions are
 183                         required, <code>lexical_cast</code>
 184                 is the wrong tool for the job and is not special-cased for such scenarios.
 185                 <p>
 186                         <hr>
 187                         <h2><a name="bad_lexical_cast"><code>bad_lexical_cast</code></a></h2>
 188                         <blockquote>
 189                                 <pre>class bad_lexical_cast : public std::bad_cast
 190 {
 191 public:
 192     ... // <i>same member function interface as</i> std::exception
 193 };
 194 </pre>
 195                         </blockquote>Exception used to indicate runtime <a href="#lexical_cast"><code>lexical_cast</code></a>
 196                 failure.
 197
 198 <hr>
 199   <h2><a name="BOOST_LEXICAL_CAST_ASSUME_C_LOCALE"><code>BOOST_LEXICAL_CAST_ASSUME_C_LOCALE</code></a></h2>
 200   <blockquote><pre>#define BOOST_LEXICAL_CAST_ASSUME_C_LOCALE
 201
 202 or,
 203
 204 g++ -DBOOST_LEXICAL_CAST_ASSUME_C_LOCALE ...  (gcc on Linux/Unix)
 205 cl.exe /DBOOST_LEXICAL_CAST_ASSUME_C_LOCALE ... (Visual C++ on Windows)
 206 </pre>
 207 Eliminate an overhead of <code>std::locale</code> if your program runs in the "C" locale. If the option is set but a program runs in other locale, <code>lexical_cast</code> result is unspecified.
 208 <hr>
 209
 210 <h2><a name="faq">Frequently Asked Questions</h2>
 211     <p> Q: Why does <code>lexical_cast&lt;int8_t&gt;("127")</code> throw <code>bad_lexical_cast</code>?
 212     <br> A: The type <code>int8_t</code> is a typedef to <code>char</code> or <code>signed char</code>.
 213     Lexical conversion to these types is simply reading a byte from source but since the source has
 214     more than one byte, the exception is thrown.
 215     <p>Please use other integer types such as <code>int</code> or <code>short int</code>. If bounds checking
 216     is important, you can also call <a href="../../libs/numeric/conversion/doc/html/boost_numericconversion/improved_numeric_cast__.html">numeric_cast</a>:
 217
 218 <pre><a href="../../libs/numeric/conversion/doc/html/boost_numericconversion/improved_numeric_cast__.html">numeric_cast</a>&lt;int8_t&gt;(lexical_cast&lt;int&gt;("127"));</pre>
 219
 220     <p> Q: What does <code>lexical_cast&lt;std::string&gt;</code> of an <code>int8_t</code> or <code>uint8_t</code> not do what I expect?
 221     <br> A: As above, note that <code>int8_t</code> and <code>uint8_t</code> are actually chars and are formatted as such.  To avoid this, cast to an integer type first:
 222
 223 <pre>lexical_cast&lt;std::string&gt;(static_cast&lt;int&gt;(n));</pre>
 224
 225     <p> Q: The implementation always resets the <code>ios_base::skipws</code> flag of an underlying stream object. It breaks my <code>operator&gt;&gt;</code> that works only in presence of this flag. Can you remove code that resets the flag?
 226     <br> A: May be in a future version. There is no requirement in <a href="#n1973">[N1973]</a> to reset the flag but remember that <a href="#n1973">[N1973]</a> is not yet accepted by the committee. By the way, it's a great opportunity to make your <code>operator&gt;&gt;</code> conform to the standard. Read a good C++ book, study <code>std::sentry</code> and <a href="../../libs/io/doc/ios_state.html">ios_state_saver</a>.
 227 </ul>
 228 <h2><a name="references">References</h2>
 229 <ul type="square">
 230     <a name="n1973"></a><li> [N1973] Kevlin Henney, Beman Dawes, Lexical Conversion Library Proposal for TR2,
 231       <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1973.html">N1973</a>.
 232       <a name="tuning"></a><li> [Tuning] Alexander Nasonov, Fine Tuning for lexical_cast,
 233       <a href="http://accu.org/index.php/journals/1375">Overload #74</a> (<a href="http://www.accu.org/var/uploads/journals/overload74.pdf">PDF</a>),
 234       August 2006.</li>
 235 </ul>
 236 <h2><a name="changes">Changes</a></h2>
 237 <h3>August, October 2006:</h3>
 238 <ul type="square">
 239     <li>Better performance for many combinations of <code>Source</code> and <code>Target</code>
 240     types. Refer to <a href="#tuning">[Tuning]</a> for more details.
 241   </li>
 242 </ul>
 243 <h3>June 2005:</h3>
 244 <ul type="square">
 245   <li>Call-by-const reference for the parameters. This requires partial specialization
 246     of class templates, so it doesn't work for MSVC 6, and it uses the original
 247     pass by value there.<br>
 248   </li>
 249   <li>The MSVC 6 support is deprecated, and will be removed in a future Boost
 250     version. </li>
 251 </ul>
 252 <h3>Earlier:</h3>
 253
 254 <ul type="square">
 255   <li>The previous version of <code>lexical_cast</code> used the default stream
 256     precision for reading and writing floating-point numbers. For numerics that
 257     have a corresponding specialization of <code>std::numeric_limits</code>, the
 258     current version now chooses a precision to match. <br>
 259   <li>The previous version of <code>lexical_cast</code> did not support conversion
 260     to or from any wide-character-based types. For compilers with full language
 261     and library support for wide characters, <code>lexical_cast</code> now supports
 262     conversions from <code>wchar_t</code>, <code>wchar_t *</code>, and <code>std::wstring</code>
 263     and to <code>wchar_t</code> and <code>std::wstring</code>. <br>
 264   <li>The previous version of <code>lexical_cast</code> assumed that the conventional
 265     stream extractor operators were sufficient for reading values. However, string
 266     I/O is asymmetric, with the result that spaces play the role of I/O separators
 267     rather than string content. The current version fixes this error for <code>std::string</code>
 268     and, where supported, <code>std::wstring</code>: <code>lexical_cast&lt;std::string&gt;("Hello,
 269     World")</code> succeeds instead of failing with a <code>bad_lexical_cast</code>
 270     exception. <br>
 271   <li>The previous version of <code>lexical_cast</code> allowed unsafe and meaningless
 272     conversions to pointers. The current version now throws a <code>bad_lexical_cast</code>
 273     for conversions to pointers: <code>lexical_cast&lt;char *&gt;("Goodbye, World")</code>
 274     now throws an exception instead of causing undefined behavior.
 275 </ul>
 276         <p>
 277                         <hr>
 278
 279 <div align="right"><small><i>&copy; Copyright Kevlin Henney, 2000&#150;2005</i></small></div>
 280         </body>
 281 </html>