result unshift ( stateT& state,
externT* to, externT* to_limit, externT*& to_next ) const;
Unshift translation state
During a character encoding translation initiated by codecvt::out the state may be shifted to some state other than the state by default if the destination range could not absorb all the characters produced by the translation.
By calling member unshift the translation of the particular sequence can be finished properly by providing more storage capacity where to write the remainder at the location pointed by to. The function does not attempt to store more characters once to_limit is reached.
When the function returns, to_next points to one beyond the last element successfully converted.
If the destination range can still not absorb all the characters remaining to be translated, it returns codecvt::partial.
On success, it returns codecvt::ok.
During its operation, this function simply calls the virtual protected member codecvt::do_unshift, which is the member function in charge of performing the actions described above.
Parameters
- state
- State object to keep track of the state of a multibyte character conversion. Typically, this is an object of type mbstate_t with its state shifted to some value other than its default value by a call to codecvt::out.
stateT is the state type (i.e., the third template parameter of codecvt).
- to, to_limit
- Pointer to the initial and final characters of the destination sequence. The range used is [to,to_limit), which contains all the characters between to and to_limit, including the character pointed by to but not the character pointed by to_limit.
A translation does not necessarily need to fill up the range to its limit, and may also exhaust it (in which case it returns codecvt::partial).
externT is the external character type (i.e., the second template parameter of codecvt).
- to_next
- Pointer type able to point to an element in the above range. Once the function returns, this object points to the element in the destination range beyond the last one successfully translated.
Return value
An object of type codecvt::result, with the following possible values:
| value | result |
|---|
| ok | Sequence conversion completed |
| partial | Sequence not completed. More characters needed to complete sequence conversion. |
| error | Argument state has an invalid value |
| noconv | This type of stateT object does not require termination |
See also
| codecvt::out | Translate out characters (public member function) |
|