1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Introduction</title> 5<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Chapter 1. Boost.Convert 2.0"> 8<link rel="up" href="../index.html" title="Chapter 1. Boost.Convert 2.0"> 9<link rel="prev" href="../index.html" title="Chapter 1. Boost.Convert 2.0"> 10<link rel="next" href="getting_started.html" title="Getting Started"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="getting_started.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="boost_convert.introduction"></a><a class="link" href="introduction.html" title="Introduction">Introduction</a> 28</h2></div></div></div> 29<p> 30 <span class="emphasis"><em>Boost.Convert</em></span> builds on the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span></code> 31 experience and takes those type conversion/transformation-related ideas further 32 </p> 33<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 34<li class="listitem"> 35 to be applicable to a wider range of conversion-related deployment scenarios, 36 </li> 37<li class="listitem"> 38 to provide a more flexible, configurable and extendible type-conversion 39 framework, 40 </li> 41<li class="listitem"> 42 to provide generic consistent behavior, 43 </li> 44<li class="listitem"> 45 to <span class="emphasis"><em>unify and to uniformly deploy</em></span> various conversion 46 facilities <span class="emphasis"><em>through one consistent interface</em></span>. 47 </li> 48</ul></div> 49<p> 50 <span class="emphasis"><em>Boost.Convert</em></span> provides new and familiar conversion/transformation-related 51 functionality such as: 52 </p> 53<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 54<li class="listitem"> 55 means to deploy types that do not meet the <a href="http://en.cppreference.com/w/cpp/named_req/DefaultConstructible" target="_top"><span class="emphasis"><em>Default 56 Constructibility</em></span></a> requirement; 57 </li> 58<li class="listitem"> 59 four types of the conversion-failure <span class="emphasis"><em>detection</em></span>: 60 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> 61<li class="listitem"> 62 as part of the same process flow -- basic and generic; 63 </li> 64<li class="listitem"> 65 as a branched process flow -- exception-based and function-based; 66 </li> 67</ul></div> 68 </li> 69<li class="listitem"> 70 the choice of immediate or delayed exception-throwing and non-throwing 71 conversion-failure <span class="emphasis"><em>processing</em></span>; 72 </li> 73<li class="listitem"> 74 flexibility of conversion-failure <span class="emphasis"><em>processing</em></span> via: 75 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> 76<li class="listitem"> 77 an exception thrown; 78 </li> 79<li class="listitem"> 80 the fallback value returned; 81 </li> 82<li class="listitem"> 83 the fallback function called; 84 </li> 85</ul></div> 86 </li> 87<li class="listitem"> 88 support for standard algorithms. 89 </li> 90</ul></div> 91<p> 92 <span class="emphasis"><em>Boost.Convert</em></span> consists of two components: 93 </p> 94<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 95<li class="listitem"> 96 the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">convert</span><span class="special">()</span></code> 97 interface; 98 </li> 99<li class="listitem"> 100 an extendible collection of pluggable converters. 101 </li> 102</ul></div> 103<p> 104 The <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">convert</span><span class="special">()</span></code> 105 interface 106 </p> 107<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 108<li class="listitem"> 109 advertises, provides and ensures certain <span class="emphasis"><em>consistent behavior</em></span>; 110 </li> 111<li class="listitem"> 112 unifies and provides <span class="emphasis"><em>one consistent interface</em></span> to various 113 conversion facilities. 114 </li> 115</ul></div> 116<p> 117 The collection of pluggable converters is independent of the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">convert</span><span class="special">()</span></code> API facade and is designed to be <span class="emphasis"><em>extendible</em></span> 118 and extended over time. Currently the following converters are provided: 119 </p> 120<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 121<li class="listitem"> 122 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span></code>-based, 123 </li> 124<li class="listitem"> 125 <code class="computeroutput"><span class="identifier">printf</span><span class="special">/</span><span class="identifier">scanf</span></code>-based, 126 </li> 127<li class="listitem"> 128 <code class="computeroutput"><span class="identifier">strtol</span></code>-inspired, 129 </li> 130<li class="listitem"> 131 <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span></code>-based, 132 </li> 133<li class="listitem"> 134 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span></code>-based. 135 </li> 136</ul></div> 137<p> 138 The converters provide new and familiar functionality and demonstrate how existing 139 and independent conversion facilities might be incorporated in to the <span class="emphasis"><em>Boost.Convert</em></span> 140 framework. For example, the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">stream</span></code>-based 141 converter draws on the standard <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">streams</span></code> 142 functionality and provides: 143 </p> 144<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 145<li class="listitem"> 146 string-to-type and type-to-string conversions; 147 </li> 148<li class="listitem"> 149 formatting support (<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ios</span></code>-based 150 precision, base, upper/lower-case, scientific, etc.); 151 </li> 152<li class="listitem"> 153 support for different <code class="computeroutput"><span class="identifier">locale</span></code>s; 154 </li> 155<li class="listitem"> 156 <code class="computeroutput"><span class="keyword">char</span></code> and <code class="computeroutput"><span class="keyword">wchar_t</span></code> 157 support. 158 </li> 159</ul></div> 160<p> 161 The following code demonstrates conversion of an array of integers from their 162 textual <span class="emphasis"><em>hexadecimal</em></span> representation. It assigns -1 to those 163 which fail to convert: 164 </p> 165<p> 166</p> 167<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special"><</span><span class="keyword">char</span> <span class="keyword">const</span><span class="special">*,</span> <span class="number">3</span><span class="special">></span> <span class="identifier">strs</span> <span class="special">=</span> <span class="special">{{</span> <span class="string">" 5"</span><span class="special">,</span> <span class="string">"0XF"</span><span class="special">,</span> <span class="string">"not an int"</span> <span class="special">}};</span> 168<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">ints</span><span class="special">;</span> 169<span class="identifier">boost</span><span class="special">::</span><span class="identifier">cnv</span><span class="special">::</span><span class="identifier">cstream</span> <span class="identifier">cnv</span><span class="special">;</span> 170 171<span class="comment">// Configure converter to read hexadecimal, skip (leading) white spaces.</span> 172<span class="identifier">cnv</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">hex</span><span class="special">)(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">skipws</span><span class="special">);</span> 173 174<span class="identifier">std</span><span class="special">::</span><span class="identifier">transform</span><span class="special">(</span><span class="identifier">strs</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">strs</span><span class="special">.</span><span class="identifier">end</span><span class="special">(),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">ints</span><span class="special">),</span> 175 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">cnv</span><span class="special">::</span><span class="identifier">apply</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">cref</span><span class="special">(</span><span class="identifier">cnv</span><span class="special">)).</span><span class="identifier">value_or</span><span class="special">(-</span><span class="number">1</span><span class="special">));</span> 176 177<span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">ints</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">3</span><span class="special">);</span> <span class="comment">// Number of values processed.</span> 178<span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">ints</span><span class="special">[</span><span class="number">0</span><span class="special">]</span> <span class="special">==</span> <span class="number">5</span><span class="special">);</span> <span class="comment">// " 5"</span> 179<span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">ints</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">==</span> <span class="number">15</span><span class="special">);</span> <span class="comment">// "0XF"</span> 180<span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">ints</span><span class="special">[</span><span class="number">2</span><span class="special">]</span> <span class="special">==</span> <span class="special">-</span><span class="number">1</span><span class="special">);</span> <span class="comment">// "not an int"</span> 181</pre> 182<p> 183 </p> 184</div> 185<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 186<td align="left"></td> 187<td align="right"><div class="copyright-footer">Copyright © 2009-2016 Vladimir Batov<p> 188 Distributed under the Boost Software License, Version 1.0. See copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>. 189 </p> 190</div></td> 191</tr></table> 192<hr> 193<div class="spirit-nav"> 194<a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="getting_started.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 195</div> 196</body> 197</html> 198
