<HTML><HEAD><TITLE>N2408=07-0268, Simple Numeric Access</TITLE></HEAD><BODY>



<CENTER>

<H1><A NAME="Simple Numeric Access">Simple Numeric Access Revision 2</A></H1>

</CENTER>



<TABLE ALIGN="RIGHT" CELLSPACING="0" CELLPADDING="0">

<TR>

<TD ALIGN="RIGHT"><B><I>Document number:</I></B></TD>

<TD>&nbsp; N2408=07-0268</TD>

</TR>

<TR>

<TD ALIGN="RIGHT"><B><I>Date:</I></B></TD>

<TD>&nbsp; 2007-09-07</TD>

</TR>

<TR>

<TD ALIGN="RIGHT"><B><I>Project:</I></B></TD>

<TD>&nbsp; Programming Language C++</TD>

</TR>

<TR>

<TD ALIGN="RIGHT"><B><I>Reference:</I></B></TD>

<TD>&nbsp; ISO/IEC IS 14882:2003(E)</TD>

</TR>

<TR>

<TD ALIGN="RIGHT"><B><I>Reply to:</I></B></TD>

<TD>&nbsp; Pete Becker</TD>

</TR>

<TR>

<TD></TD>

<TD>&nbsp; Roundhouse Consulting, Ltd.</TD>

</TR>

<TR>

<TD></TD>

<TD>&nbsp; pete@versatilecoding.com</TD>

</TR>

</TABLE>

<BR CLEAR="ALL">



<HR>



<H2>Changes since N1982=06-0052</H2>



<UL>

<LI>Changed <CODE>string&amp;</CODE> arguments to <CODE>const string&amp;</CODE>

and <CODE>wstring&amp;</CODE> arguments to <CODE>const wstring&amp;</CODE>.

Removed the requirement to erase the converted characters.

This supports the common situation of simply needing to convert text into

a numeric value:

<PRE><CODE>    std::string str("1234");

    std::stoi(text);	// converts contents of str to int

    std::stoi("1234");	// converts "1234" to int

</CODE></PRE>

</LI>

<LI>Added a second argument, of type <CODE>std::string::size_type*</CODE>,

with a default value of 0, to the functions taking <CODE>const string&amp;</CODE>

and <CODE>const wstring&amp;</CODE>.

This supports more sophisticated parsing, by allowing the user to ask for the

offset of the beginning of the unconverted remainder of the string.

</LI>

</UL>



<P>My thanks to PJ Plauger, who reviewed N1982, suggested these changes, and caught

an egregious error in an earlier draft of this document.</P>



<H2><A NAME=Proposed Wording>Proposed Wording</H2>



<P>Add the following to [lib.string.classes] at the end of the "Header &lt;string&gt;

synopsis":</P>



<BLOCKQUOTE>

<CODE><PRE>int stoi(const string&amp; str, size_t *idx = 0, int base = 10);

long stol(const string&amp; str, size_t *idx = 0, int base = 10);

unsigned long stoul(const string&amp; str, size_t *idx = 0, int base = 10);

long long stoll(const string&amp; str, size_t *idx = 0, int base = 10);

unsigned long long stoull(const string&amp; str, size_t *idx = 0, int base = 10);

float stof(const string&amp; str, size_t *idx = 0);

double stod(const string&amp; str, size_t *idx = 0);

long double stold(const string&amp; str, size_t *idx = 0);

string to_string(long long val);

string to_string(unsigned long long val);

string to_string(long double val);</CODE></PRE>

</BLOCKQUOTE>



<BLOCKQUOTE>

<CODE><PRE>int stoi(const wstring&amp; str, size_t *idx = 0, int base = 10);

long stol(const wstring&amp; str, size_t *idx = 0, int base = 10);

unsigned long stoul(const wstring&amp; str, size_t *idx = 0, int base = 10);

long long stoll(const wstring&amp; str, size_t *idx = 0, int base = 10);

unsigned long long stoull(const wstring&amp; str, size_t *idx = 0, int base = 10);

float stof(const wstring&amp; str, size_t *idx = 0);

double stod(const wstring&amp; str, size_t *idx = 0);

long double stold(const wstring&amp; str, size_t *idx = 0);

wstring to_wstring(long long val);

wstring to_wstring(unsigned long long val);

wstring to_wstring(long double val);</CODE></PRE>

</BLOCKQUOTE>



Add the following as a new subclause of [string.ops], with the title &quot;Numeric conversions&quot;:



<BLOCKQUOTE>

<PRE><CODE>int stoi(const string&amp; str, size_t *idx = 0, int base = 10);

long stol(const string&amp; str, size_t *idx = 0, int base = 10);

unsigned long stoul(const string&amp; str, size_t *idx = 0, int base = 10);

long long stoll(const string&amp; str, size_t *idx = 0, int base = 10);

unsigned long long stoull(const string&amp; str, size_t *idx = 0, int base = 10);</CODE></PRE>



<P><I>Effects:</I> the first two functions call <CODE>strtol(str.c_str(), ptr, base)</CODE>,

and the last three functions call <CODE>strtoul(str.c_str(), ptr, base)</CODE>,

<CODE>strtoll(str.c_str(), ptr, base)</CODE>,

and <CODE>strtoull(str.c_str(), ptr, base)</CODE>, respectively.

Each function

returns the converted result, if any.

The argument <CODE>ptr</CODE> designates a pointer to an object internal to the

function that is used to determine what to store at <CODE>*idx</CODE>.

If the function does not throw an exception

and <CODE>idx != 0</CODE>, the function stores

in <CODE>*idx</CODE> the index of the first unconverted element of <CODE>str</CODE>.</P>



<P><I>Returns:</I> the converted result.</P>



