In the introduction of this chapter it was said that certain character sets use a stateful encoding. I.e., the encoded values depend in some way on the previous bytes in the text.
Since the conversion functions allow converting a text in more than one step we must have a way to pass this information from one call of the functions to another.
mbstate_t
can contain all the information
about the shift state needed from one call to a conversion
function to another.
This type is defined in `wchar.h'. It got introduced in Amendment 1 to ISO C90.
To use objects of this type the programmer has to define such objects (normally as local variables on the stack) and pass a pointer to the object to the conversion functions. This way the conversion function can update the object if the current multibyte character set is stateful.
There is no specific function or initializer to put the state object in any specific state. The rules are that the object should always represent the initial state before the first use and this is achieved by clearing the whole variable with code such as follows:
{ mbstate_t state; memset (&state, '\0', sizeof (state)); /* from now on state can be used. */ ... }
When using the conversion functions to generate output it is often necessary to test whether the current state corresponds to the initial state. This is necessary, for example, to decide whether or not to emit escape sequences to set the state to the initial state at certain sequence points. Communication protocols often require this.
This function was introduced in Amendment 1 to ISO C90 and is declared in `wchar.h'.
Code using this function often looks similar to this:
{ mbstate_t state; memset (&state, '\0', sizeof (state)); /* Use state. */ ... if (! mbsinit (&state)) { /* Emit code to return to initial state. */ const wchar_t empty[] = L""; const wchar_t *srcp = empty; wcsrtombs (outbuf, &srcp, outbuflen, &state); } ... }
The code to emit the escape sequence to get back to the initial state is
interesting. The wcsrtombs
function can be used to determine the
necessary output code (see section Converting Multibyte and Wide Character Strings). Please note that on
GNU systems it is not necessary to perform this extra action for the
conversion from multibyte text to wide character text since the wide
character encoding is not stateful. But there is nothing mentioned in
any standard which prohibits making wchar_t
using a stateful
encoding.
Go to the first, previous, next, last section, table of contents.