22 Localization library [localization]

Returns: use_facet<ctype<charT> >(loc).toupper(c).

Returns: use_facet<ctype<charT> >(loc).tolower(c).

The type shall be a synonym for std::basic_string<char, char_traits<char>, Byte_alloc>

Returns: cvtcount.

Effects: The first member function shall convert the single-element sequence byte to a wide string. The second member function shall convert the null-terminated sequence beginning at ptr to a wide string. The third member function shall convert the sequence stored in str to a wide string. The fourth member function shall convert the sequence defined by the range [first,last) to a wide string.

In all cases:

• (8.1)

  If the cvtstate object was not constructed with an explicit value, it shall be set to its default value (the initial conversion state) before the conversion begins. Otherwise it shall be left unchanged.

• (8.2)

  The number of input elements successfully converted shall be stored in cvtcount.

Returns: If no conversion error occurs, the member function shall return the converted wide string. Otherwise, if the object was constructed with a wide-error string, the member function shall return the wide-error string. Otherwise, the member function throws an object of class std::range_error.

returns cvtstate.

The type shall be a synonym for Codecvt::state_type.

Effects: The first member function shall convert the single-element sequence wchar to a byte string. The second member function shall convert the null-terminated sequence beginning at wptr to a byte string. The third member function shall convert the sequence stored in wstr to a byte string. The fourth member function shall convert the sequence defined by the range [first,last) to a byte string.

In all cases:

• (13.1)

  If the cvtstate object was not constructed with an explicit value, it shall be set to its default value (the initial conversion state) before the conversion begins. Otherwise it shall be left unchanged.

• (13.2)

  The number of input elements successfully converted shall be stored in cvtcount.

Returns: If no conversion error occurs, the member function shall return the converted byte string. Otherwise, if the object was constructed with a byte-error string, the member function shall return the byte-error string. Otherwise, the member function shall throw an object of class std::range_error.

The type shall be a synonym for std::basic_string<Elem, char_traits<Elem>, Wide_alloc>.

Requires: For the first and second constructors, pcvt != nullptr.

Effects: The first constructor shall store pcvt in cvtptr and default values in cvtstate, byte_err_string, and wide_err_string. The second constructor shall store pcvt in cvtptr, state in cvtstate, and default values in byte_err_string and wide_err_string; moreover the stored state shall be retained between calls to from_bytes and to_bytes. The third constructor shall store new Codecvt in cvtptr, state_type() in cvtstate, byte_err in byte_err_string, and wide_err in wide_err_string.

Effects: The destructor shall delete cvtptr.

Returns: cvtstate.

Returns: bufptr.

Effects: stores bytebuf in bufptr.

Returns: The previous value of bufptr.

The type shall be a synonym for Codecvt::state_type.

Requires: pcvt != nullptr.

Effects: The constructor constructs a stream buffer object, initializes bufptr to bytebuf, initializes cvtptr to pcvt, and initializes cvtstate to state.

Effects: The destructor shall delete cvtptr.

Returns: do_is(m,c) or do_is(low,high,vec)

Returns: do_scan_is(m,low,high)

Returns: do_scan_not(m,low,high)

Returns: do_toupper(c) or do_toupper(low,high)

Returns: do_tolower(c) or do_tolower(low,high)

Returns: do_widen(c) or do_widen(low,high,to)

Returns: do_narrow(c,dfault) or do_narrow(low,high,dfault,to)

Effects: Classifies a character or sequence of characters. For each argument character, identifies a value M of type ctype_base::mask. The second form identifies a value M of type ctype_base::mask for each *p where (low<=p && p<high), and places it into vec[p-low].

Returns: The first form returns the result of the expression (M & m) != 0; i.e., true if the character has the characteristics specified. The second form returns high.

Effects: Locates a character in a buffer that conforms to a classification m.

Returns: The smallest pointer p in the range [low, high) such that is(m,*p) would return true; otherwise, returns high.

Effects: Locates a character in a buffer that fails to conform to a classification m.

Returns: The smallest pointer p, if any, in the range [low,high) such that is(m,*p) would return false; otherwise, returns high.

