[locale.codecvt]

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

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

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

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

#### 28.3.4.2.5 Class template codecvt [locale.codecvt]

#### [28.3.4.2.5.1](#general) General [[locale.codecvt.general]](locale.codecvt.general)

[🔗](#lib:codecvt)

namespace std {class codecvt_base {public:enum result { ok, partial, error, noconv }; }; template<class internT, class externT, class stateT>class codecvt : public locale::facet, public codecvt_base {public:using intern_type = internT; using extern_type = externT; using state_type = stateT; explicit codecvt(size_t refs = 0);

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

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

 result in( stateT& state, const externT* from, const externT* from_end, const externT*& from_next,
 internT* to, internT* to_end, internT*& to_next) const; int encoding() const noexcept; bool always_noconv() const noexcept; int length(stateT&, const externT* from, const externT* end, size_t max) const; int max_length() const noexcept; static locale::id id; protected:~codecvt(); virtual 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; virtual 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; virtual result do_unshift( stateT& state,
 externT* to, externT* to_end, externT*& to_next) const; virtual int do_encoding() const noexcept; virtual bool do_always_noconv() const noexcept; virtual int do_length(stateT&, const externT* from, const externT* end, size_t max) const; virtual int do_max_length() const noexcept; };}

[1](#general-1)

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

The class codecvt<internT, externT, stateT> is for use
when converting from one character encoding to another,
such as from wide characters to multibyte characters or
between wide character encodings such as UTF-32 and EUC[.](#general-1.sentence-1)

[2](#general-2)

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

The stateT argument selects
the pair of character encodings being mapped between[.](#general-2.sentence-1)

[3](#general-3)

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

The specializations required
in Table [91](locale.category#tab:locale.category.facets "Table 91: Locale category facets") ([[locale.category]](locale.category "28.3.3.1.2.1 Type locale​::​category"))
convert the implementation-defined native character set[.](#general-3.sentence-1)

codecvt<char, char, mbstate_t> implements a degenerate conversion;
it does not convert at all[.](#general-3.sentence-2)

codecvt<wchar_t, char, mbstate_t> converts between the native character sets for ordinary and wide characters[.](#general-3.sentence-3)

Specializations on mbstate_t perform conversion between encodings known to the library implementer[.](#general-3.sentence-4)

Other encodings can be converted by specializing on
a program-defined stateT type[.](#general-3.sentence-5)

Objects of type stateT can contain any state
that is useful to communicate to or from
the specialized do_in or do_out members[.](#general-3.sentence-6)

#### [28.3.4.2.5.2](#members) Members [[locale.codecvt.members]](locale.codecvt.members)

[🔗](#lib:codecvt,out)

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

[1](#members-1)

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

*Returns*: do_out(state, from, from_end, from_next, to, to_end, to_next)[.](#members-1.sentence-1)

[🔗](#lib:codecvt,unshift)

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

[2](#members-2)

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

*Returns*: do_unshift(state, to, to_end, to_next)[.](#members-2.sentence-1)

[🔗](#lib:codecvt,in)

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

[3](#members-3)

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

*Returns*: do_in(state, from, from_end, from_next, to, to_end, to_next)[.](#members-3.sentence-1)

[🔗](#lib:codecvt,encoding)

`int encoding() const noexcept;
`

[4](#members-4)

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

*Returns*: do_encoding()[.](#members-4.sentence-1)

[🔗](#lib:codecvt,always_noconv)

`bool always_noconv() const noexcept;
`

[5](#members-5)

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

*Returns*: do_always_noconv()[.](#members-5.sentence-1)

[🔗](#lib:codecvt,length)

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

[6](#members-6)

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

*Returns*: do_length(state, from, from_end, max)[.](#members-6.sentence-1)

[🔗](#lib:codecvt,max_length)

`int max_length() const noexcept;
`

[7](#members-7)

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

*Returns*: do_max_length()[.](#members-7.sentence-1)

#### [28.3.4.2.5.3](#virtuals) Virtual functions [[locale.codecvt.virtuals]](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](#virtuals-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[.](#virtuals-1.sentence-1)

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

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

[3](#virtuals-3)

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

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

It always leaves the from_next and to_next pointers
pointing one beyond the last element successfully converted[.](#virtuals-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)[.](#virtuals-3.sentence-3)

[4](#virtuals-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[.](#virtuals-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](#virtuals-note-1)*:

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

— *end note*]

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

[6](#virtuals-6)

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

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

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

— *end note*]

[🔗](#lib:codecvt,do_unshift)

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

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

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

[9](#virtuals-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")[.](#virtuals-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](#virtuals-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[.](#virtuals-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](#virtuals-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[.](#virtuals-11.sentence-1)

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

[🔗](#lib:codecvt,do_length)

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

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

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

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

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

[🔗](#lib:codecvt,do_max_length)

`int do_max_length() const noexcept;
`

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

The specialization codecvt<char, char, mbstate_t>​::​do_max_length() returns 1[.](#virtuals-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)