generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
main
boost/doc/html/boost_lexical_cast/synopsis.html

259 lines
24 KiB
HTML
Raw Permalink Normal View History

[DEV] add v1.76.0
2021-10-05 21:37:46 +02:00
<!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=UTF-8">
<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">&lt;</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">&gt;</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">&amp;</span> <span class="identifier">arg</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">&gt;</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">&lt;</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">&gt;</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">&amp;</span> <span class="identifier">arg</span><span class="special">,</span> <span class="identifier">Target</span><span class="special">&amp;</span> <span class="identifier">result</span><span class="special">);</span>
<span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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">&amp;</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">&lt;</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">&gt;</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">&amp;</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">&gt;&gt;</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">&lt;</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">&gt;</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">&lt;&lt;</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">&gt;&gt;</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">&lt;</span><span class="identifier">WideCharPtr</span><span class="special">&gt;</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">&lt;</span><span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">&gt;</span></code>
and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">&gt;</span></code>,
<code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">&gt;</span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">&gt;</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">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">u32string</span><span class="special">&gt;(</span><span class="number">1.0</span><span class="special">).</span><span class="identifier">size</span><span class="special">()</span>
<span class="special">&lt;&lt;</span> <span class="string">" "</span>
<span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">u16string</span><span class="special">&gt;(</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">&lt;</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">&gt;</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">&amp;</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">&lt;&lt;</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">&gt;&gt;</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-2021 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>
Reference in New Issue Copy Permalink