From aad1bfda73a0bfe294bd8697f4137e1c56b3de9c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Terje=20Sletteb=C3=B8?= <tslettebo@broadpark.no>
Date: Fri, 14 Mar 2003 20:32:51 +0000
Subject: [PATCH] Updated Changes section

[SVN r17922]
---
 lexical_cast.htm | 67 +++++++++++++++++++++++++++++++++---------------
 1 file changed, 47 insertions(+), 20 deletions(-)
diff --git a/lexical_cast.htm b/lexical_cast.htm
index 6b52fb5..1215a52 100644
--- a/lexical_cast.htm
+++ b/lexical_cast.htm
@@ -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>