Effects: Converts a character or characters to upper case. The second form replaces each character *p in the range [low,high) for which a corresponding upper-case character exists, with that character.

Returns: The first form returns the corresponding upper-case character if it is known to exist, or its argument if not. The second form returns high.

Effects: Converts a character or characters to lower case. The second form replaces each character *p in the range [low,high) and for which a corresponding lower-case character exists, with that character.

Returns: The first form returns the corresponding lower-case character if it is known to exist, or its argument if not. The second form returns high.

Effects: Applies the simplest reasonable transformation from a char value or sequence of char values to the corresponding charT value or values.240 The only characters for which unique transformations are required are those in the basic source character set ([lex.charset]).

For any named ctype category with a ctype<charT> facet ctc and valid ctype_base::mask value M, (ctc.is(M, c) || !is(M, do_widen(c)) ) is true.241

The second form transforms each character *p in the range [low,high), placing the result in dest[p-low].

Returns: The first form returns the transformed value. The second form returns high.

Effects: Applies the simplest reasonable transformation from a charT value or sequence of charT values to the corresponding char value or values.

For any character c in the basic source character set ([lex.charset]) the transformation is such that

do_widen(do_narrow(c,0)) == c

For any named ctype category with a ctype<char> facet ctc however, and ctype_base::mask value M,

(is(M,c) || !ctc.is(M, do_narrow(c,dfault)) )

is true (unless do_narrow returns dfault). In addition, for any digit character c, the expression (do_narrow(c, dfault) - '0') evaluates to the digit value of the character. The second form transforms each character *p in the range [low,high), placing the result (or dfault if no simple transformation is readily available) in dest[p-low].

Returns: The first form returns the transformed value; or dfault if no mapping is readily available. The second form returns high.

Effects: If the constructor's first argument was nonzero, and its second argument was true, does delete [] table().

Requires: tbl either 0 or an array of at least table_size elements.

Effects: Passes its refs argument to its base class constructor.

Effects: The second form, for all *p in the range [low,high), assigns into vec[p-low] the value table()[ (unsigned char)*p].

Returns: The first form returns table()[(unsigned char)c] & m; the second form returns high.

Returns: The smallest p in the range [low,high) such that

table()[(unsigned char) *p] & m

is true.

Returns: The smallest p in the range [low,high) such that

table()[(unsigned char) *p] & m

is false.

Returns: do_toupper(c) or do_toupper(low,high), respectively.

Returns: do_tolower(c) or do_tolower(low,high), respectively.

Returns: do_widen(c) or do_widen(low, high, to), respectively.

Returns: do_narrow(c, dfault) or do_narrow(low, high, dfault, to), respectively.

Returns: The first constructor argument, if it was non-zero, otherwise classic_table().

Returns: A pointer to the initial element of an array of size table_size which represents the classifications of characters in the "C" locale.

Returns: do_out(state, from, from_end, from_next, to, to_end, to_next)

Returns: do_unshift(state, to, to_end, to_next)

Returns: do_in(state, from, from_end, from_next, to, to_end, to_next)

Returns: do_encoding()

Returns: do_always_noconv()

Returns: do_length(state, from,from_end,max)

Returns: do_max_length()

Requires: (from<=from_end && to<=to_end) well-defined and true; state initialized, if at the beginning of a sequence, or else equal to the result of converting the preceding characters in the sequence.

Effects: Translates characters in the source range [from,from_end), placing the results in sequential positions starting at destination to. Converts no more than (from_end-from) source elements, and stores no more than (to_end-to) destination elements.

Stops if it encounters a character it cannot convert. It always leaves the from_next and to_next pointers pointing one beyond the last element successfully converted. If returns noconv, internT and externT are the same type and the converted sequence is identical to the input sequence [from, from_next). to_next is set equal to to, the value of state is unchanged, and there are no changes to the values in [to, to_end).

A codecvt facet that is used by basic_filebuf ([file.streams]) shall have the property that if

do_out(state, from, from_end, from_next, to, to_end, to_next)

would return ok, where from != from_end, then

do_out(state, from, from + 1, from_next, to, to_end, to_next)

shall also return ok, and that if

do_in(state, from, from_end, from_next, to, to_end, to_next)

would return ok, where to != to_end, then

