doc/html/boost_lexical_cast.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Chapter&#160;21.&#160;Boost.Lexical_Cast 1.0</title>
   6 <link rel="stylesheet" href="../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="libraries.html" title="Part&#160;I.&#160;The Boost C++ Libraries (BoostBook Subset)">
  10 <link rel="prev" href="lambda/s10.html" title="Rationale for some of the design decisions">
  11 <link rel="next" href="boost_lexical_cast/examples.html" title="Examples">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../boost.png"></td>
  16 <td align="center"><a href="../../index.html">Home</a></td>
  17 <td align="center"><a href="../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <a accesskey="p" href="lambda/s10.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost_lexical_cast/examples.html"><img src="../../doc/src/images/next.png" alt="Next"></a>
  25 </div>
  26 <div class="chapter">
  27 <div class="titlepage"><div>
  28 <div><h2 class="title">
  29 <a name="boost_lexical_cast"></a>Chapter&#160;21.&#160;Boost.Lexical_Cast 1.0</h2></div>
  30 <div><p class="copyright">Copyright &#169; 2000-2005 Kevlin Henney</p></div>
  31 <div><p class="copyright">Copyright &#169; 2006-2010 Alexander Nasonov</p></div>
  32 <div><p class="copyright">Copyright &#169; 2011-2019 Antony
  33       Polukhin</p></div>
  34 <div><div class="legalnotice">
  35 <a name="boost_lexical_cast.legal"></a><p>
  36         Distributed under the Boost Software License, Version 1.0. (See accompanying
  37         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
  38       </p>
  39 </div></div>
  40 </div></div>
  41 <div class="toc">
  42 <p><b>Table of Contents</b></p>
  43 <dl class="toc">
  44 <dt><span class="section"><a href="boost_lexical_cast.html#boost_lexical_cast.motivation">Motivation</a></span></dt>
  45 <dt><span class="section"><a href="boost_lexical_cast/examples.html">Examples</a></span></dt>
  46 <dd><dl>
  47 <dt><span class="section"><a href="boost_lexical_cast/examples.html#boost_lexical_cast.examples.strings_to_numbers_conversion">Strings
  48       to numbers conversion</a></span></dt>
  49 <dt><span class="section"><a href="boost_lexical_cast/examples.html#boost_lexical_cast.examples.numbers_to_strings_conversion">Numbers
  50       to strings conversion</a></span></dt>
  51 <dt><span class="section"><a href="boost_lexical_cast/examples.html#boost_lexical_cast.examples.converting_to_string_without_dynamic_memory_allocation">Converting
  52       to string without dynamic memory allocation</a></span></dt>
  53 <dt><span class="section"><a href="boost_lexical_cast/examples.html#boost_lexical_cast.examples.converting_part_of_the_string">Converting
  54       part of the string</a></span></dt>
  55 <dt><span class="section"><a href="boost_lexical_cast/examples.html#boost_lexical_cast.examples.generic_programming__boost_fusion_">Generic
  56       programming (Boost.Fusion)</a></span></dt>
  57 <dt><span class="section"><a href="boost_lexical_cast/examples.html#boost_lexical_cast.examples.generic_programming__boost_variant_">Generic
  58       programming (Boost.Variant)</a></span></dt>
  59 </dl></dd>
  60 <dt><span class="section"><a href="boost_lexical_cast/synopsis.html">Synopsis</a></span></dt>
  61 <dd><dl>
  62 <dt><span class="section"><a href="boost_lexical_cast/synopsis.html#boost_lexical_cast.synopsis.lexical_cast">lexical_cast</a></span></dt>
  63 <dt><span class="section"><a href="boost_lexical_cast/synopsis.html#boost_lexical_cast.synopsis.bad_lexical_cast">bad_lexical_cast</a></span></dt>
  64 <dt><span class="section"><a href="boost_lexical_cast/synopsis.html#boost_lexical_cast.synopsis.try_lexical_convert">try_lexical_convert</a></span></dt>
  65 </dl></dd>
  66 <dt><span class="section"><a href="boost_lexical_cast/frequently_asked_questions.html">Frequently
  67     Asked Questions</a></span></dt>
  68 <dt><span class="section"><a href="boost_lexical_cast/changes.html">Changes</a></span></dt>
  69 <dt><span class="section"><a href="boost_lexical_cast/performance.html">Performance</a></span></dt>
  70 <dd><dl>
  71 <dt><span class="section"><a href="boost_lexical_cast/performance.html#boost_lexical_cast.performance.tests_description">Tests
  72       description</a></span></dt>
  73 <dt><span class="section"><a href="boost_lexical_cast/performance.html#boost_lexical_cast.performance.gnu_c___version_6_1_1_20160511">GNU
  74       C++ version 6.1.1 20160511</a></span></dt>
  75 <dt><span class="section"><a href="boost_lexical_cast/performance.html#boost_lexical_cast.performance.gnu_c___version_4_8_5">GNU
  76       C++ version 4.8.5</a></span></dt>
  77 <dt><span class="section"><a href="boost_lexical_cast/performance.html#boost_lexical_cast.performance.clang_version_3_6_0__tags_release_360_final_">Clang
  78       version 3.6.0 (tags/RELEASE_360/final)</a></span></dt>
  79 </dl></dd>
  80 </dl>
  81 </div>
  82 <div class="section">
  83 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  84 <a name="boost_lexical_cast.motivation"></a><a class="link" href="boost_lexical_cast.html#boost_lexical_cast.motivation" title="Motivation">Motivation</a>
  85 </h2></div></div></div>
  86 <p>
  87       Sometimes a value must be converted to a literal text form, such as an <code class="computeroutput"><span class="keyword">int</span></code> represented as a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>,
  88       or vice-versa, when a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> is interpreted as an <code class="computeroutput"><span class="keyword">int</span></code>. Such examples are common when converting
  89       between data types internal to a program and representation external to a program,
  90       such as windows and configuration files.
  91     </p>
  92 <p>
  93       The standard C and C++ libraries offer a number of facilities for performing
  94       such conversions. However, they vary with their ease of use, extensibility,
  95       and safety.
  96     </p>
  97 <p>
  98       For instance, there are a number of limitations with the family of standard
  99       C functions typified by <code class="computeroutput"><span class="identifier">atoi</span></code>:
 100     </p>
 101 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 102 <li class="listitem">
 103           Conversion is supported in one direction only: from text to internal data
 104           type. Converting the other way using the C library requires either the
 105           inconvenience and compromised safety of the <code class="computeroutput"><span class="identifier">sprintf</span></code>
 106           function, or the loss of portability associated with non-standard functions
 107           such as <code class="computeroutput"><span class="identifier">itoa</span></code>.
 108         </li>
 109 <li class="listitem">
 110           The range of types supported is only a subset of the built-in numeric types,
 111           namely <code class="computeroutput"><span class="keyword">int</span></code>, <code class="computeroutput"><span class="keyword">long</span></code>, and <code class="computeroutput"><span class="keyword">double</span></code>.
 112         </li>
 113 <li class="listitem">
 114           The range of types cannot be extended in a uniform manner. For instance,
 115           conversion from string representation to complex or rational.
 116         </li>
 117 </ul></div>
 118 <p>
 119       The standard C functions typified by <code class="computeroutput"><span class="identifier">strtol</span></code>
 120       have the same basic limitations, but offer finer control over the conversion
 121       process. However, for the common case such control is often either not required
 122       or not used. The <code class="computeroutput"><span class="identifier">scanf</span></code> family
 123       of functions offer even greater control, but also lack safety and ease of use.
 124     </p>
 125 <p>
 126       The standard C++ library offers <code class="computeroutput"><span class="identifier">stringstream</span></code>
 127       for the kind of in-core formatting being discussed. It offers a great deal
 128       of control over the formatting and conversion of I/O to and from arbitrary
 129       types through text. However, for simple conversions direct use of <code class="computeroutput"><span class="identifier">stringstream</span></code> can be either clumsy (with the
 130       introduction of extra local variables and the loss of infix-expression convenience)
 131       or obscure (where <code class="computeroutput"><span class="identifier">stringstream</span></code>
 132       objects are created as temporary objects in an expression). Facets provide
 133       a comprehensive concept and facility for controlling textual representation,
 134       but their perceived complexity and high entry level requires an extreme degree
 135       of involvement for simple conversions, and excludes all but a few programmers.
 136     </p>
 137 <p>
 138       The <code class="computeroutput"><span class="identifier">lexical_cast</span></code> function template
 139       offers a convenient and consistent form for supporting common conversions to
 140       and from arbitrary types when they are represented as text. The simplification
 141       it offers is in expression-level convenience for such conversions. For more
 142       involved conversions, such as where precision or formatting need tighter control
 143       than is offered by the default behavior of <code class="computeroutput"><span class="identifier">lexical_cast</span></code>,
 144       the conventional <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span></code> approach is recommended. Where
 145       the conversions are numeric to numeric, <a href="../../libs/numeric/conversion/doc/html/boost_numericconversion/improved_numeric_cast__.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric_cast</span></code></a>
 146       may offer more reasonable behavior than <code class="computeroutput"><span class="identifier">lexical_cast</span></code>.
 147     </p>
 148 <p>
 149       For a good discussion of the options and issues involved in string-based formatting,
 150       including comparison of <code class="computeroutput"><span class="identifier">stringstream</span></code>,
 151       <code class="computeroutput"><span class="identifier">lexical_cast</span></code>, and others, see
 152       Herb Sutter's article, <a href="http://www.gotw.ca/publications/mill19.htm" target="_top">The
 153       String Formatters of Manor Farm</a>. Also, take a look at the <a class="link" href="boost_lexical_cast/performance.html" title="Performance">Performance</a>
 154       section.
 155     </p>
 156 </div>
 157 </div>
 158 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 159 <td align="left"><p><small>Last revised: December 10, 2019 at 00:26:27 GMT</small></p></td>
 160 <td align="right"><div class="copyright-footer"></div></td>
 161 </tr></table>
 162 <hr>
 163 <div class="spirit-nav">
 164 <a accesskey="p" href="lambda/s10.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost_lexical_cast/examples.html"><img src="../../doc/src/images/next.png" alt="Next"></a>
 165 </div>
 166 </body>
 167 </html>