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

247
cppdraft/locale/codecvt/virtuals.md Normal file
View File

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