| Functions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Wide/multibyte conversions | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
(C95) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Types | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Macros | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Defined in header <stdlib.h> | ||
int wctomb(char*s,wchar_t wc); | (1) | |
errno_t wctomb_s(int*restrict status,char*restrict s, rsize_t ssz,wchar_t wc); | (2) | (since C11) |
wc to multibyte encoding and stores it (including any shift sequences) in the char array whose first element is pointed to bys. No more thanMB_CUR_MAX characters are stored. The conversion is affected by the current locale's LC_CTYPE category.wc is the null character, the null byte is written tos, preceded by any shift sequences necessary to restore the initial shift state.s is a null pointer, this function resets the global conversion state and determines whether shift sequences are used.status and the following errors are detected at runtime and call the currently installedconstraint handler function:ssz is less than the number of bytes that would be written (unlesss is null)ssz is greater thanRSIZE_MAX (unlesss is null)s is a null pointer butssz is not zerowctomb_s is only guaranteed to be available if__STDC_LIB_EXT1__ is defined by the implementation and if the user defines__STDC_WANT_LIB_EXT1__ to the integer constant1 before including<stdlib.h>.Contents |
Each call towctomb updates the internal global conversion state (a static object of typembstate_t, known only to this function). If the multibyte encoding uses shift states, this function is not reentrant. In any case, multiple threads should not callwctomb without synchronization:wcrtomb orwctomb_s may be used instead.
Unlike most bounds-checked functions,wctomb_s does not null-terminate its output, because it is designed to be used in loops that process strings character-by-character.
| s | - | pointer to the character array for output |
| wc | - | wide character to convert |
| ssz | - | maximum number of bytes to write tos (size of the arrays) |
| status | - | pointer to an out-parameter where the result (length of the multibyte sequence or the shift sequence status) will be stored |
s is not a null pointer, returns the number of bytes that are contained in the multibyte representation ofwc or-1 ifwc is not a valid character.s is a null pointer, resets its internal conversion state to represent the initial shift state and returns0 if the current multibyte encoding is not state-dependent (does not use shift sequences) or a non-zero value if the current multibyte encoding is state-dependent (uses shift sequences).wc is stored ins and its length is stored in*status, or, ifs is null, the shift sequence status is stored instatus). Non-zero on encoding error or runtime constraint violation, in which case(size_t)-1 is stored in*status. The value stored in*status never exceedsMB_CUR_MAX#include <stdio.h>#include <stdlib.h>#include <locale.h> void demo(wchar_t wc){constchar* dep= wctomb(NULL, wc)?"Yes":"No";printf("State-dependent encoding? %s.\n", dep); char mb[MB_CUR_MAX];int len= wctomb(mb, wc);printf("wide char '%lc' -> multibyte char [", wc);for(int idx=0; idx< len;++idx)printf("%s%#2x", idx?" ":"",(unsignedchar)mb[idx]);printf("]\n");} int main(void){setlocale(LC_ALL,"en_US.utf8");printf("MB_CUR_MAX = %zu\n", MB_CUR_MAX); demo(L'A'); demo(L'\u00df'); demo(L'\U0001d10b');}
Possible output:
MB_CUR_MAX = 6State-dependent encoding? No.wide char 'A' -> multibyte char [0x41]State-dependent encoding? No.wide char 'ß' -> multibyte char [0xc3 0x9f]State-dependent encoding? No.wide char '𝄋' -> multibyte char [0xf0 0x9d 0x84 0x8b]
| converts the next multibyte character to wide character (function)[edit] | |
(C95)(C11) | converts a wide character to its multibyte representation, given state (function)[edit] |
C++ documentation forwctomb | |
