Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <wchar.h>
    int wcrtomb( char *s, wchar_t wc, mbstate_t *ps );
    int _fwcrtomb( char __far *s, wchar_t wc, mbstate_t __far *ps );

Description:
    If s is a null pointer, the wcrtomb function determines the number of
    bytes necessary to enter the initial shift state (zero if encodings are
    not state-dependent or if the initial conversion state is described).
     The resulting state described will be the initial conversion state.

    If s is not a null pointer, the wcrtomb function determines the number
    of bytes needed to represent the multibyte character that corresponds to
    the wide character given by wc (including any shift sequences), and
    stores the resulting bytes in the array whose first element is pointed
    to by s.  At most  MB_CUR_MAX bytes will be stored.  If wc is a null
    wide character, the resulting state described will be the initial
    conversion state.

    The _fwcrtomb function is a data model independent form of the wcrtomb
    function that accepts far pointer arguments.  It is most useful in mixed
    memory model applications.

    The restartable multibyte/wide character conversion functions differ
    from the corresponding internal-state multibyte character functions (
     mblen,  mbtowc, and  wctomb) in that they have an extra argument, ps,
    of type pointer to  mbstate_t that points to an object that can
    completely describe the current conversion state of the associated
    multibyte character sequence.  If ps is a null pointer, each function
    uses its own internal  mbstate_t object instead.  You are guaranteed
    that no other function in the library calls these functions with a null
    pointer for ps, thereby ensuring the stability of the state.

    Also unlike their corresponding functions, the return value does not
    represent whether the encoding is state-dependent.

    If the encoding is state-dependent, on entry each function takes the
    described conversion state (either internal or pointed to by ps) as
    current.  The conversion state described by the pointed-to object is
    altered as needed to track the shift state of the associated multibyte
    character sequence.  For encodings without state dependency, the pointer
    to the  mbstate_t argument is ignored.

Returns:
    If s is a null pointer, the wcrtomb function returns the number of bytes
    necessary to enter the initial shift state.  The value returned will not
    be greater than that of the  MB_CUR_MAX macro.

    If s is not a null pointer, the wcrtomb function returns the number of
    bytes stored in the array object (including any shift sequences) when wc
    is a valid wide character; otherwise (when wc is not a valid wide
    character), an encoding error occurs, the value of the macro  EILSEQ
    will be stored in  errno and -1 will be returned, but the conversion
    state will be unchanged.


Example:
    #include <stdio.h>
    #include <wchar.h>
    #include <mbctype.h>
    #include <errno.h>

    const wchar_t wc[] = {
        0x0020,
        0x002e,
        0x0031,
        0x0041,
        0x3000,     /* double-byte space */
        0xff21,     /* double-byte A */
        0x3048,     /* double-byte Hiragana */
        0x30a3,     /* double-byte Katakana */
        0xff61,     /* single-byte Katakana punctuation */
        0xff66,     /* single-byte Katakana alphabetic */
        0xff9f,     /* single-byte Katakana alphabetic */
        0x720d,     /* double-byte Kanji */
        0x0000
    };

    #define SIZE sizeof( wc ) / sizeof( wchar_t )

    void main()
    {
        int         i, j, k;
        char        s[2];

        _setmbcp( 932 );
        i = wcrtomb( NULL, 0, NULL );
        printf( "Number of bytes to enter "
                "initial shift state = %d\n", i );
        j = 1;
        for( i = 0; i < SIZE; i++ ) {
            j = wcrtomb( s, wc[i], NULL );
            printf( "%d bytes in character ", j );
            if( errno == EILSEQ ) {
              printf( " - illegal wide character\n" );
            } else {
              if ( j == 0 ) {
                  k = 0;
              } else if ( j == 1 ) {
                  k = s[0];
              } else if( j == 2 ) {
                  k = s[0]<<8 | s[1];
              }
              printf( "(%#6.4x->%#6.4x)\n", wc[i], k );
            }
        }
    }

    produces the following:

    Number of bytes to enter initial shift state = 0
    1 bytes in character (0x0020->0x0020)
    1 bytes in character (0x002e->0x002e)
    1 bytes in character (0x0031->0x0031)
    1 bytes in character (0x0041->0x0041)
    2 bytes in character (0x3000->0x8140)
    2 bytes in character (0xff21->0x8260)
    2 bytes in character (0x3048->0x82a6)
    2 bytes in character (0x30a3->0x8342)
    1 bytes in character (0xff61->0x00a1)
    1 bytes in character (0xff66->0x00a6)
    1 bytes in character (0xff9f->0x00df)
    2 bytes in character (0x720d->0xe0a1)
    1 bytes in character (  0000->0x0069)

Classification:
    wcrtomb is ANSI, _fwcrtomb is not ANSI

Systems:
     wcrtomb - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

    _fwcrtomb - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

See Also:
    _mbccmp, _mbccpy, _mbcicmp, _mbcjistojms, _mbcjmstojis, _mbclen,
    _mbctohira, _mbctokata, _mbctolower, _mbctombb, _mbctoupper, mblen,
    mbrlen, mbrtowc, mbsrtowcs, mbstowcs, mbtowc, sisinit, wcsrtombs,
    wcstombs, wctob, wctomb