Simple Numeric Access Revision 2

*Document number:*	N2408=07-0268
*Date:*	2007-09-07
*Project:*	Programming Language C++
*Reference:*	ISO/IEC IS 14882:2003(E)
*Reply to:*	Pete Becker
	Roundhouse Consulting, Ltd.
	pete@versatilecoding.com

Changes since N1982=06-0052

Changed string& arguments to const string& and wstring& arguments to const wstring&. Removed the requirement to erase the converted characters. This supports the common situation of simply needing to convert text into a numeric value:
```
    std::string str("1234");

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

    std::stoi("1234");	// converts "1234" to int
```
Added a second argument, of type std::string::size_type*, with a default value of 0, to the functions taking const string& and const wstring&. This supports more sophisticated parsing, by allowing the user to ask for the offset of the beginning of the unconverted remainder of the string.

My thanks to PJ Plauger, who reviewed N1982, suggested these changes, and caught an egregious error in an earlier draft of this document.

Proposed Wording

Add the following to [lib.string.classes] at the end of the "Header <string> synopsis":

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

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

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

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

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

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

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

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

string to_string(long long val);

string to_string(unsigned long long val);

string to_string(long double val);

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

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

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

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

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

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

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

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

wstring to_wstring(long long val);

wstring to_wstring(unsigned long long val);

wstring to_wstring(long double val);

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

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

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

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

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

unsigned long long stoull(const string& str, size_t *idx = 0, int base = 10);
Effects: the first two functions call strtol(str.c_str(), ptr, base), and the last three functions call strtoul(str.c_str(), ptr, base), strtoll(str.c_str(), ptr, base), and strtoull(str.c_str(), ptr, base), respectively. Each function returns the converted result, if any. The argument ptr designates a pointer to an object internal to the function that is used to determine what to store at *idx. If the function does not throw an exception and idx != 0, the function stores in *idx the index of the first unconverted element of str.

Returns: the converted result.

Throws: invalid_argument if strtol, strtoul, strtoll, or strtoull reports that no conversion could be performed. Throws out_of_range if the converted value is outside the range of representable values for the return type.
float stof(const string& str, size_t *idx = 0);

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

long double stold(const string& str, size_t *idx = 0);
Effects: the first two functions call strtod(str.c_str(), ptr) and the third function calls strtold(str.c_str(), ptr). Each function returns the converted result, if any. The argument ptr designates a pointer to an object internal to the function that is used to determine what to store at *idx. If the function does not throw an exception and idx != 0, the function stores in *idx the index of the first unconverted element of str.

Returns: the converted result.

Throws: invalid_argument if strtod or strtold reports that no conversion could be performed. Throws out_of_range if strtod or strtold sets errno to ERANGE.
string to_string(long long val);

string to_string(unsigned long long val);

string to_string(long double val);
Returns: each function returns a string object holding the character representation of the value of its argument that would be generated by calling sprintf(buf, fmt, val) with a format specifier of "%lld", "%ulld", or "%f", respectively.

Throws: nothing.

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

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

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

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

unsigned long long stoull(const wstring& str, size_t *idx = 0, int base = 10);
Effects: the first two functions call wcstol(str.c_str(), ptr, base), and the last three functions call wcstoul(str.c_str(), ptr, base), wcstoll(str.c_str(), ptr, base), and wcstoull(str.c_str(), ptr, base), respectively. Each function returns the converted result, if any. The argument ptr designates a pointer to an object internal to the function that is used to determine what to store at *idx. If the function does not throw an exception and idx != 0, the function stores in *idx the index of the first unconverted element of str.

Returns: the converted result.

Throws: invalid_argument if wcstol, wcstoul, wcstoll, or wcstoull reports that no conversion could be performed. Throws out_of_range if the converted value is outside the range of representable values for the return type.
float stof(const wstring& str, size_t *idx = 0);

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

long double stold(const wstring& str, size_t *idx = 0);
Effects: the first two functions call wcstod(str.c_str(), ptr) and the third function calls wcstold(str.c_str(), ptr). Each function returns the converted result, if any. The argument ptr designates a pointer to an object internal to the function that is used to determine what to store at *idx. If the function does not throw an exception and idx != 0, the function stores in *idx the index of the first unconverted element of str.

Returns: the converted result.

Throws: invalid_argument if wcstod or wcstold reports that no conversion could be performed. Throws out_of_range if wcstod or wcstold sets errno to ERANGE.
wstring to_wstring(long long val);

wstring to_wstring(unsigned long long val);

wstring to_wstring(long double val);
Returns: each function returns a wstring object holding the character representation of the value of its argument that would be generated by calling wsprintf(buf, fmt, val) with a format specifier of L"%lld", L"%ulld", or L"%f", respectively.

Throws: nothing.