depish/cppdraft_translate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Init

Browse Source
This commit is contained in:
Leonov Artur (Depish)
2025-10-25 03:02:53 +03:00
commit 043225d523
3416 changed files with 681196 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

388
cppdraft/locale/codecvt.md Normal file
View File

@@ -0,0 +1,388 @@
[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)