boostorg/conversion
1
0
Fork 1
mirror of https://github.com/boostorg/conversion.git synced 2025-08-03 14:34:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

Updated Changes section

Browse Source 
[SVN r17922]
This commit is contained in:
Terje Slettebø
2003-03-14 20:32:51 +00:00
parent 3f452717cf
commit aad1bfda73
1 changed files with 47 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
lexical_cast.htm
View File

@@ -1,3 +1,4 @@
<!-- saved from url=(0022)http://internet.e-mail -->
<!doctype html public "-//W3C//DTD HTML Transitional 4.0//EN">
<html>
<head>
@@ -8,7 +9,7 @@
<body bgcolor="#FFFFFF" text="#000000">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" width="277" height="86">Header
<a href="../../boost/lexical_cast.hpp">boost/lexical_cast.hpp</a></h1>
<ul>
<ul type="square">
<li>
<a href="#motivation">Motivation</a></li>
<li>
@@ -19,6 +20,8 @@
<a href="#lexical_cast"><code>lexical_cast</code></a></li>
<li>
<a href="#bad_lexical_cast"><code>bad_lexical_cast</code></a></li>
<li>
<a href="#changes">Changes</a></li>
</ul>
<hr>
<h2><a name="motivation">Motivation</a></h2>
@@ -34,7 +37,7 @@
<p>
For instance, there are a number of limitations with the family of standard C
functions typified by <code>atoi</code>:
<ul>
<ul type="square">
<li>
Conversion is supported in one direction only: from text to internal data type.
Converting the other way using the C library requires either the inconvenience
@@ -75,14 +78,12 @@
offered by the default behavior of <code>lexical_cast</code>, the conventional <code>
stringstream</code> approach is recommended. Where the conversions are
numeric to numeric, <code><a href="cast.htm#numeric_cast">numeric_cast</a></code>
may offer more reasonable behavior than <code>lexical_cast</code>
.
may offer more reasonable behavior than <code>lexical_cast</code>.
<p>
For a good discussion of the options and issues involved in string-based
formatting, including comparison of <code>stringstream</code>, <code>lexical_cast</code>,
and others, see Herb Sutter's article, <a href="http://www.gotw.ca/publications/mill19.htm">
<i>The String Formatters of Manor Farm</i></a>
.
<i>The String Formatters of Manor Farm</i></a>.
<p>
<hr>
<h2><a name="examples">Examples</a></h2>
@@ -141,41 +142,46 @@ namespace boost
template&lt;typename Target, typename Source&gt;
Target lexical_cast(Source arg);
</pre>
</blockquote>Returns the result of streaming <code>arg</code> into a <code>std::stringstream</code>
and then out as a <code>Target</code> object. Note that spaces are significant
in any conversion and are not skipped. If the conversion is unsuccessful, a <a href="#bad_lexical_cast">
<code>bad_lexical_cast</code></a>
exception is thrown.
</blockquote>Returns the result of streaming <code>arg</code> into a
standard library string-based stream and then out as a <code>Target</code> object.
Where <code>Target</code> is either <code>std::string</code>
or <code>std::wstring</code>, stream extraction takes the whole content
of the string, including spaces, rather than relying on the default
<code>operator&gt;&gt;</code> behavior.
If the conversion is unsuccessful, a <a href="#bad_lexical_cast">
<code>bad_lexical_cast</code></a> exception is thrown.
<p>
The requirements on the argument and result types are:
<ul>
<ul type="square">
<li>
<code>Source</code> is <i>OutputStreamable</i>, meaning that an <code>operator&lt;&lt;</code>
is defined that takes a <code>std::ostream</code> or <code>std::wostream</code> object on the
left hand side and an instance of the argument type on the right.
</li>
<li>
Both <code>Source</code> and <code>Target</code> are <i>CopyConstructible</i> [20.1.3].
</li>
<li>
<code>Target</code> is <i>InputStreamable</i>, meaning that an <code>operator&gt;&gt;</code>
is defined that takes a <code>std::istream</code> or <code>std::wistream</code> object on the left hand side
and an instance of the result type on the right.
</li>
<li>
Both <code>Source</code> and <code>Target</code> are <i>CopyConstructible</i> [20.1.3].
</li>
<li>
<code>Target</code> is <i>DefaultConstructible</i>, meaning that it is possible
to <i>default-initialize</i> an object of that type [8.5, 20.1.4].
</li>
</ul>
The character type of the underlying stream is assumed to be <code>char</code> unless
the either the <code>Source</code> or the <code>Target</code> type is <code>wchar_t</code>
or a wide-character string type &#151; either <code>wchar_t *</code> or <code>std::wstring</code> &#151;
in which case <code>wchar_t</code> is used.
either the <code>Source</code> or the <code>Target</code> requires wide-character
streaming, in which case the underlying stream uses <code>wchar_t</code>.
<code>Source</code> types that require wide-character streaming are <code>wchar_t</code>,
<code>wchar_t *</code>, and <code>std::wstring</code>. <code>Target</code> types that
require wide-character streaming are <code>wchar_t</code> and <code>std::wstring</code>.
<p>
Where a higher degree of control is required over conversions, <code>std::stringstream</code>
and <code>std::wstringstream</code> offer a more appropriate path. Where non-stream-based conversions are
required, <code>lexical_cast</code>
is the wrong tool for the job, and is not special-cased for such scenarios.
is the wrong tool for the job and is not special-cased for such scenarios.
<p>
<hr>
<h2><a name="bad_lexical_cast"><code>bad_lexical_cast</code></a></h2>
@@ -189,7 +195,28 @@ public:
</pre>
</blockquote>Exception used to indicate runtime <a href="#lexical_cast"><code>lexical_cast</code></a>
failure.
<p>
<hr>
<h2><a name="changes">Changes</a></h2>
<ul type="square">
<li>The previous version of <code>lexical_cast</code> used the default stream precision for reading
and writing floating-point numbers. For numerics that have a corresponding specialization of
<code>std::numeric_limits</code>, the current version now chooses a precision to match.
<li>The previous version of <code>lexical_cast</code> did not support conversion to or from any
wide-character-based types. For compilers with full language and library support for wide characters,
<code>lexical_cast</code> now supports conversions from <code>wchar_t</code>, <code>wchar_t *</code>,
and <code>std::wstring</code> and to <code>wchar_t</code> and <code>std::wstring</code>.
<li>The previous version of <code>lexical_cast</code> assumed that the conventional stream extractor
operators were sufficient for reading values. However, string I/O is asymmetric, with the result
that spaces play the role of I/O separators rather than string content. The current version fixes
this error for <code>std::string</code> and, where supported, <code>std::wstring</code>:
<code>lexical_cast&lt;std::string&gt;("Hello, World")</code> succeeds instead of failing with
a <code>bad_lexical_cast</code> exception.
<li>The previous version of <code>lexical_cast</code> allowed unsafe and meaningless conversions to
pointers. The current version now throws a <code>bad_lexical_cast</code> for conversions to pointers:
<code>lexical_cast&lt;char *&gt;("Goodbye, World")</code> now throws an exception instead of
causing undefined behavior.
</ul>
<p>
<hr>
<div align="right"><small><i>&copy; Copyright Kevlin Henney, 2000&#150;2003</i></small></div>
</body>