[category.numeric] (original) (raw)
28 Text processing library [text]
28.3 Localization library [localization]
28.3.4 Standard locale categories [locale.categories]
28.3.4.3 The numeric category [category.numeric]
28.3.4.3.1 General [category.numeric.general]
28.3.4.3.2 Class template num_get [locale.num.get]
28.3.4.3.2.1 General [locale.num.get.general]
28.3.4.3.2.2 Members [facet.num.get.members]
28.3.4.3.2.3 Virtual functions [facet.num.get.virtuals]
28.3.4.3.3 Class template num_put [locale.nm.put]
28.3.4.3.3.1 General [locale.nm.put.general]
28.3.4.3.3.2 Members [facet.num.put.members]
28.3.4.3.3.3 Virtual functions [facet.num.put.virtuals]
28.3.4.3.1 General [category.numeric.general]
The classes num_get<> and num_put<>handle numeric formatting and parsing.
Virtual functions are provided for several numeric types.
Implementations may (but are not required to) delegate extraction of smaller types to extractors for larger types.[223](#footnote-223 "Parsing "-1" correctly into, e.g., an unsigned short requires that the corresponding member get() at least extract the sign before delegating.")
All specifications of member functions for num_put and num_getin the subclauses of [category.numeric] only apply to the specializations required in Tables 91and 92 ([locale.category]), namelynum_get<char>,num_get<wchar_t>,num_get<C, InputIterator>,num_put<char>,num_put<wchar_t>, andnum_put<C, OutputIterator>.
These specializations refer to the ios_base& argument for formatting specifications ([locale.categories]), and to its imbued locale for the numpunct<> facet to identify all numeric punctuation preferences, and also for the ctype<> facet to perform character classification.
28.3.4.3.2 Class template num_get [locale.num.get]
28.3.4.3.2.1 General [locale.num.get.general]
namespace std { template<class charT, class InputIterator = istreambuf_iterator<charT>> class num_get : public locale::facet { public: using char_type = charT;using iter_type = InputIterator;explicit num_get(size_t refs = 0); iter_type get(iter_type in, iter_type end, ios_base&, ios_base::iostate& err, bool& v) const; iter_type get(iter_type in, iter_type end, ios_base&, ios_base::iostate& err, long& v) const; iter_type get(iter_type in, iter_type end, ios_base&, ios_base::iostate& err, long long& v) const; iter_type get(iter_type in, iter_type end, ios_base&, ios_base::iostate& err, unsigned short& v) const; iter_type get(iter_type in, iter_type end, ios_base&, ios_base::iostate& err, unsigned int& v) const; iter_type get(iter_type in, iter_type end, ios_base&, ios_base::iostate& err, unsigned long& v) const; iter_type get(iter_type in, iter_type end, ios_base&, ios_base::iostate& err, unsigned long long& v) const; iter_type get(iter_type in, iter_type end, ios_base&, ios_base::iostate& err, float& v) const; iter_type get(iter_type in, iter_type end, ios_base&, ios_base::iostate& err, double& v) const; iter_type get(iter_type in, iter_type end, ios_base&, ios_base::iostate& err, long double& v) const; iter_type get(iter_type in, iter_type end, ios_base&, ios_base::iostate& err, void*& v) const;static locale::id id;protected: ~num_get();virtual iter_type do_get(iter_type, iter_type, ios_base&, ios_base::iostate& err, bool& v) const;virtual iter_type do_get(iter_type, iter_type, ios_base&, ios_base::iostate& err, long& v) const;virtual iter_type do_get(iter_type, iter_type, ios_base&, ios_base::iostate& err, long long& v) const;virtual iter_type do_get(iter_type, iter_type, ios_base&, ios_base::iostate& err, unsigned short& v) const;virtual iter_type do_get(iter_type, iter_type, ios_base&, ios_base::iostate& err, unsigned int& v) const;virtual iter_type do_get(iter_type, iter_type, ios_base&, ios_base::iostate& err, unsigned long& v) const;virtual iter_type do_get(iter_type, iter_type, ios_base&, ios_base::iostate& err, unsigned long long& v) const;virtual iter_type do_get(iter_type, iter_type, ios_base&, ios_base::iostate& err, float& v) const;virtual iter_type do_get(iter_type, iter_type, ios_base&, ios_base::iostate& err, double& v) const;virtual iter_type do_get(iter_type, iter_type, ios_base&, ios_base::iostate& err, long double& v) const;virtual iter_type do_get(iter_type, iter_type, ios_base&, ios_base::iostate& err, void*& v) const;};}
The facet num_get is used to parse numeric values from an input sequence such as an istream.
28.3.4.3.2.2 Members [facet.num.get.members]
iter_type get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, bool& val) const; iter_type get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, long& val) const; iter_type get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, long long& val) const; iter_type get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, unsigned short& val) const; iter_type get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, unsigned int& val) const; iter_type get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, unsigned long& val) const; iter_type get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, unsigned long long& val) const; iter_type get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, float& val) const; iter_type get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, double& val) const; iter_type get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, long double& val) const; iter_type get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, void*& val) const;
Returns: do_get(in, end, str, err, val).
28.3.4.3.2.3 Virtual functions [facet.num.get.virtuals]
iter_type do_get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, long& val) const; iter_type do_get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, long long& val) const; iter_type do_get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, unsigned short& val) const; iter_type do_get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, unsigned int& val) const; iter_type do_get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, unsigned long& val) const; iter_type do_get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, unsigned long long& val) const; iter_type do_get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, float& val) const; iter_type do_get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, double& val) const; iter_type do_get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, long double& val) const; iter_type do_get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, void*& val) const;
Effects: Reads characters from in, interpreting them according tostr.flags(),use_facet<ctype<charT>>(loc), anduse_facet<numpunct<charT>>(loc), where loc is str.getloc().
The details of this operation occur in three stages:
- Stage 1: Determine a conversion specifier.
- Stage 2: Extract characters from in and determine a corresponding char value for the format expected by the conversion specification determined in stage 1.
The details of the stages are presented below.
- Stage 1:
The function initializes local variables viafmtflags flags = str.flags(); fmtflags basefield = (flags & ios_base::basefield); fmtflags uppercase = (flags & ios_base::uppercase); fmtflags boolalpha = (flags & ios_base::boolalpha);
For conversion to an integral type, the function determines the integral conversion specifier as indicated in Table 95.
The table is ordered.
That is, the first line whose condition is true applies.
Table 95 — Integer conversions [tab:facet.num.get.int]🔗State stdio equivalent 🔗basefield == oct %o 🔗basefield == hex %X 🔗basefield == 0 %i 🔗signed integral type %d 🔗unsigned integral type %u For conversions to a floating-point type the specifier is %g. For conversions to void* the specifier is %p. A length modifier is added to the conversion specification, if needed, as indicated in Table 96. Table 96 — Length modifier [tab:facet.num.get.length] 🔗Type Length modifier ------------------------------------------------------- ------------------- 🔗short h 🔗unsigned short h 🔗long l 🔗unsigned long l 🔗long long ll 🔗unsigned long long ll 🔗double l 🔗long double L - Stage 2:
If in == end then stage 2 terminates.
Otherwise a charT is taken from in and local variables are initialized as if bychar_type ct = *in;char c = src[find(atoms, atoms + sizeof(src) - 1, ct) - atoms];if (ct == use_facet<numpunct<charT>>(loc).decimal_point()) c = '.';bool discard = ct == use_facet<numpunct<charT>>(loc).thousands_sep() && use_facet<numpunct<charT>>(loc).grouping().length() != 0;where the values src and atoms are defined as if by:static const char src[] = "0123456789abcdefpxABCDEFPX+-"; char_type atoms[sizeof(src)]; use_facet<ctype<charT>>(loc).widen(src, src + sizeof(src), atoms);for this value of loc.
If discard is true, then if '.' has not yet been accumulated, then the position of the character is remembered, but the character is otherwise ignored.
Otherwise, if '.' has already been accumulated, the character is discarded and Stage 2 terminates.
If it is not discarded, then a check is made to determine if c is allowed as the next character of an input field of the conversion specifier returned by Stage 1.
If so, it is accumulated.
If the character is either discarded or accumulated then in is advanced by ++inand processing returns to the beginning of stage 2.
[Example 1:
Given an input sequence of "0x1a.bp+07p",- if the conversion specifier returned by Stage 1 is %d,"0" is accumulated;
- if the conversion specifier returned by Stage 1 is %i,"0x1a" are accumulated;
- if the conversion specifier returned by Stage 1 is %g,"0x1a.bp+07" are accumulated.
In all cases, the remainder is left in the input.
— _end example_]
- Stage 3:
The sequence of chars accumulated in stage 2 (the field) is converted to a numeric value by the rules of one of the functions declared in the header :- For a signed integer value, the function strtoll.
- For an unsigned integer value, the function strtoull.
- For a float value, the function strtof.
- For a double value, the function strtod.
- For a long double value, the function strtold.
The numeric value to be stored can be one of: - zero, if the conversion function does not convert the entire field.
- the most positive (or negative) representable value, if the field to be converted to a signed integer type represents a value too large positive (or negative) to be represented in val.
- the most positive representable value, if the field to be converted to an unsigned integer type represents a value that cannot be represented in val.
- the converted value, otherwise.
The resultant numeric value is stored in val.
If the conversion function does not convert the entire field, or if the field represents a value outside the range of representable values,ios_base::failbit is assigned to err.
Digit grouping is checked.
That is, the positions of discarded separators are examined for consistency withuse_facet<numpunct<charT>>(loc).grouping().
If they are not consistent then ios_base::failbit is assigned to err.
In any case, if stage 2 processing was terminated by the test for in == endthen err |= ios_base::eofbit is performed.
iter_type do_get(iter_type in, iter_type end, ios_base& str, ios_base::iostate& err, bool& val) const;
Effects: If (str.flags() & ios_base::boolalpha) == 0then input proceeds as it would for a longexcept that if a value is being stored into val, the value is determined according to the following: If the value to be stored is 0 then false is stored.
If the value is 1 then true is stored.
Otherwise true is stored andios_base::failbit is assigned to err.
Otherwise target sequences are determined “as if” by calling the members falsename() and truename() of the facet obtained by use_facet<numpunct<charT>>(str.getloc()).
Successive characters in the range [in, end) (see [sequence.reqmts]) are obtained and matched against corresponding positions in the target sequences only as necessary to identify a unique match.
The input iterator in is compared to endonly when necessary to obtain a character.
If a target sequence is uniquely matched,val is set to the corresponding value.
Otherwise false is stored andios_base::failbit is assigned to err.
The in iterator is always left pointing one position beyond the last character successfully matched.
If val is set, then err is set to str.goodbit; or to str.eofbit if, when seeking another character to match, it is found that (in == end).
If val is not set, then err is set to str.failbit; or to (str.failbit | str.eofbit)if the reason for the failure was that (in == end).
[Example 2:
For targets true: "a" and false: "abb", the input sequence "a" yieldsval == true and err == str.eofbit; the input sequence "abc" yieldserr = str.failbit, with in ending at the 'c' element.
For targets true: "1" and false: "0", the input sequence "1" yieldsval == true and err == str.goodbit.
For empty targets (""), any input sequence yields err == str.failbit.
— _end example_]
28.3.4.3.3 Class template num_put [locale.nm.put]
28.3.4.3.3.1 General [locale.nm.put.general]
namespace std { template<class charT, class OutputIterator = ostreambuf_iterator<charT>> class num_put : public locale::facet { public: using char_type = charT;using iter_type = OutputIterator;explicit num_put(size_t refs = 0); iter_type put(iter_type s, ios_base& f, char_type fill, bool v) const; iter_type put(iter_type s, ios_base& f, char_type fill, long v) const; iter_type put(iter_type s, ios_base& f, char_type fill, long long v) const; iter_type put(iter_type s, ios_base& f, char_type fill, unsigned long v) const; iter_type put(iter_type s, ios_base& f, char_type fill, unsigned long long v) const; iter_type put(iter_type s, ios_base& f, char_type fill, double v) const; iter_type put(iter_type s, ios_base& f, char_type fill, long double v) const; iter_type put(iter_type s, ios_base& f, char_type fill, const void* v) const;static locale::id id;protected: ~num_put();virtual iter_type do_put(iter_type, ios_base&, char_type fill, bool v) const;virtual iter_type do_put(iter_type, ios_base&, char_type fill, long v) const;virtual iter_type do_put(iter_type, ios_base&, char_type fill, long long v) const;virtual iter_type do_put(iter_type, ios_base&, char_type fill, unsigned long) const;virtual iter_type do_put(iter_type, ios_base&, char_type fill, unsigned long long) const;virtual iter_type do_put(iter_type, ios_base&, char_type fill, double v) const;virtual iter_type do_put(iter_type, ios_base&, char_type fill, long double v) const;virtual iter_type do_put(iter_type, ios_base&, char_type fill, const void* v) const;};}
The facetnum_putis used to format numeric values to a character sequence such as an ostream.
28.3.4.3.3.2 Members [facet.num.put.members]
iter_type put(iter_type out, ios_base& str, char_type fill, bool val) const; iter_type put(iter_type out, ios_base& str, char_type fill, long val) const; iter_type put(iter_type out, ios_base& str, char_type fill, long long val) const; iter_type put(iter_type out, ios_base& str, char_type fill, unsigned long val) const; iter_type put(iter_type out, ios_base& str, char_type fill, unsigned long long val) const; iter_type put(iter_type out, ios_base& str, char_type fill, double val) const; iter_type put(iter_type out, ios_base& str, char_type fill, long double val) const; iter_type put(iter_type out, ios_base& str, char_type fill, const void* val) const;
Returns: do_put(out, str, fill, val).
28.3.4.3.3.3 Virtual functions [facet.num.put.virtuals]
iter_type do_put(iter_type out, ios_base& str, char_type fill, long val) const; iter_type do_put(iter_type out, ios_base& str, char_type fill, long long val) const; iter_type do_put(iter_type out, ios_base& str, char_type fill, unsigned long val) const; iter_type do_put(iter_type out, ios_base& str, char_type fill, unsigned long long val) const; iter_type do_put(iter_type out, ios_base& str, char_type fill, double val) const; iter_type do_put(iter_type out, ios_base& str, char_type fill, long double val) const; iter_type do_put(iter_type out, ios_base& str, char_type fill, const void* val) const;
Effects: Writes characters to the sequence out, formatting val as desired.
In the following description, loc names a local variable initialized aslocale loc = str.getloc();
The details of this operation occur in several stages:
- Stage 1: Determine a printf conversion specifier spec and determine the characters that would be printed by printf ([c.files]) given this conversion specifier forprintf(spec, val) assuming that the current locale is the "C" locale.
- Stage 2: Adjust the representation by converting each char determined by stage 1 to a charTusing a conversion and values returned by members of use_facet<numpunct<charT>>(loc).
- Stage 3: Determine where padding is required.
- Stage 4: Insert the sequence into the out.
Detailed descriptions of each stage follow.
- Stage 1:
The first action of stage 1 is to determine a conversion specifier.
The tables that describe this determination use the following local variables
fmtflags flags = str.flags(); fmtflags basefield = (flags & (ios_base::basefield)); fmtflags uppercase = (flags & (ios_base::uppercase)); fmtflags floatfield = (flags & (ios_base::floatfield)); fmtflags showpos = (flags & (ios_base::showpos)); fmtflags showbase = (flags & (ios_base::showbase)); fmtflags showpoint = (flags & (ios_base::showpoint));
All tables used in describing stage 1 are ordered.
That is, the first line whose condition is true applies.
A line without a condition is the default behavior when none of the earlier lines apply.
For conversion from an integral type other than a character type, the function determines the integral conversion specifier as indicated in Table 97.
Table 97 — Integer conversions [tab:facet.num.put.int]🔗State stdio equivalent 🔗basefield == ios_base::oct %o 🔗(basefield == ios_base::hex) && !uppercase %x 🔗(basefield == ios_base::hex) %X 🔗for a signed integral type %d 🔗for an unsigned integral type %u For conversion from a floating-point type, the function determines the floating-point conversion specifier as indicated in Table 98. Table 98 — Floating-point conversions [tab:facet.num.put.fp] 🔗State stdio equivalent -------------------------------------------------------------------------------------------------------------- -------------------- 🔗floatfield == ios_base::fixed && !uppercase %f 🔗floatfield == ios_base::fixed %F 🔗floatfield == ios_base::scientific && !uppercase %e 🔗floatfield == ios_base::scientific %E 🔗floatfield == (ios_base::fixed | ios_base::scientific) && !uppercase %a 🔗floatfield == (ios_base::fixed | ios_base::scientific) %A 🔗!uppercase %g 🔗otherwise %G For conversions from an integral or floating-point type a length modifier is added to the conversion specifier as indicated in Table 99. Table 99 — Length modifier [tab:facet.num.put.length] 🔗Type Length modifier ------------------------------------------------------- ------------------- 🔗long l 🔗long long ll 🔗unsigned long l 🔗unsigned long long ll 🔗long double L 🔗otherwise none The conversion specifier has the following optional additional qualifiers prepended as indicated in Table 100. Table 100 — Numeric conversions [tab:facet.num.put.conv] 🔗Type(s) State -------------------------------------------------------- --------- 🔗an integral type showpos 🔗 showbase 🔗a floating-point type showpos 🔗 showpoint For conversion from a floating-point type, if floatfield != (ios_base::fixed ios_base::scientific),str.precision() is specified as precision in the conversion specification. Otherwise, no precision is specified. For conversion from void* the specifier is %p. The representations at the end of stage 1 consists of the char's that would be printed by a call of printf(s, val)where s is the conversion specifier determined above. - Stage 2:
Any character c other than a decimal point(.) is converted to a charT viause_facet<ctype<charT>>(loc).widen(c)
A local variable punct is initialized viaconst numpunct<charT>& punct = use_facet<numpunct<charT>>(loc);
For arithmetic types,punct.thousands_sep() characters are inserted into the sequence as determined by the value returned by punct.do_grouping()using the method described in [facet.numpunct.virtuals].
Decimal point characters(.) are replaced by punct.decimal_point(). - Stage 3:
A local variable is initialized asfmtflags adjustfield = (flags & (ios_base::adjustfield));
The location of any padding224is determined according to Table 101.
Table 101 — Fill padding [tab:facet.num.put.fill]🔗State Location 🔗adjustfield == ios_base::left pad after 🔗adjustfield == ios_base::right pad before 🔗adjustfield == internal and a sign occurs in the representation pad after the sign 🔗adjustfield == internal and representation after stage 1 began with 0x or 0X pad after x or X 🔗otherwise pad before If str.width() is nonzero and the number of charT's in the sequence after stage 2 is less than str.width(), then enough fill characters are added to the sequence at the position indicated for padding to bring the length of the sequence to str.width(). - Stage 4:
The sequence of charT's at the end of stage 3 are output via*out++ = c
iter_type do_put(iter_type out, ios_base& str, char_type fill, bool val) const;
Returns: If (str.flags() & ios_base::boolalpha) == 0returns do_put(out, str, fill,
(int)val), otherwise obtains a string s as if bystring_type s = val ? use_facet<numpunct<charT>>(loc).truename() : use_facet<numpunct<charT>>(loc).falsename();and then inserts each character c of s into outvia *out++ = cand returns out.