[category.numeric]

# 28 Text processing library [[text]](./#text)

## 28.3 Localization library [[localization]](localization#category.numeric)

### 28.3.4 Standard locale categories [[locale.categories]](locale.categories#category.numeric)

#### 28.3.4.3 The numeric category [category.numeric]

#### [28.3.4.3.1](#general) General [[category.numeric.general]](category.numeric.general)

[1](#general-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2387)

The classes num_get<> and num_put<> handle numeric formatting and parsing[.](#general-1.sentence-1)

Virtual functions are provided for several numeric types[.](#general-1.sentence-2)

Implementations may (but are not required to) delegate
extraction of smaller types to extractors for larger types[.](#general-1.sentence-3)[223](#footnote-223 "Parsing &quot;-1&quot; correctly into, e.g., an unsigned short requires that the corresponding member get() at least extract the sign before delegating.")

[2](#general-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2399)

All specifications of member functions for num_put and num_get in the subclauses of [category.numeric] only apply to
the specializations required in Tables [91](locale.category#tab:locale.category.facets "Table 91: Locale category facets") and [92](locale.category#tab:locale.spec "Table 92: Required specializations") ([[locale.category]](locale.category "28.3.3.1.2.1 Type locale​::​category")), namelynum_get<char>,num_get<wchar_t>,num_get<C, InputIterator>,num_put<char>,num_put<wchar_t>, andnum_put<C, OutputIterator>[.](#general-2.sentence-1)

These specializations refer to the ios_base& argument for
formatting specifications ([[locale.categories]](locale.categories "28.3.4 Standard 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[.](#general-2.sentence-2)

[3](#general-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2416)

Extractor and inserter members of the standard iostreams usenum_get<> and num_put<> member functions for
formatting and parsing
numeric values ([[istream.formatted.reqmts]](istream.formatted.reqmts "31.7.5.3.1 Common requirements"), [[ostream.formatted.reqmts]](ostream.formatted.reqmts "31.7.6.3.1 Common requirements"))[.](#general-3.sentence-1)

[223)](#footnote-223)[223)](#footnoteref-223)

Parsing "-1" correctly into, e.g., an unsigned short requires that the corresponding member get() at least extract the sign before delegating[.](#footnote-223.sentence-1)

#### [28.3.4.3.2](#locale.num.get) Class template num_get [[locale.num.get]](locale.num.get)

#### [28.3.4.3.2.1](#locale.num.get.general) General [[locale.num.get.general]](locale.num.get.general)

[🔗](#lib:num_get)

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; };}

[1](#locale.num.get.general-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2490)

The facet num_get is used to parse numeric values
from an input sequence such as an istream[.](#locale.num.get.general-1.sentence-1)

#### [28.3.4.3.2.2](#facet.num.get.members) Members [[facet.num.get.members]](facet.num.get.members)

[🔗](#lib:num_get,get)

`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;
`

[1](#facet.num.get.members-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2523)

*Returns*: do_get(in, end, str, err, val)[.](#facet.num.get.members-1.sentence-1)

#### [28.3.4.3.2.3](#facet.num.get.virtuals) Virtual functions [[facet.num.get.virtuals]](facet.num.get.virtuals)

[🔗](#lib:num_get,do_get)

`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;
`

[1](#facet.num.get.virtuals-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2555)

*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()[.](#facet.num.get.virtuals-1.sentence-1)

[2](#facet.num.get.virtuals-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2564)

The details of this operation occur in three stages:

- [(2.1)](#facet.num.get.virtuals-2.1)

  Stage 1:
Determine a conversion specifier[.](#facet.num.get.virtuals-2.1.sentence-1)

- [(2.2)](#facet.num.get.virtuals-2.2)

  Stage 2:
Extract characters from in and
determine a corresponding char value for
the format expected by the conversion specification determined in stage 1[.](#facet.num.get.virtuals-2.2.sentence-1)

- [(2.3)](#facet.num.get.virtuals-2.3)

  Stage 3:
Store results[.](#facet.num.get.virtuals-2.3.sentence-1)

[3](#facet.num.get.virtuals-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2581)

The details of the stages are presented below[.](#facet.num.get.virtuals-3.sentence-1)

- [Stage 1:](#facet.num.get.virtuals-3.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](#tab:facet.num.get.int "Table 95: Integer conversions")[.](#facet.num.get.virtuals-3.1.sentence-2)
  The table is ordered[.](#facet.num.get.virtuals-3.1.sentence-3)
  That is, the first line whose condition is true applies[.](#facet.num.get.virtuals-3.1.sentence-4)
  Table [95](#tab:facet.num.get.int) — Integer conversions [[tab:facet.num.get.int]](./tab:facet.num.get.int)  

| [🔗](#tab:facet.num.get.int-row-1)<br>   **State** | **stdio equivalent** |
| --- | --- |
| [🔗](#tab:facet.num.get.int-row-2)<br>   basefield == oct | %o |
| [🔗](#tab:facet.num.get.int-row-3)<br>   basefield == hex | %X |
| [🔗](#tab:facet.num.get.int-row-4)<br>   basefield == 0 | %i |
| [🔗](#tab:facet.num.get.int-row-5)<br>   signed integral type | %d |
| [🔗](#tab:facet.num.get.int-row-6)<br>   unsigned integral type | %u |

  For conversions to a floating-point type the specifier is %g[.](#facet.num.get.virtuals-3.1.sentence-5)
  For conversions to void* the specifier is %p[.](#facet.num.get.virtuals-3.1.sentence-6)
  A length modifier is added to the conversion specification, if needed,
as indicated in Table [96](#tab:facet.num.get.length "Table 96: Length modifier")[.](#facet.num.get.virtuals-3.1.sentence-7)
  Table [96](#tab:facet.num.get.length) — Length modifier [[tab:facet.num.get.length]](./tab:facet.num.get.length)  

| [🔗](#tab:facet.num.get.length-row-1)<br>   **Type** | **Length modifier** |
| --- | --- |
| [🔗](#tab:facet.num.get.length-row-2)<br>   short | h |
| [🔗](#tab:facet.num.get.length-row-3)<br>   unsigned short | h |
| [🔗](#tab:facet.num.get.length-row-4)<br>   long | l |
| [🔗](#tab:facet.num.get.length-row-5)<br>   unsigned long | l |
| [🔗](#tab:facet.num.get.length-row-6)<br>   long long | ll |
| [🔗](#tab:facet.num.get.length-row-7)<br>   unsigned long long | ll |
| [🔗](#tab:facet.num.get.length-row-8)<br>   double | l |
| [🔗](#tab:facet.num.get.length-row-9)<br>   long double | L |

- [Stage 2:](#facet.num.get.virtuals-3.2)
  If in == end then stage 2 terminates[.](#facet.num.get.virtuals-3.2.sentence-1)
  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[.](#facet.num.get.virtuals-3.2.sentence-2)
  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[.](#facet.num.get.virtuals-3.2.sentence-3)
  Otherwise, if '.' has already been accumulated,
the character is discarded and Stage 2 terminates[.](#facet.num.get.virtuals-3.2.sentence-4)
  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[.](#facet.num.get.virtuals-3.2.sentence-5)
  If so, it is accumulated[.](#facet.num.get.virtuals-3.2.sentence-6)
  If the character is either discarded or accumulated
then in is advanced by ++in and processing returns to the beginning of stage 2[.](#facet.num.get.virtuals-3.2.sentence-7)
  [*Example [1](#facet.num.get.virtuals-example-1)*:
  Given an input sequence of "0x1a.bp+07p",
  * [(3.2.1)](#facet.num.get.virtuals-3.2.1)

if the conversion specifier returned by Stage 1 is %d,"0" is accumulated;

  * [(3.2.2)](#facet.num.get.virtuals-3.2.2)

if the conversion specifier returned by Stage 1 is %i,"0x1a" are accumulated;

  * [(3.2.3)](#facet.num.get.virtuals-3.2.3)

if the conversion specifier returned by Stage 1 is %g,"0x1a.bp+07" are accumulated[.](#facet.num.get.virtuals-3.2.sentence-8)

   In all cases, the remainder is left in the input[.](#facet.num.get.virtuals-3.2.sentence-9)
 — *end example*]

- [Stage 3:](#facet.num.get.virtuals-3.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 [<cstdlib>](cstdlib.syn#header:%3ccstdlib%3e "17.2.2 Header <cstdlib> synopsis [cstdlib.syn]"):

  * [(3.3.1)](#facet.num.get.virtuals-3.3.1)

      For a signed integer value, the function strtoll[.](#facet.num.get.virtuals-3.3.1.sentence-1)

  * [(3.3.2)](#facet.num.get.virtuals-3.3.2)

      For an unsigned integer value, the function strtoull[.](#facet.num.get.virtuals-3.3.2.sentence-1)

  * [(3.3.3)](#facet.num.get.virtuals-3.3.3)

      For a float value, the function strtof[.](#facet.num.get.virtuals-3.3.3.sentence-1)

  * [(3.3.4)](#facet.num.get.virtuals-3.3.4)

      For a double value, the function strtod[.](#facet.num.get.virtuals-3.3.4.sentence-1)

  * [(3.3.5)](#facet.num.get.virtuals-3.3.5)

      For a long double value, the function strtold[.](#facet.num.get.virtuals-3.3.5.sentence-1)

  The numeric value to be stored can be one of:
  * [(3.3.6)](#facet.num.get.virtuals-3.3.6)

      zero, if the conversion function does not convert the entire field[.](#facet.num.get.virtuals-3.3.6.sentence-1)

  * [(3.3.7)](#facet.num.get.virtuals-3.3.7)

      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[.](#facet.num.get.virtuals-3.3.7.sentence-1)

  * [(3.3.8)](#facet.num.get.virtuals-3.3.8)

      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[.](#facet.num.get.virtuals-3.3.8.sentence-1)

  * [(3.3.9)](#facet.num.get.virtuals-3.3.9)

      the converted value, otherwise[.](#facet.num.get.virtuals-3.3.9.sentence-1)

  The resultant numeric value is stored in val[.](#facet.num.get.virtuals-3.3.sentence-3)
  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[.](#facet.num.get.virtuals-3.3.sentence-4)

[4](#facet.num.get.virtuals-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2726)

Digit grouping is checked[.](#facet.num.get.virtuals-4.sentence-1)

That is, the positions of discarded
separators are examined for consistency withuse_facet<numpunct<charT>>(loc).grouping()[.](#facet.num.get.virtuals-4.sentence-2)

If they are not consistent
then ios_base​::​failbit is assigned to err[.](#facet.num.get.virtuals-4.sentence-3)

[5](#facet.num.get.virtuals-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2734)

In any case,
if stage 2 processing was terminated by the test for in == end then err |= ios_base​::​eofbit is performed[.](#facet.num.get.virtuals-5.sentence-1)

[🔗](#lib:do_get,num_get_)

`iter_type do_get(iter_type in, iter_type end, ios_base& str,
                 ios_base::iostate& err, bool& val) const;
`

[6](#facet.num.get.virtuals-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2747)

*Effects*: If (str.flags() & ios_base​::​boolalpha) == 0 then input proceeds as it would for a long except 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[.](#facet.num.get.virtuals-6.sentence-1)

If the value is 1 then true is stored[.](#facet.num.get.virtuals-6.sentence-2)

Otherwise true is stored andios_base​::​failbit is assigned to err[.](#facet.num.get.virtuals-6.sentence-3)

[7](#facet.num.get.virtuals-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2758)

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())[.](#facet.num.get.virtuals-7.sentence-1)

Successive characters in the range [in, end) (see [[sequence.reqmts]](sequence.reqmts "23.2.4 Sequence containers"))
are obtained and matched against
corresponding positions in the target sequences
only as necessary to identify a unique match[.](#facet.num.get.virtuals-7.sentence-2)

The input iterator in is compared to end only when necessary to obtain a character[.](#facet.num.get.virtuals-7.sentence-3)

If a target sequence is uniquely matched,val is set to the corresponding value[.](#facet.num.get.virtuals-7.sentence-4)

Otherwise false is stored andios_base​::​failbit is assigned to err[.](#facet.num.get.virtuals-7.sentence-5)

[8](#facet.num.get.virtuals-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2773)

The in iterator is always left pointing one position beyond
the last character successfully matched[.](#facet.num.get.virtuals-8.sentence-1)

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)[.](#facet.num.get.virtuals-8.sentence-2)

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)[.](#facet.num.get.virtuals-8.sentence-3)

[*Example [2](#facet.num.get.virtuals-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[.](#facet.num.get.virtuals-8.sentence-4)

For targets true: "1" and false: "0",
the input sequence "1" yieldsval == true and err == str.goodbit[.](#facet.num.get.virtuals-8.sentence-5)

For empty targets (""),
any input sequence yields err == str.failbit[.](#facet.num.get.virtuals-8.sentence-6)

— *end example*]

[9](#facet.num.get.virtuals-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2796)

*Returns*: in[.](#facet.num.get.virtuals-9.sentence-1)

#### [28.3.4.3.3](#locale.nm.put) Class template num_put [[locale.nm.put]](locale.nm.put)

#### [28.3.4.3.3.1](#locale.nm.put.general) General [[locale.nm.put.general]](locale.nm.put.general)

[🔗](#lib:num_put)

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; };}

[1](#locale.nm.put.general-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2841)

The facetnum_put is used to format numeric values to a character sequence such as an ostream[.](#locale.nm.put.general-1.sentence-1)

#### [28.3.4.3.3.2](#facet.num.put.members) Members [[facet.num.put.members]](facet.num.put.members)

[🔗](#lib:num_put,put)

`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;
`

[1](#facet.num.put.members-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2861)

*Returns*: do_put(out, str, fill, val)[.](#facet.num.put.members-1.sentence-1)

#### [28.3.4.3.3.3](#facet.num.put.virtuals) Virtual functions [[facet.num.put.virtuals]](facet.num.put.virtuals)

[🔗](#lib:num_put,do_put)

`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;
`

[1](#facet.num.put.virtuals-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2880)

*Effects*: Writes characters to the sequence out,
formatting val as desired[.](#facet.num.put.virtuals-1.sentence-1)

In the following description, loc names a local variable initialized aslocale loc = str.getloc();

[2](#facet.num.put.virtuals-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2889)

The details of this operation occur in several stages:

- [(2.1)](#facet.num.put.virtuals-2.1)

  Stage 1:
Determine a printf conversion specifier spec and
determine the characters
that would be printed by printf ([[c.files]](c.files "31.13 C library files"))
given this conversion specifier forprintf(spec, val) assuming that the current locale is the "C" locale[.](#facet.num.put.virtuals-2.1.sentence-1)

- [(2.2)](#facet.num.put.virtuals-2.2)

  Stage 2:
Adjust the representation by converting
each char determined by stage 1 to a charT using a conversion and
values returned by members of use_facet<numpunct<charT>>(loc)[.](#facet.num.put.virtuals-2.2.sentence-1)

- [(2.3)](#facet.num.put.virtuals-2.3)

  Stage 3:
Determine where padding is required[.](#facet.num.put.virtuals-2.3.sentence-1)

- [(2.4)](#facet.num.put.virtuals-2.4)

  Stage 4:
Insert the sequence into the out[.](#facet.num.put.virtuals-2.4.sentence-1)

[3](#facet.num.put.virtuals-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2917)

Detailed descriptions of each stage follow[.](#facet.num.put.virtuals-3.sentence-1)

[4](#facet.num.put.virtuals-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2920)

*Returns*: out[.](#facet.num.put.virtuals-4.sentence-1)

[5](#facet.num.put.virtuals-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L2924)

- [Stage 1:](#facet.num.put.virtuals-5.1)
  The first action of stage 1 is to determine a conversion specifier[.](#facet.num.put.virtuals-5.1.sentence-1)
  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[.](#facet.num.put.virtuals-5.1.sentence-3)
  That is, the first line whose condition is true applies[.](#facet.num.put.virtuals-5.1.sentence-4)
  A line without a condition is the default behavior
when none of the earlier lines apply[.](#facet.num.put.virtuals-5.1.sentence-5)
  For conversion from an integral type other than a character type,
the function determines the integral conversion specifier
as indicated in Table [97](#tab:facet.num.put.int "Table 97: Integer conversions")[.](#facet.num.put.virtuals-5.1.sentence-6)
  Table [97](#tab:facet.num.put.int) — Integer conversions [[tab:facet.num.put.int]](./tab:facet.num.put.int)  

| [🔗](#tab:facet.num.put.int-row-1)<br>   **State** | **stdio equivalent** |
| --- | --- |
| [🔗](#tab:facet.num.put.int-row-2)<br>   basefield == ios_base​::​oct | %o |
| [🔗](#tab:facet.num.put.int-row-3)<br>   (basefield == ios_base​::​hex) && !uppercase | %x |
| [🔗](#tab:facet.num.put.int-row-4)<br>   (basefield == ios_base​::​hex) | %X |
| [🔗](#tab:facet.num.put.int-row-5)<br>   for a signed integral type | %d |
| [🔗](#tab:facet.num.put.int-row-6)<br>   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](#tab:facet.num.put.fp "Table 98: Floating-point conversions")[.](#facet.num.put.virtuals-5.1.sentence-7)
  Table [98](#tab:facet.num.put.fp) — Floating-point conversions [[tab:facet.num.put.fp]](./tab:facet.num.put.fp)  

| [🔗](#tab:facet.num.put.fp-row-1)<br>   **State** | **stdio equivalent** |
| --- | --- |
| [🔗](#tab:facet.num.put.fp-row-2)<br>   floatfield == ios_base​::​fixed && !uppercase | %f |
| [🔗](#tab:facet.num.put.fp-row-3)<br>   floatfield == ios_base​::​fixed | %F |
| [🔗](#tab:facet.num.put.fp-row-4)<br>   floatfield == ios_base​::​scientific && !uppercase | %e |
| [🔗](#tab:facet.num.put.fp-row-5)<br>   floatfield == ios_base​::​scientific | %E |
| [🔗](#tab:facet.num.put.fp-row-6)<br>   floatfield == (ios_base​::​fixed | ios_base​::​scientific) && !uppercase | %a |
| [🔗](#tab:facet.num.put.fp-row-7)<br>   floatfield == (ios_base​::​fixed | ios_base​::​scientific) | %A |
| [🔗](#tab:facet.num.put.fp-row-8)<br>   !uppercase | %g |
| [🔗](#tab:facet.num.put.fp-row-9)<br>   *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](#tab:facet.num.put.length "Table 99: Length modifier")[.](#facet.num.put.virtuals-5.1.sentence-8)
  Table [99](#tab:facet.num.put.length) — Length modifier [[tab:facet.num.put.length]](./tab:facet.num.put.length)  

| [🔗](#tab:facet.num.put.length-row-1)<br>   **Type** | **Length modifier** |
| --- | --- |
| [🔗](#tab:facet.num.put.length-row-2)<br>   long | l |
| [🔗](#tab:facet.num.put.length-row-3)<br>   long long | ll |
| [🔗](#tab:facet.num.put.length-row-4)<br>   unsigned long | l |
| [🔗](#tab:facet.num.put.length-row-5)<br>   unsigned long long | ll |
| [🔗](#tab:facet.num.put.length-row-6)<br>   long double | L |
| [🔗](#tab:facet.num.put.length-row-7)<br>   *otherwise* | *none* |

  The conversion specifier has the following optional additional qualifiers
prepended as indicated in Table [100](#tab:facet.num.put.conv "Table 100: Numeric conversions")[.](#facet.num.put.virtuals-5.1.sentence-9)
  Table [100](#tab:facet.num.put.conv) — Numeric conversions [[tab:facet.num.put.conv]](./tab:facet.num.put.conv)  

| [🔗](#tab:facet.num.put.conv-row-1)<br>   **Type(s)** | **State** | **stdio equivalent** |
| --- | --- | --- |
| [🔗](#tab:facet.num.put.conv-row-2)<br>   an integral type | showpos | + |
| [🔗](#tab:facet.num.put.conv-row-3) | showbase | # |
| [🔗](#tab:facet.num.put.conv-row-4)<br>   a floating-point type | showpos | + |
| [🔗](#tab:facet.num.put.conv-row-5) | 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[.](#facet.num.put.virtuals-5.1.sentence-10)
  Otherwise, no precision is specified[.](#facet.num.put.virtuals-5.1.sentence-11)
  For conversion from void* the specifier is %p[.](#facet.num.put.virtuals-5.1.sentence-12)
  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[.](#facet.num.put.virtuals-5.1.sentence-13)

- [Stage 2:](#facet.num.put.virtuals-5.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]](facet.numpunct.virtuals "28.3.4.4.1.3 Virtual functions")[.](#facet.num.put.virtuals-5.2.sentence-3)
  Decimal point characters(.) are replaced by punct.decimal_point()[.](#facet.num.put.virtuals-5.2.sentence-4)

- [Stage 3:](#facet.num.put.virtuals-5.3)
  A local variable is initialized asfmtflags adjustfield = (flags & (ios_base::adjustfield));
  The location of any padding[224](#footnote-224 "The conversion specification #o generates a leading 0 which is not a padding character.") is determined according to Table [101](#tab:facet.num.put.fill "Table 101: Fill padding")[.](#facet.num.put.virtuals-5.3.sentence-2)
  Table [101](#tab:facet.num.put.fill) — Fill padding [[tab:facet.num.put.fill]](./tab:facet.num.put.fill)  

| [🔗](#tab:facet.num.put.fill-row-1)<br>   **State** | **Location** |
| --- | --- |
| [🔗](#tab:facet.num.put.fill-row-2)<br>   adjustfield == ios_base​::​left | pad after |
| [🔗](#tab:facet.num.put.fill-row-3)<br>   adjustfield == ios_base​::​right | pad before |
| [🔗](#tab:facet.num.put.fill-row-4)<br>   adjustfield == internal and a sign occurs in the representation | pad after the sign |
| [🔗](#tab:facet.num.put.fill-row-5)<br>   adjustfield == internal and representation after stage 1 began with 0x or 0X | pad after x or X |
| [🔗](#tab:facet.num.put.fill-row-6)<br>   *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()[.](#facet.num.put.virtuals-5.3.sentence-3)
  str.width(0) is called[.](#facet.num.put.virtuals-5.3.sentence-4)

- [Stage 4:](#facet.num.put.virtuals-5.4)
  The sequence of charT's at the end of stage 3 are output via*out++ = c

[🔗](#lib:do_put,num_put_)

`iter_type do_put(iter_type out, ios_base& str, char_type fill, bool val) const;
`

[6](#facet.num.put.virtuals-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/text.tex#L3086)

*Returns*: If (str.flags() & ios_base​::​boolalpha) == 0 returns 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 out via *out++ = c and returns out[.](#facet.num.put.virtuals-6.sentence-1)

[224)](#footnote-224)[224)](#footnoteref-224)

The conversion specification #o generates a leading 0 which is *not* a padding character[.](#footnote-224.sentence-1)