wcstombs, wcstombs_s
cppreference.net에서
| 헤더에 정의됨 <stdlib.h>
|
||
size_t wcstombs( char* dst, const wchar_t* src, size_t len );
|
(1) | (C99까지) |
size_t wcstombs( char* restrict dst, const wchar_t* restrict src, size_t len );
|
(C99부터) | |
errno_t wcstombs_s( size_t* restrict retval, char* restrict dst, rsize_t dstsz,
const wchar_t* restrict src, rsize_t len );
|
(2) | (C11부터) |
1) 와이드 문자 시퀀스를 첫 번째 요소가
src 가 가리키는 배열에서 초기 시프트 상태로 시작하는 좁은 멀티바이트 표현으로 변환합니다. 변환된 문자는 dst 이 가리키는 char 배열의 연속된 요소에 저장됩니다. 최대 len 바이트까지만 대상 배열에 기록됩니다. 각 문자는 wctomb 호출에 의해 변환되는 것처럼 처리되지만, wctomb의 변환 상태는 영향을 받지 않습니다. 변환은 다음 조건 중 하나가 발생하면 중지됩니다:
- 널 문자
L'\0'가 변환되어 저장되었습니다. 이 경우 저장된 바이트는 (필요한 경우) 언시프트 시퀀스 다음에'\0', - 하나의
wchar_t가 현재 C 로케일의 유효한 문자에 해당하지 않는 것으로 발견되었습니다. - 저장할 다음 멀티바이트 문자가
len를 초과합니다.
만약
src 와 dst 가 겹치면, 동작은 명시되지 않습니다.2) (1)과 동일하지만, (1) 다음 예외가 있습니다:
- 변환은 wcrtomb 에 의해 수행되는 것처럼 처리되며, wctomb
- 함수는 결과를 출력 매개변수로 반환합니다
retval - 변환이 널 문자를 쓰지 않고 중지되면, 함수는
'\0'의 다음 바이트에 저장합니다dst(이는dst[len]또는dst[dstsz]중 먼저 오는 위치). 즉, 최대 len+1/dstsz+1 바이트가 기록될 수 있습니다. 이 경우 종료 널 앞에 언시프트 시퀀스가 기록되지 않을 수 있습니다. - 만약
dst가 널 포인터이면, 생성될 바이트 수가*retval - 에 저장됩니다. 함수는 종료 널부터
dstsz - 만약
src와dst가 겹치면, 동작은 명시되지 않습니다. - 다음 오류가 런타임에 감지되어 현재 설치된 제약 조건 핸들러 함수를 호출합니다:
retval또는src가 널 포인터입니다dstsz또는len가 RSIZE_MAX 보다 큽니다 (dst가 널인 경우 제외)dstsz가 0이 아닙니다 (dst가 널인 경우 제외)len가dstsz보다 크고, 변환이src배열에서dstsz에 도달할 때까지 널 또는 인코딩 오류를 만나지 않습니다 (dst가 널인 경우 제외)
wcstombs_s 는 다음 조건에서만 사용 가능함이 보장됩니다: __STDC_LIB_EXT1__ 이 구현에 의해 정의되고, 사용자가 __STDC_WANT_LIB_EXT1__ 를 정수 상수 1 로 정의한 후, <stdlib.h>를 포함해야 합니다.참고
대부분의 구현에서, wcstombs 는 mbstate_t 타입의 전역 정적 객체를 업데이트하며, 두 스레드에서 동시에 호출될 수 없습니다. 따라서 이러한 경우 wcsrtombs 또는 wcstombs_s 를 사용해야 합니다.
POSIX는 일반적인 확장을 지정합니다: 만약 dst 가 널 포인터이면, 이 함수는 변환 시 dst 에 기록될 바이트 수를 반환합니다. 유사한 동작이 wcsrtombs 및 wcstombs_s에 대해 표준입니다.
매개변수
| dst | - | 멀티바이트 문자가 저장될 좁은 문자 배열을 가리키는 포인터 |
| src | - | 변환할 널 종료 와이드 문자열의 첫 번째 요소를 가리키는 포인터 |
| len | - | dst가 가리키는 배열에서 사용 가능한 바이트 수 |
| dstsz | - | 기록될 최대 바이트 수 (dst 배열의 크기)
|
| retval | - | 결과가 저장될 size_t 객체를 가리키는 포인터 |
반환값
1)
성공 시, (모든 시프트 시퀀스를 포함하지만 종료
'\0' 는 제외한) 첫 번째 요소가 dst 가 가리키는 문자 배열에 기록된 바이트 수를 반환합니다. 변환 오류(유효하지 않은 와이드 문자가 발견된 경우) 시 (size_t)-1를 반환합니다.
2)
성공 시 0을 반환합니다(이 경우 종료 0을 제외하고
dst 에 기록되었거나 기록될 바이트 수가 *retval 에 저장됨). 오류 시 0이 아닌 값을 반환합니다. 런타임 제약 조건 위반 시, (size_t)-1 를 *retval 에 저장하고 ( retval 가 널이 아닌 경우), dst[0] 를 '\0' 로 설정합니다 ( dst 가 널이거나 dstmax 가 0이거나 RSIZE_MAX보다 큰 경우 제외)
예제
이 코드 실행
#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
int main(void)
{
// 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]);
}
출력:
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
참조
- C23 표준 (ISO/IEC 9899:2024):
- 7.22.8.2 wcstombs 함수 (p: TBD)
- K.3.6.5.2 wcstombs_s 함수 (p: TBD)
- C17 표준 (ISO/IEC 9899:2018):
- 7.22.8.2 wcstombs 함수 (p: TBD)
- K.3.6.5.2 wcstombs_s 함수 (p: TBD)
- C11 표준 (ISO/IEC 9899:2011):
- 7.22.8.2 wcstombs 함수 (p: 360)
- K.3.6.5.2 wcstombs_s 함수 (p: 612-614)
- C99 표준 (ISO/IEC 9899:1999):
- 7.20.8.2 wcstombs 함수 (p: 324)
- C89/C90 표준 (ISO/IEC 9899:1990):
- 4.10.8.2 wcstombs 함수
같이 보기
(C95)
(C11)
|
와이드 문자열을 주어진 상태에서 좁은 멀티바이트 문자열로 변환합니다 (함수) |
(C11)
|
좁은 멀티바이트 문자열을 와이드 문자열로 변환합니다 (함수) |
C++ 문서
대하여 wcstombs
| |