<P><I>Throws:</I> <CODE>invalid_argument</CODE> if <CODE>strtol</CODE>, <CODE>strtoul</CODE>,

<CODE>strtoll</CODE>, or <CODE>strtoull</CODE> reports that no conversion could be performed.

Throws <CODE>out_of_range</CODE> if the converted value is outside the range of representable

values for the return type.</P>



<PRE><CODE>float stof(const string&amp; str, size_t *idx = 0);

double stod(const string&amp; str, size_t *idx = 0);

long double stold(const string&amp; str, size_t *idx = 0);</CODE></PRE>



<P><I>Effects:</I> the first two functions call

<CODE>strtod(str.c_str(), ptr)</CODE> and the third function calls

<CODE>strtold(str.c_str(), ptr)</CODE>. 

Each function

returns the converted result, if any.

The argument <CODE>ptr</CODE> designates a pointer to an object internal to the

function that is used to determine what to store at <CODE>*idx</CODE>.

If the function does not throw an exception

and <CODE>idx != 0</CODE>, the function stores

in <CODE>*idx</CODE> the index of the first unconverted element of <CODE>str</CODE>.</P>



<P><I>Returns:</I> the converted result.</P>



<P><I>Throws:</I> <CODE>invalid_argument</CODE> if <CODE>strtod</CODE>

or <CODE>strtold</CODE> reports that no conversion could be performed.

Throws <CODE>out_of_range</CODE> if <CODE>strtod</CODE> or

<CODE>strtold</CODE> sets <CODE>errno</CODE> to <CODE>ERANGE</CODE>.</P>



<PRE><CODE>string to_string(long long val);

string to_string(unsigned long long val);

string to_string(long double val);</CODE></PRE>



<P><I>Returns:</I> each function returns a <CODE>string</CODE> object holding the

character representation of the value of its argument that would be generated by calling

<CODE>sprintf(buf, fmt, val)</CODE> with a format specifier of

<CODE>&quot;%lld&quot;</CODE>, <CODE>&quot;%ulld&quot;</CODE>, or

<CODE>&quot;%f&quot;</CODE>, respectively.</P>



<P><I>Throws:</I> nothing.</P>

</BLOCKQUOTE>



<BLOCKQUOTE>

<PRE><CODE>int stoi(const wstring&amp; str, size_t *idx = 0, int base = 10);

long stol(const wstring&amp; str, size_t *idx = 0, int base = 10);

unsigned long stoul(const wstring&amp; str, size_t *idx = 0, int base = 10);

long long stoll(const wstring&amp; str, size_t *idx = 0, int base = 10);

unsigned long long stoull(const wstring&amp; str, size_t *idx = 0, int base = 10);</CODE></PRE>



<P><I>Effects:</I> the first two functions call <CODE>wcstol(str.c_str(), ptr, base)</CODE>,

and the last three functions call <CODE>wcstoul(str.c_str(), ptr, base)</CODE>,

<CODE>wcstoll(str.c_str(), ptr, base)</CODE>,

and <CODE>wcstoull(str.c_str(), ptr, base)</CODE>, respectively.

Each function

returns the converted result, if any.

The argument <CODE>ptr</CODE> designates a pointer to an object internal to the

function that is used to determine what to store at <CODE>*idx</CODE>.

If the function does not throw an exception

and <CODE>idx != 0</CODE>, the function stores

in <CODE>*idx</CODE> the index of the first unconverted element of <CODE>str</CODE>.</P>



<P><I>Returns:</I> the converted result.</P>



<P><I>Throws:</I> <CODE>invalid_argument</CODE> if <CODE>wcstol</CODE>, <CODE>wcstoul</CODE>,

<CODE>wcstoll</CODE>, or <CODE>wcstoull</CODE> reports that no conversion could be performed.

Throws <CODE>out_of_range</CODE> if the converted value is outside the range of representable

values for the return type.</P>



<PRE><CODE>float stof(const wstring&amp; str, size_t *idx = 0);

double stod(const wstring&amp; str, size_t *idx = 0);

long double stold(const wstring&amp; str, size_t *idx = 0);</CODE></PRE>



<P><I>Effects:</I> the first two functions call

<CODE>wcstod(str.c_str(), ptr)</CODE> and the third function calls

<CODE>wcstold(str.c_str(), ptr)</CODE>.

Each function

returns the converted result, if any.

The argument <CODE>ptr</CODE> designates a pointer to an object internal to the

function that is used to determine what to store at <CODE>*idx</CODE>.

If the function does not throw an exception

and <CODE>idx != 0</CODE>, the function stores

in <CODE>*idx</CODE> the index of the first unconverted element of <CODE>str</CODE>.</P>



<P><I>Returns:</I> the converted result.</P>



<P><I>Throws:</I> <CODE>invalid_argument</CODE> if <CODE>wcstod</CODE>

or <CODE>wcstold</CODE> reports that no conversion could be performed.

Throws <CODE>out_of_range</CODE> if <CODE>wcstod</CODE> or

<CODE>wcstold</CODE> sets <CODE>errno</CODE> to <CODE>ERANGE</CODE>.</P>



<PRE><CODE>wstring to_wstring(long long val);

wstring to_wstring(unsigned long long val);

wstring to_wstring(long double val);</CODE></PRE>



<P><I>Returns:</I> each function returns a <CODE>wstring</CODE> object holding the

character representation of the value of its argument that would be generated by calling

<CODE>wsprintf(buf, fmt, val)</CODE> with a format specifier of

<CODE>L&quot;%lld&quot;</CODE>, <CODE>L&quot;%ulld&quot;</CODE>, or

<CODE>L&quot;%f&quot;</CODE>, respectively.</P>



<P><I>Throws:</I> nothing.</P>

</BLOCKQUOTE>



<HR>



</BODY></HTML>

