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=UTF-8"> 5<title>Synopsis</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="../boost_lexical_cast.html" title="Chapter 21. Boost.Lexical_Cast 1.0"> 10<link rel="prev" href="examples.html" title="Examples"> 11<link rel="next" href="frequently_asked_questions.html" title="Frequently Asked Questions"> 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="examples.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_lexical_cast.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="frequently_asked_questions.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="boost_lexical_cast.synopsis"></a><a class="link" href="synopsis.html" title="Synopsis">Synopsis</a> 29</h2></div></div></div> 30<div class="toc"><dl class="toc"> 31<dt><span class="section"><a href="synopsis.html#boost_lexical_cast.synopsis.lexical_cast">lexical_cast</a></span></dt> 32<dt><span class="section"><a href="synopsis.html#boost_lexical_cast.synopsis.bad_lexical_cast">bad_lexical_cast</a></span></dt> 33<dt><span class="section"><a href="synopsis.html#boost_lexical_cast.synopsis.try_lexical_convert">try_lexical_convert</a></span></dt> 34</dl></div> 35<p> 36 Library features defined in <a href="../../../boost/lexical_cast.hpp" target="_top">boost/lexical_cast.hpp</a>: 37</p> 38<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> 39<span class="special">{</span> 40 <span class="keyword">class</span> <span class="identifier">bad_lexical_cast</span><span class="special">;</span> 41 42 <span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Source</span><span class="special">></span> 43 <span class="identifier">Target</span> <span class="identifier">lexical_cast</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Source</span><span class="special">&</span> <span class="identifier">arg</span><span class="special">);</span> 44 45 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">></span> 46 <span class="identifier">Target</span> <span class="identifier">lexical_cast</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">AnyCharacterType</span><span class="special">*</span> <span class="identifier">chars</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">);</span> 47 48 <span class="keyword">namespace</span> <span class="identifier">conversion</span> 49 <span class="special">{</span> 50 <span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Source</span><span class="special">></span> 51 <span class="keyword">bool</span> <span class="identifier">try_lexical_convert</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Source</span><span class="special">&</span> <span class="identifier">arg</span><span class="special">,</span> <span class="identifier">Target</span><span class="special">&</span> <span class="identifier">result</span><span class="special">);</span> 52 53 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">AnyCharacterType</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">></span> 54 <span class="keyword">bool</span> <span class="identifier">try_lexical_convert</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">AnyCharacterType</span><span class="special">*</span> <span class="identifier">chars</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">,</span> <span class="identifier">Target</span><span class="special">&</span> <span class="identifier">result</span><span class="special">);</span> 55 56 <span class="special">}</span> <span class="comment">// namespace conversion</span> 57<span class="special">}</span> <span class="comment">// namespace boost</span> 58</pre> 59<p> 60 </p> 61<div class="section"> 62<div class="titlepage"><div><div><h3 class="title"> 63<a name="boost_lexical_cast.synopsis.lexical_cast"></a><a class="link" href="synopsis.html#boost_lexical_cast.synopsis.lexical_cast" title="lexical_cast">lexical_cast</a> 64</h3></div></div></div> 65<p> 66</p> 67<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Source</span><span class="special">></span> 68 <span class="identifier">Target</span> <span class="identifier">lexical_cast</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Source</span><span class="special">&</span> <span class="identifier">arg</span><span class="special">);</span> 69</pre> 70<p> 71 Returns the result of streaming arg into a standard library string-based 72 stream and then out as a Target object. Where Target is either <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> 73 or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span></code>, stream extraction takes the whole 74 content of the string, including spaces, rather than relying on the default 75 <code class="computeroutput"><span class="keyword">operator</span><span class="special">>></span></code> 76 behavior. If the conversion is unsuccessful, a <code class="computeroutput"><span class="identifier">bad_lexical_cast</span></code> 77 exception is thrown. 78 </p> 79<p> 80</p> 81<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">></span> 82 <span class="identifier">Target</span> <span class="identifier">lexical_cast</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">AnyCharacterType</span><span class="special">*</span> <span class="identifier">chars</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">);</span> 83</pre> 84<p> 85 Takes an array of <code class="computeroutput"><span class="identifier">count</span></code> characters 86 as input parameter and streams them out as a Target object. If the conversion 87 is unsuccessful, a <code class="computeroutput"><span class="identifier">bad_lexical_cast</span></code> 88 exception is thrown. This call may be useful for processing nonzero terminated 89 array of characters or processing just some part of character array. 90 </p> 91<p> 92 The requirements on the argument and result types for both functions are: 93 </p> 94<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 95<li class="listitem"> 96 Source is OutputStreamable, meaning that an <code class="computeroutput"><span class="keyword">operator</span><span class="special"><<</span></code> is defined that takes a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wostream</span></code> 97 object on the left hand side and an instance of the argument type on 98 the right. 99 </li> 100<li class="listitem"> 101 Target is InputStreamable, meaning that an <code class="computeroutput"><span class="keyword">operator</span><span class="special">>></span></code> is defined that takes a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wistream</span></code> 102 object on the left hand side and an instance of the result type on the 103 right. 104 </li> 105<li class="listitem"> 106 Target is CopyConstructible [20.1.3]. 107 </li> 108<li class="listitem"> 109 Target is DefaultConstructible, meaning that it is possible to default-initialize 110 an object of that type [8.5, 20.1.4]. 111 </li> 112</ul></div> 113<p> 114 The character type of the underlying stream is assumed to be <code class="computeroutput"><span class="keyword">char</span></code> unless either the <code class="computeroutput"><span class="identifier">Source</span></code> 115 or the <code class="computeroutput"><span class="identifier">Target</span></code> requires wide-character 116 streaming, in which case the underlying stream uses <code class="computeroutput"><span class="keyword">wchar_t</span></code>. 117 Following types also can use <code class="computeroutput"><span class="keyword">char16_t</span></code> 118 or <code class="computeroutput"><span class="keyword">char32_t</span></code> for wide-character 119 streaming: 120 </p> 121<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 122<li class="listitem"> 123 Single character: <code class="computeroutput"><span class="keyword">char16_t</span></code>, 124 <code class="computeroutput"><span class="keyword">char32_t</span></code> 125 </li> 126<li class="listitem"> 127 Arrays of characters: <code class="computeroutput"><span class="keyword">char16_t</span> 128 <span class="special">*</span></code>, <code class="computeroutput"><span class="keyword">char32_t</span> 129 <span class="special">*</span></code>, <code class="computeroutput"><span class="keyword">const</span> 130 <span class="keyword">char16_t</span> <span class="special">*</span></code>, 131 <code class="computeroutput"><span class="keyword">const</span> <span class="keyword">char32_t</span> 132 <span class="special">*</span></code> 133 </li> 134<li class="listitem"> 135 Strings: <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span></code>, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">containers</span><span class="special">::</span><span class="identifier">basic_string</span></code> 136 </li> 137<li class="listitem"> 138 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">iterator_range</span><span class="special"><</span><span class="identifier">WideCharPtr</span><span class="special">></span></code>, 139 where <code class="computeroutput"><span class="identifier">WideCharPtr</span></code> is 140 a pointer to wide-character or pointer to const wide-character 141 </li> 142<li class="listitem"> 143 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special"><</span><span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">></span></code> 144 and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special"><</span><span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">></span></code>, 145 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">></span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">></span></code> 146 </li> 147</ul></div> 148<div class="important"><table border="0" summary="Important"> 149<tr> 150<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td> 151<th align="left">Important</th> 152</tr> 153<tr><td align="left" valign="top"> 154<p> 155 Many compilers and runtime libraries fail to make conversions using new 156 Unicode characters. Make sure that the following code compiles and outputs 157 nonzero values, before using new types: 158</p> 159<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> 160 <span class="special"><<</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">u32string</span><span class="special">>(</span><span class="number">1.0</span><span class="special">).</span><span class="identifier">size</span><span class="special">()</span> 161 <span class="special"><<</span> <span class="string">" "</span> 162 <span class="special"><<</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">u16string</span><span class="special">>(</span><span class="number">1.0</span><span class="special">).</span><span class="identifier">size</span><span class="special">();</span> 163</pre> 164<p> 165 </p> 166</td></tr> 167</table></div> 168<p> 169 Where a higher degree of control is required over conversions, <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span></code> 170 and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstringstream</span></code> offer a more appropriate 171 path. Where non-stream-based conversions are required, <code class="computeroutput"><span class="identifier">lexical_cast</span></code> 172 is the wrong tool for the job and is not special-cased for such scenarios. 173 </p> 174</div> 175<div class="section"> 176<div class="titlepage"><div><div><h3 class="title"> 177<a name="boost_lexical_cast.synopsis.bad_lexical_cast"></a><a class="link" href="synopsis.html#boost_lexical_cast.synopsis.bad_lexical_cast" title="bad_lexical_cast">bad_lexical_cast</a> 178</h3></div></div></div> 179<p> 180</p> 181<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">bad_lexical_cast</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">bad_cast</span> 182<span class="special">{</span> 183<span class="keyword">public</span><span class="special">:</span> 184 <span class="special">...</span> <span class="comment">// same member function interface as std::exception</span> 185<span class="special">};</span> 186</pre> 187<p> 188 Exception used to indicate runtime lexical_cast failure. 189 </p> 190</div> 191<div class="section"> 192<div class="titlepage"><div><div><h3 class="title"> 193<a name="boost_lexical_cast.synopsis.try_lexical_convert"></a><a class="link" href="synopsis.html#boost_lexical_cast.synopsis.try_lexical_convert" title="try_lexical_convert">try_lexical_convert</a> 194</h3></div></div></div> 195<p> 196 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span></code> remains the main interface 197 for lexical conversions. It must be used by default in most cases. However 198 some developers wish to make their own conversion functions, reusing all 199 the optimizations of the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span></code>. 200 That's where the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">conversion</span><span class="special">::</span><span class="identifier">try_lexical_convert</span></code> function steps in. 201 </p> 202<p> 203 <code class="computeroutput"><span class="identifier">try_lexical_convert</span></code> returns 204 <code class="computeroutput"><span class="keyword">true</span></code> if conversion succeeded, 205 otherwise returns <code class="computeroutput"><span class="keyword">false</span></code>. If 206 conversion failed and <code class="computeroutput"><span class="keyword">false</span></code> 207 was returned, state of <code class="computeroutput"><span class="identifier">result</span></code> 208 output variable is undefined. 209 </p> 210<p> 211 Actually, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span></code> is implemented using <code class="computeroutput"><span class="identifier">try_lexical_convert</span></code>: 212</p> 213<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Source</span><span class="special">></span> 214<span class="keyword">inline</span> <span class="identifier">Target</span> <span class="identifier">lexical_cast</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Source</span> <span class="special">&</span><span class="identifier">arg</span><span class="special">)</span> 215<span class="special">{</span> 216 <span class="identifier">Target</span> <span class="identifier">result</span><span class="special">;</span> 217 218 <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">conversion</span><span class="special">::</span><span class="identifier">try_lexical_convert</span><span class="special">(</span><span class="identifier">arg</span><span class="special">,</span> <span class="identifier">result</span><span class="special">))</span> 219 <span class="keyword">throw</span> <span class="identifier">bad_lexical_cast</span><span class="special">();</span> 220 221 <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span> 222<span class="special">}</span> 223</pre> 224<p> 225 </p> 226<p> 227 <code class="computeroutput"><span class="identifier">try_lexical_convert</span></code> relaxes 228 the CopyConstructible and DefaultConstructible requirements for <code class="computeroutput"><span class="identifier">Target</span></code> type. Following requirements for 229 <code class="computeroutput"><span class="identifier">Target</span></code> and <code class="computeroutput"><span class="identifier">Source</span></code> remain: 230 </p> 231<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 232<li class="listitem"> 233 Source must be OutputStreamable, meaning that an <code class="computeroutput"><span class="keyword">operator</span><span class="special"><<</span></code> is defined that takes a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wostream</span></code> 234 object on the left hand side and an instance of the argument type on 235 the right. 236 </li> 237<li class="listitem"> 238 Target must be InputStreamable, meaning that an <code class="computeroutput"><span class="keyword">operator</span><span class="special">>></span></code> is defined that takes a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wistream</span></code> 239 object on the left hand side and an instance of the result type on the 240 right. 241 </li> 242</ul></div> 243</div> 244</div> 245<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 246<td align="left"></td> 247<td align="right"><div class="copyright-footer">Copyright © 2000-2005 Kevlin Henney<br>Copyright © 2006-2010 Alexander Nasonov<br>Copyright © 2011-2020 Antony Polukhin<p> 248 Distributed under the Boost Software License, Version 1.0. (See accompanying 249 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>) 250 </p> 251</div></td> 252</tr></table> 253<hr> 254<div class="spirit-nav"> 255<a accesskey="p" href="examples.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_lexical_cast.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="frequently_asked_questions.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 256</div> 257</body> 258</html> 259