do_in(state, from, from_end, from_next, to, to + 1, to_next)

shall also return ok.243 [ Note: As a result of operations on state, it can return ok or partial and set from_next == from and to_next != to.  — end note ]

Remarks: Its operations on state are unspecified. [ Note: This argument can be used, for example, to maintain shift state, to specify conversion options (such as count only), or to identify a cache of seek offsets.  — end note ]

Returns: An enumeration value, as summarized in Table [tab:localization.convert.result.values.out.in].

A return value of partial, if (from_next==from_end), indicates that either the destination sequence has not absorbed all the available destination elements, or that additional source elements are needed before another destination element can be produced.

Requires: (to <= to_end) well defined and true; state initialized, if at the beginning of a sequence, or else equal to the result of converting the preceding characters in the sequence.

Effects: Places characters starting at to that should be appended to terminate a sequence when the current stateT is given by state.244 Stores no more than (to_end-to) destination elements, and leaves the to_next pointer pointing one beyond the last element successfully stored.

Returns: An enumeration value, as summarized in Table [tab:localization.convert.result.values.unshift].

Returns: -1 if the encoding of the externT sequence is state-dependent; else the constant number of externT characters needed to produce an internal character; or 0 if this number is not a constant.245

Returns: true if do_in() and do_out() return noconv for all valid argument values. codecvt<char, char, mbstate_t> returns true.

Requires: (from<=from_end) well-defined and true; state initialized, if at the beginning of a sequence, or else equal to the result of converting the preceding characters in the sequence.

Effects: The effect on the state argument is “as if” it called do_in(state, from, from_end, from, to, to+max, to) for to pointing to a buffer of at least max elements.

Returns: (from_next-from) where from_next is the largest value in the range [from,from_end] such that the sequence of values in the range [from,from_next) represents max or fewer valid complete characters of type internT. The specialization codecvt<char, char, mbstate_t>, returns the lesser of max and (from_end-from).

Returns: The maximum value that do_length(state, from, from_end, 1) can return for any valid range [from, from_end) and stateT value state. The specialization codecvt<char, char, mbstate_t>::do_max_length() returns 1.

Returns: do_get(in, end, str, err, val).

Effects: Reads characters from in, interpreting them according to str.flags(), use_facet<ctype<charT> >(loc), and use_facet< numpunct<charT> >(loc), where loc is str.getloc().

The details of this operation occur in three stages

• (2.1)

  Stage 1: Determine a conversion specifier

