wcstombs - cppreference.com

##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# wcstombs

From cppreference.com
< c‎ | string‎ | multibyte

Defined in header `<stdlib.h>` |  |
size_t wcstombs( char *dst, const wchar_t *src, size_t len ); |  | (until C99)
size_t wcstombs( char *restrict dst, const wchar_t *restrict src, size_t len ); |  | (since C99)

Converts a sequence of wide characters from the array whose first element is pointed to by `src` to its narrow multibyte representation that begins in the initial shift state. Converted characters are stored in the successive elements of the char array pointed to by `dst`. No more than `len` bytes are written to the destination array.

Each character is converted as if by a call to wctomb, except that the wctomb's conversion state is unaffected. The conversion stops if:

- The null character was converted and stored.
- A wchar_t was found that does not correspond to a valid character in the current C locale.
- The next multibyte character to be stored would exceed `len`.

### [edit] Notes

In most implementations, this function updates a global static object of type mbstate_t as it processes through the string, and cannot be called simultaneously by two threads, wcsrtombs should be used in such cases.

POSIX specifies a common extension: if `dst` is a null pointer, this function returns the number of bytes that would be written to `dst`, if converted. Similar behavior is standard for wcsrtombs.

### [edit] Parameters

dst | - | pointer to narrow character array where the multibyte character will be stored
src | - | pointer to the first element of a null-terminated wide string to convert
len | - | number of bytes available in the array pointed to by dst

### [edit] Return value

On success, returns the number of bytes (including any shift sequences, but excluding the terminating '\0') written to the character array whose first element is pointed to by `dst`.

On conversion error (if invalid wide character was encountered), returns (size_t)-1.

### [edit] Example

Run this code

    #include <stdio.h>
    #include <stdlib.h>
    #include <locale.h>

    int main ()
    {
        // 4 wide characters
        const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
        // they occupy 10 bytes in UTF-8
        char dst[11];

        setlocale(LC_ALL, "en_US.utf8");
        printf("wide-character string: '%ls'\n",src);
        for (size_t ndx=0; ndx < sizeof src/sizeof src[0]; ++ndx)
            printf("   src[%2zu] = %#8x\n", ndx, src[ndx]);

        int rtn_val = wcstombs(dst, src, sizeof dst);
        printf("rtn_val = %d\n", rtn_val);
        if (rtn_val > 0)
            printf("multibyte string:  '%s'\n",dst);
        for (size_t ndx=0; ndx<sizeof dst; ++ndx)
            printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
    }

Output:

    wide-character string: 'zß水🍌'
       src[ 0] =     0x7a
       src[ 1] =     0xdf
       src[ 2] =   0x6c34
       src[ 3] =  0x1f34c
       src[ 4] =        0
    rtn_val = 10
    multibyte string:  'zß水🍌'
       dst[ 0] = 0x7a
       dst[ 1] = 0xc3
       dst[ 2] = 0x9f
       dst[ 3] = 0xe6
       dst[ 4] = 0xb0
       dst[ 5] = 0xb4
       dst[ 6] = 0xf0
       dst[ 7] = 0x9f
       dst[ 8] = 0x8d
       dst[ 9] = 0x8c
       dst[10] =  0

### [edit] See also

wcsrtombs | converts a wide string to narrow multibyte character string, given state (function) [edit]
mbstowcs | converts a narrow multibyte character string to wide string (function) [edit]
C++ documentation for wcstombs

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=c/string/multibyte/wcstombs&oldid=67379"