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

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.