• (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.

• (2.3)

  Stage 3: Store results

The details of the stages are presented below.

• (3.1)

  The function initializes local variables via

  fmtflags 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 [tab:localization.integer.conversions.in]. The table is ordered. That is, the first line whose condition is true applies.

  Table 85 — Integer conversions
  

  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 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 [tab:localization.length.modifier.in].

  Table 86 — Length modifier
  

  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

• (3.2)

  If in==end then stage 2 terminates. Otherwise a charT is taken from in and local variables are initialized as if by

  char_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[] = "0123456789abcdefxABCDEFX+-";
  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 ++in and processing returns to the beginning of stage 2.

• (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>:

  • (3.3.1)

    For a signed integer value, the function strtoll.

  • (3.3.2)

    For an unsigned integer value, the function strtoull.

  • (3.3.3)

    For a floating-point value, the function strtold.

  The numeric value to be stored can be one of:

  • (3.3.4)

    zero, if the conversion function fails to convert the entire field. ios_base::failbit is assigned to err.

  • (3.3.5)

    the most positive representable value, if the field represents a value too large positive to be represented in val. ios_base::failbit is assigned to err.

  • (3.3.6)

    the most negative representable value or zero for an unsigned integer type, if the field represents a value too large negative to be represented in val. ios_base::failbit is assigned to err.

  • (3.3.7)

    the converted value, otherwise.

  The resultant numeric value is stored in val.

Digit grouping is checked. That is, the positions of discarded separators is examined for consistency with use_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==end then err |=ios_base::eofbit is performed.

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. If the value is 1 then true is stored. Otherwise true is stored and ios_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 end only when necessary to obtain a character. If a target sequence is uniquely matched, val is set to the corresponding value. Otherwise false is stored and ios_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: For targets true: "a" and false: "abb", the input sequence "a" yields val == true and err == str.eofbit; the input sequence "abc" yields err = str.failbit, with in ending at the 'c' element. For targets true: "1" and false: "0", the input sequence "1" yields val == true and err == str.goodbit. For empty targets (""), any input sequence yields err == str.failbit.  — end example ]

Returns: in.

Returns: do_put(out, str, fill, val).

Effects: Writes characters to the sequence out, formatting val as desired. In the following description, a local variable initialized with

locale loc = str.getloc();

The details of this operation occur in several stages:

• (2.1)

  Stage 1: Determine a printf conversion specifier spec and determining the characters that would be printed by printf ([c.files]) given this conversion specifier for

  printf(spec, val )
  

  assuming that the current locale is the "C" locale.

• (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> >(str.getloc())

• (2.3)

  Stage 3: Determine where padding is required.

• (2.4)

  Stage 4: Insert the sequence into the out.

Detailed descriptions of each stage follow.

Returns: out.

• (5.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));
  

  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 [tab:localization.integer.conversions.out].

  Table 87 — Integer conversions
  

  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 [tab:localization.fp.conversions.out].

  Table 88 — Floating-point conversions
  

  State	stdio equivalent
  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 [tab:localization.length.modifier.out].

  Table 89 — Length modifier
  

  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 [tab:localization.numeric.conversions].

  Table 90 — Numeric conversions
  

  Type(s)	State	stdio equivalent
  an integral type	flags & showpos	+
  	flags & showbase	#
  a floating-point type	flags & showpos	+
  	flags & 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.

• (5.2)

  Any character c other than a decimal point(.) is converted to a charT via use_facet<ctype<charT> >(loc).widen( c )

  A local variable punct is initialized via

  const numpunct<charT>& punct = use_facet< numpunct<charT> >(str.getloc());
  

  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()

• (5.3)

  A local variable is initialized as

  fmtflags adjustfield=   (flags & (ios_base::adjustfield));
  

  The location of any padding247 is determined according to Table [tab:localization.fill.padding].

  Table 91 — Fill padding
  

  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(). str.width(0) is called.

• (5.4)

  The sequence of charT's at the end of stage 3 are output via

  *out++ = c
  

Returns: If (str.flags() & ios_base::boolalpha) == 0 returns do_put(out, str, fill,
(int)val), otherwise obtains a string s as if by

string_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.

Returns: do_decimal_point()

Returns: do_thousands_sep()

Returns: do_grouping()

Returns: do_truename() or do_falsename(), respectively.

Returns: A character for use as the decimal radix separator. The required specializations return '.' or L'.'.

Returns: A character for use as the digit group separator. The required specializations return ',' or L','.

Returns: A basic_string<char> vec used as a vector of integer values, in which each element vec[i] represents the number of digits248 in the group at position i, starting with position 0 as the rightmost group. If vec.size() <= i, the number is the same as group (i-1); if (i<0 || vec[i]<=0 || vec[i]==CHAR_MAX), the size of the digit group is unlimited.

The required specializations return the empty string, indicating no grouping.

Returns: A string representing the name of the boolean value true or false, respectively.

In the base class implementation these names are "true" and "false", or L"true" and L"false".

Returns: do_compare(low1, high1, low2, high2)

Returns: do_transform(low, high)

Returns: do_hash(low, high)

Returns: 1 if the first string is greater than the second, -1 if less, zero otherwise. The specializations required in Table [tab:localization.category.facets] ([locale.category]), namely collate<char> and collate<wchar_t>, implement a lexicographical comparison ([alg.lex.comparison]).

Returns: A basic_string<charT> value that, compared lexicographically with the result of calling transform() on another string, yields the same result as calling do_compare() on the same two strings.249

Returns: An integer value equal to the result of calling hash() on any other string for which do_compare() returns 0 (equal) when passed the two strings. [ Note: The probability that the result equals that for another string which does not compare equal should be very small, approaching (1.0/numeric_limits<unsigned long>::max()).  — end note ]

Returns: do_date_order()

Returns: do_get_time(s, end, str, err, t)

Returns: do_get_date(s, end, str, err, t)

Returns: do_get_weekday(s, end, str, err, t) or do_get_monthname(s, end, str, err, t)

Returns: do_get_year(s, end, str, err, t)

Returns: do_get(s, end, f, err, t, format, modifier)

Requires: [fmt,fmtend) shall be a valid range.

Effects: The function starts by evaluating err = ios_base::goodbit. It then enters a loop, reading zero or more characters from s at each iteration. Unless otherwise specified below, the loop terminates when the first of the following conditions holds:

• (8.1)

  The expression fmt == fmtend evaluates to true.

• (8.2)

  The expression err == ios_base::goodbit evaluates to false.

• (8.3)

  The expression s == end evaluates to true, in which case the function evaluates err = ios_base::eofbit | ios_base::failbit.

• (8.4)

  The next element of fmt is equal to '%', optionally followed by a modifier character, followed by a conversion specifier character, format, together forming a conversion specification valid for the ISO/IEC 9945 function strptime. If the number of elements in the range [fmt,fmtend) is not sufficient to unambiguously determine whether the conversion specification is complete and valid, the function evaluates err = ios_base::failbit. Otherwise, the function evaluates s = do_get(s, end, f, err, t, format, modifier), where the value of modifier is '\0' when the optional modifier is absent from the conversion specification. If err == ios_base::goodbit holds after the evaluation of the expression, the function increments fmt to point just past the end of the conversion specification and continues looping.

• (8.5)

  The expression isspace(*fmt, f.getloc()) evaluates to true, in which case the function first increments fmt until fmt == fmtend || !isspace(*fmt, f.getloc()) evaluates to true, then advances s until s == end || !isspace(*s, f.getloc()) is true, and finally resumes looping.

• (8.6)

  The next character read from s matches the element pointed to by fmt in a case-insensitive comparison, in which case the function evaluates ++fmt, ++s and continues looping. Otherwise, the function evaluates err = ios_base::failbit.

[ Note: The function uses the ctype<charT> facet installed in f's locale to determine valid whitespace characters. It is unspecified by what means the function performs case-insensitive comparison or whether multi-character sequences are considered while doing so.  — end note ]

Returns: s

Returns: An enumeration value indicating the preferred order of components for those date formats that are composed of day, month, and year.251 Returns no_order if the date format specified by 'x' contains other variable components (e.g., Julian day, week number, week day).

Effects: Reads characters starting at s until it has extracted those struct tm members, and remaining format characters, used by time_put<>::put to produce the format specified by "%H:%M:%S", or until it encounters an error or end of sequence.

Returns: An iterator pointing immediately beyond the last character recognized as possibly part of a valid time.

Effects: Reads characters starting at s until it has extracted those struct tm members and remaining format characters used by time_put<>::put to produce one of the following formats, or until it encounters an error. The format depends on the value returned by date_order() as shown in Table [tab:lib.locale.time.get.virtuals.dogetdate].

An implementation may also accept additional implementation-defined formats.

Returns: An iterator pointing immediately beyond the last character recognized as possibly part of a valid date.

Effects: Reads characters starting at s until it has extracted the (perhaps abbreviated) name of a weekday or month. If it finds an abbreviation that is followed by characters that could match a full name, it continues reading until it matches the full name or fails. It sets the appropriate struct tm member accordingly.

Returns: An iterator pointing immediately beyond the last character recognized as part of a valid name.

Effects: Reads characters starting at s until it has extracted an unambiguous year identifier. It is implementation-defined whether two-digit year numbers are accepted, and (if so) what century they are assumed to lie in. Sets the t->tm_year member accordingly.

Returns: An iterator pointing immediately beyond the last character recognized as part of a valid year identifier.

Requires: t shall point to an object.

Effects: The function starts by evaluating err = ios_base::goodbit. It then reads characters starting at s until it encounters an error, or until it has extracted and assigned those struct tm members, and any remaining format characters, corresponding to a conversion directive appropriate for the ISO/IEC 9945 function strptime, formed by concatenating '%', the modifier character, when non-NUL, and the format character. When the concatenation fails to yield a complete valid directive the function leaves the object pointed to by t unchanged and evaluates err |= ios_base::failbit. When s == end evaluates to true after reading a character the function evaluates err |= ios_base::eofbit.

For complex conversion directives such as %c, %x, or %X, or directives that involve the optional modifiers E or O, when the function is unable to unambiguously determine some or all struct tm members from the input sequence [s,end), it evaluates err |= ios_base::eofbit. In such cases the values of those struct tm members are unspecified and may be outside their valid range.

Remark: It is unspecified whether multiple calls to do_get() with the address of the same struct tm object will update the current contents of the object or simply overwrite its members. Portable programs must zero out the object before invoking the function.

Returns: An iterator pointing immediately beyond the last character recognized as possibly part of a valid input sequence for the given format and modifier.

Effects: The first form steps through the sequence from pattern to pat_end, identifying characters that are part of a format sequence. Each character that is not part of a format sequence is written to s immediately, and each format sequence, as it is identified, results in a call to do_put; thus, format elements and other characters are interleaved in the output in the order in which they appear in the pattern. Format sequences are identified by converting each character c to a char value as if by ct.narrow(c,0), where ct is a reference to ctype<charT> obtained from str.getloc(). The first character of each sequence is equal to '%', followed by an optional modifier character mod252 and a format specifier character spec as defined for the function strftime. If no modifier character is present, mod is zero. For each valid format sequence identified, calls do_put(s, str, fill, t, spec, mod).

The second form calls do_put(s, str, fill, t, format, modifier).

[ Note: The fill argument may be used in the implementation-defined formats or by derivations. A space character is a reasonable default for this argument.  — end note ]

Returns: An iterator pointing immediately after the last character produced.

Effects: Formats the contents of the parameter t into characters placed on the output sequence s. Formatting is controlled by the parameters format and modifier, interpreted identically as the format specifiers in the string argument to the standard library function strftime()253, except that the sequence of characters produced for those specifiers that are described as depending on the C locale are instead implementation-defined.254

Returns: An iterator pointing immediately after the last character produced. [ Note: The fill argument may be used in the implementation-defined formats or by derivations. A space character is a reasonable default for this argument.  — end note ]

Returns: do_get(s, end, intl, f, err, quant)

Effects: Reads characters from s to parse and construct a monetary value according to the format specified by a moneypunct<charT,Intl> facet reference mp and the character mapping specified by a ctype<charT> facet reference ct obtained from the locale returned by str.getloc(), and str.flags(). If a valid sequence is recognized, does not change err; otherwise, sets err to (err|str.failbit), or (err|str.failbit|str.eofbit) if no more characters are available, and does not change units or digits. Uses the pattern returned by mp.neg_format() to parse all values. The result is returned as an integral value stored in units or as a sequence of digits possibly preceded by a minus sign (as produced by ct.widen(c) where c is '-' or in the range from '0' through '9', inclusive) stored in digits. [ Example: The sequence $1,056.23 in a common United States locale would yield, for units, 105623, or, for digits, "105623".  — end example ] If mp.grouping() indicates that no thousands separators are permitted, any such characters are not read, and parsing is terminated at the point where they first appear. Otherwise, thousands separators are optional; if present, they are checked for correct placement only after all format components have been read.

Where money_base::space or money_base::none appears as the last element in the format pattern, no white space is consumed. Otherwise, where money_base::space appears in any of the initial elements of the format pattern, at least one white space character is required. Where money_base::none appears in any of the initial elements of the format pattern, white space is allowed but not required. If (str.flags() & str.showbase) is false, the currency symbol is optional and is consumed only if other characters are needed to complete the format; otherwise, the currency symbol is required.

If the first character (if any) in the string pos returned by mp.positive_sign() or the string neg returned by mp.negative_sign() is recognized in the position indicated by sign in the format pattern, it is consumed and any remaining characters in the string are required after all the other format components. [ Example: If showbase is off, then for a neg value of "()" and a currency symbol of "L", in "(100 L)" the "L" is consumed; but if neg is "-", the "L" in "-100 L" is not consumed.  — end example ] If pos or neg is empty, the sign component is optional, and if no sign is detected, the result is given the sign that corresponds to the source of the empty string. Otherwise, the character in the indicated position must match the first character of pos or neg, and the result is given the corresponding sign. If the first character of pos is equal to the first character of neg, or if both strings are empty, the result is given a positive sign.

Digits in the numeric monetary component are extracted and placed in digits, or into a character buffer buf1 for conversion to produce a value for units, in the order in which they appear, preceded by a minus sign if and only if the result is negative. The value units is produced as if by255

for (int i = 0; i < n; ++i)
  buf2[i] = src[find(atoms, atoms+sizeof(src), buf1[i]) - atoms];
buf2[n] = 0;
sscanf(buf2, "%Lf", &units);

where n is the number of characters placed in buf1, buf2 is a character buffer, and the values src and atoms are defined as if by

static const char src[] = "0123456789-";
charT atoms[sizeof(src)];
ct.widen(src, src + sizeof(src) - 1, atoms);

Returns: An iterator pointing immediately beyond the last character recognized as part of a valid monetary quantity.

Returns: do_put(s, intl, f, loc, quant)

Effects: Writes characters to s according to the format specified by a moneypunct<charT,Intl> facet reference mp and the character mapping specified by a ctype<charT> facet reference ct obtained from the locale returned by str.getloc(), and str.flags(). The argument units is transformed into a sequence of wide characters as if by

ct.widen(buf1, buf1 + sprintf(buf1, "%.0Lf", units), buf2)

for character buffers buf1 and buf2. If the first character in digits or buf2 is equal to ct.widen('-'), then the pattern used for formatting is the result of mp.neg_format(); otherwise the pattern is the result of mp.pos_format(). Digit characters are written, interspersed with any thousands separators and decimal point specified by the format, in the order they appear (after the optional leading minus sign) in digits or buf2. In digits, only the optional leading minus sign and the immediately subsequent digit characters (as classified according to ct) are used; any trailing characters (including digits appearing after a non-digit character) are ignored. Calls str.width(0).

Remarks: The currency symbol is generated if and only if (str.flags() & str.showbase) is nonzero. If the number of characters generated for the specified format is less than the value returned by str.width() on entry to the function, then copies of fill are inserted as necessary to pad to the specified width. For the value af equal to (str.flags() & str.adjustfield), if (af == str.internal) is true, the fill characters are placed where none or space appears in the formatting pattern; otherwise if (af == str.left) is true, they are placed after the other characters; otherwise, they are placed before the other characters. [ Note: It is possible, with some combinations of format patterns and flag values, to produce output that cannot be parsed using num_get<>::get.  — end note ]

Returns: An iterator pointing immediately after the last character produced.

Returns: The radix separator to use in case do_frac_digits() is greater than zero.257

Returns: The digit group separator to use in case do_grouping() specifies a digit grouping pattern.258

Returns: A pattern defined identically as, but not necessarily equal to, the result of numpunct<charT>::do_grouping().259

Returns: A string to use as the currency identifier symbol.260

Returns: do_positive_sign() returns the string to use to indicate a positive monetary value;261 do_negative_sign() returns the string to use to indicate a negative value.

Returns: The number of digits after the decimal radix separator, if any.262

Returns: The specializations required in Table [tab:localization.required.specializations] ([locale.category]), namely moneypunct<char>, moneypunct<wchar_t>, moneypunct<char,true>, and moneypunct<wchar_t,true>, return an object of type pattern initialized to { symbol, sign, none, value }.263

Returns: do_open(name, loc).

Returns: do_get(cat, set, msgid, dfault).

Effects: Calls do_close(cat).

Returns: A value that may be passed to get() to retrieve a message from the message catalog identified by the string name according to an implementation-defined mapping. The result can be used until it is passed to close().

Returns a value less than 0 if no such catalog can be opened.

Remarks: The locale argument loc is used for character set code conversion when retrieving messages, if needed.

Requires: cat shall be a catalog obtained from open() and not yet closed.

Returns: A message identified by arguments set, msgid, and dfault, according to an implementation-defined mapping. If no such message can be found, returns dfault.

Requires: cat shall be a catalog obtained from open() and not yet closed.

Effects: Releases unspecified resources associated with cat.

Remarks: The limit on such resources, if any, is implementation-defined.