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