cppdraft_translate/cppdraft/locale/codecvt/virtuals.md

[locale.codecvt.virtuals]

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

## 28.3 Localization library [[localization]](localization#locale.codecvt.virtuals)

### 28.3.4 Standard locale categories [[locale.categories]](locale.categories#locale.codecvt.virtuals)

#### 28.3.4.2 The ctype category [[category.ctype]](category.ctype#locale.codecvt.virtuals)

#### 28.3.4.2.5 Class template codecvt [[locale.codecvt]](locale.codecvt#virtuals)

#### 28.3.4.2.5.3 Virtual functions [locale.codecvt.virtuals]

[🔗](#lib:codecvt,do_out)

`result do_out(
  stateT& state,
  const internT* from, const internT* from_end, const internT*& from_next,
  externT* to, externT* to_end, externT*& to_next) const;

result do_in(
  stateT& state,
  const externT* from, const externT* from_end, const externT*& from_next,
  internT* to, internT* to_end, internT*& to_next) const;
`

[1](#1)

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

*Preconditions*: (from <= from_end && to <= to_end) is well-defined and true;state is initialized, if at the beginning of a sequence,
or else is equal to the result of converting
the preceding characters in the sequence[.](#1.sentence-1)

[2](#2)

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

*Effects*: Translates characters in the source range [from, from_end),
placing the results in sequential positions starting at destination to[.](#2.sentence-1)

Converts no more than (from_end - from) source elements, and
stores no more than (to_end - to) destination elements[.](#2.sentence-2)

[3](#3)

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

Stops if it encounters a character it cannot convert[.](#3.sentence-1)

It always leaves the from_next and to_next pointers
pointing one beyond the last element successfully converted[.](#3.sentence-2)

If it 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)[.](#3.sentence-3)

[4](#4)

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

A codecvt facet
that is used by basic_filebuf ([[file.streams]](file.streams "31.10 File-based streams"))
shall have the property that ifdo_out(state, from, from_end, from_next, to, to_end, to_next) would return ok,
where from != from_end,
thendo_out(state, from, from + 1, from_next, to, to_end, to_next) shall also return ok,
and that ifdo_in(state, from, from_end, from_next, to, to_end, to_next) would return ok,
where to != to_end,
thendo_in(state, from, from_end, from_next, to, to + 1, to_next) shall also return ok[.](#4.sentence-1)[220](#footnote-220 "Informally, this means that basic_­filebuf assumes that the mappings from internal to external characters is 1 to N: that a codecvt facet that is used by basic_­filebuf can translate characters one internal character at a time.")

[*Note [1](#note-1)*:

As a result of operations on state,
it can return ok or partial and
set from_next == from and to_next != to[.](#4.sentence-2)

— *end note*]

[5](#5)

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

*Returns*: An enumeration value, as summarized in Table [93](#tab:locale.codecvt.inout "Table 93: do_­in/do_­out result values")[.](#5.sentence-1)

Table [93](#tab:locale.codecvt.inout) — do_in/do_out result values [[tab:locale.codecvt.inout]](./tab:locale.codecvt.inout)  

| [🔗](#tab:locale.codecvt.inout-row-1)<br>**Value** | **Meaning** |
| --- | --- |
| [🔗](#tab:locale.codecvt.inout-row-2)<br>ok | completed the conversion |
| [🔗](#tab:locale.codecvt.inout-row-3)<br>partial | not all source characters converted |
| [🔗](#tab:locale.codecvt.inout-row-4)<br>error | encountered a character in [from, from_end) that cannot be converted |
| [🔗](#tab:locale.codecvt.inout-row-5)<br>noconv | internT and externT are the same type, and input sequence is identical to converted sequence |

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[.](#5.sentence-2)

[6](#6)

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

*Remarks*: Its operations on state are unspecified[.](#6.sentence-1)

[*Note [2](#note-2)*:

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[.](#6.sentence-2)

— *end note*]

[🔗](#lib:codecvt,do_unshift)

`result do_unshift(stateT& state, externT* to, externT* to_end, externT*& to_next) const;
`

[7](#7)

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

*Preconditions*: (to <= to_end) is well-defined and true;state is initialized, if at the beginning of a sequence,
or else is equal to the result of converting
the preceding characters in the sequence[.](#7.sentence-1)

[8](#8)

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

*Effects*: Places characters starting at to that should be appended to terminate a sequence
when the current stateT is given by state[.](#8.sentence-1)[221](#footnote-221 "Typically these will be characters to return the state to stateT().")

Stores no more than (to_end - to) destination elements, and
leaves the to_next pointer
pointing one beyond the last element successfully stored[.](#8.sentence-2)

[9](#9)

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

*Returns*: An enumeration value, as summarized in Table [94](#tab:locale.codecvt.unshift "Table 94: do_­unshift result values")[.](#9.sentence-1)

Table [94](#tab:locale.codecvt.unshift) — do_unshift result values [[tab:locale.codecvt.unshift]](./tab:locale.codecvt.unshift)  

| [🔗](#tab:locale.codecvt.unshift-row-1)<br>**Value** | **Meaning** |
| --- | --- |
| [🔗](#tab:locale.codecvt.unshift-row-2)<br>ok | completed the sequence |
| [🔗](#tab:locale.codecvt.unshift-row-3)<br>partial | space for more than to_end - to destination elements was needed to terminate a sequence given the value of state |
| [🔗](#tab:locale.codecvt.unshift-row-4)<br>error | an unspecified error has occurred |
| [🔗](#tab:locale.codecvt.unshift-row-5)<br>noconv | no termination is needed for this state_type |

[🔗](#lib:codecvt,do_encoding)

`int do_encoding() const noexcept;
`

[10](#10)

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

*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[.](#10.sentence-1)[222](#footnote-222 "If encoding() yields -1, then more than max_­length() externT elements can be consumed when producing a single internT character, and additional externT elements can appear at the end of a sequence after those that yield the final internT character.")

[🔗](#lib:codecvt,do_always_noconv)

`bool do_always_noconv() const noexcept;
`

[11](#11)

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

*Returns*: true if do_in() and do_out() return noconv for all valid argument values[.](#11.sentence-1)

codecvt<char, char, mbstate_t> returns true[.](#11.sentence-2)

[🔗](#lib:codecvt,do_length)

`int do_length(stateT& state, const externT* from, const externT* from_end, size_t max) const;
`

[12](#12)

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

*Preconditions*: (from <= from_end) is well-defined and true;state is initialized, if at the beginning of a sequence,
or else is equal to the result of converting
the preceding characters in the sequence[.](#12.sentence-1)

[13](#13)

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

*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[.](#13.sentence-1)

[14](#14)

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

*Returns*: (from_next - from) wherefrom_next is the largest value in the range [from, from_end]
such that the sequence of values in the range [from, from_next)
representsmax or fewer valid complete characters of type internT[.](#14.sentence-1)

The specialization codecvt<char, char, mbstate_t>,
returns the lesser of max and (from_end - from)[.](#14.sentence-2)

[🔗](#lib:codecvt,do_max_length)

`int do_max_length() const noexcept;
`

[15](#15)

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

*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[.](#15.sentence-1)

The specialization codecvt<char, char, mbstate_t>​::​do_max_length() returns 1[.](#15.sentence-2)

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

Informally, this means that basic_filebuf assumes that the mappings from internal to external characters is 1 to N:
that a codecvt facet that is used by basic_filebuf can translate characters one internal character at a time[.](#footnote-220.sentence-1)

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

Typically these will be characters to return the state to stateT()[.](#footnote-221.sentence-1)

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

If encoding() yields -1,
then more than max_length() externT elements
can be consumed when producing a single internT character, and
additional externT elements can appear at the end of a sequence
after those that yield the final internT character[.](#footnote-222.sentence-1)