public member function
<locale>
result unshift (state_type& state, extern_type* to, extern_type* to_limit, extern_type*& to_next) const;
Unshift translation state
Writes into to the sequence of character needed to unshift the state of state.
During a character encoding translation (such as the one initiated by codecvt::out), the state may have been shifted to some state other than the state by default, notably when the destination range could not absorb all the characters produced by the translation. By calling this function with additional storage, the remainder of the sequence needed to return the shift state to its default state is written to to (taking up to to_limit).
When the function returns, to_next points to one beyond the last element successfully written.
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.
Internally, this function simply calls the virtual protected member do_unshift, which behaves as described above by default.
Parameters
- state
- A state object, as required by the facet instantiation.
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).
Member type state_type is the facet's state type (defined as an alias of codecvt's third template parameter, stateT).
- to, to_limit
- Pointer to the initial and final characters of the destination sequence. The range used is, at most,
[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.
An unshift operation does not necessarily need to fill up the range to its limit, and may also exhaust it before finishing.
Member type extern_type is the facet's external character type (defined as an alias of codecvt's second template parameter, externT).
- to_next
- Pointer 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 written.
Return value
A value of type codecvt_base::result, with the following possible values:
| member constant | int value | result |
|---|
| ok | 0 | Conversion successful: all characters needed to unshift the state were successfully wirtten. |
| partial | 1 | Partial conversion: the destination sequence [to,to_limit) is not long enough.
The range [to,to_limit) has been filled with the partial result. The function may be called again with additional storage to obtain more unshift characters. |
| error | 2 | Conversion error: Some unspecified error occurred, such as state in an invalid state. |
| noconv | 3 | No conversion: The current state of state does not need to be unshifted. |
Data races
The facet object is accessed.
The arguments state and to_next, along with up to all the characters in the range [to,to_limit) are modified.
Exception safety
If an exception is thrown, there are no changes in the facet object, although characters in the destination range and to_next may have been affected.
See also
- codecvt::out
- Translate out characters (public member function)
- codecvt::do_unshift
- Unshift translation state [virtual] (protected virtual member function)