Namespaces
Variants

wcsncpy, wcsncpy_s

From cppreference.net
< c ‎ | string ‎ | wide
C
Strings library
Null-terminated wide strings
헤더 파일에 정의됨 <wchar.h>
(1)
wchar_t * wcsncpy ( wchar_t * dest, const wchar_t * src, size_t count ) ;
(C95부터)
(C99까지)
wchar_t * wcsncpy ( wchar_t * restrict dest, const wchar_t * restrict src, size_t count ) ;
(C99부터)
errno_t wcsncpy_s ( wchar_t * restrict dest, rsize_t destsz,
const wchar_t * restrict src, rsize_t count ) ;
(2) (C11부터)
1) src 가 가리키는 와이드 문자열(종료 널 와이드 문자 포함)에서 최대 count 개의 문자를 dest 가 가리키는 와이드 문자 배열로 복사합니다.
만약 count 에 도달했을 때 전체 문자열 src 가 복사되지 않은 경우, 결과 와이드 문자 배열은 null로 종료되지 않습니다.
만약 src 에서 종료 널 와이드 문자를 복사한 후에 count 에 도달하지 않으면, 총 count 개의 문자가 기록될 때까지 dest 에 추가적인 널 와이드 문자들이 기록됩니다.
문자열이 겹치는 경우, 동작은 정의되지 않습니다.
2) (1) 과 동일하지만, 이 함수는 count 까지 채우기 위해 대상 배열에 널 문자를 계속 기록하지 않고, 종료 널 문자를 기록한 후 중단합니다(소스에 널 문자가 없었던 경우 dest [ count ] 에 하나를 기록한 후 중단). 또한 런타임에 다음 오류들이 감지되어 현재 설치된 constraint handler 함수를 호출합니다:
  • src 또는 dest 가 null 포인터인 경우
  • destsz 또는 count 가 0이거나 RSIZE_MAX / sizeof ( wchar_t ) 보다 큰 경우
  • count 가 destsz 보다 크거나 같지만, destsz 가 wcsnlen_s ( src, count ) 보다 작거나 같은 경우, 즉 잘림(truncation)이 발생할 경우
  • 소스 문자열과 대상 문자열 사이에 중복(overlap)이 발생할 경우
모든 경계 검사 함수와 마찬가지로, wcsncpy_s 는 구현에 의해 __STDC_LIB_EXT1__ 가 정의되고 사용자가 <wchar.h> 를 포함하기 전에 __STDC_WANT_LIB_EXT1__ 를 정수 상수 1 로 정의한 경우에만 사용 가능함이 보장됩니다.

목차

매개변수

dest - 복사 대상 와이드 문자 배열에 대한 포인터
src - 복사할 와이드 문자열에 대한 포인터
count - 복사할 최대 와이드 문자 수
destsz - 대상 버퍼의 크기

반환값

1) dest 의 복사본을 반환합니다
2) 성공 시 0을 반환하고, 오류 시 0이 아닌 값을 반환합니다. 또한 오류 발생 시 L ' \0 ' 를 dest [ 0 ] 에 기록합니다( dest 가 null 포인터이거나 destsz 가 0이거나 RSIZE_MAX / sizeof ( wchar_t ) 보다 큰 경우는 제외). 또한 목적지 배열의 나머지 부분을 지정되지 않은 값으로 덮어쓸 수 있습니다.

참고 사항

일반적인 사용법에서, count 는 대상 배열의 요소 개수입니다.

대상 버퍼에 맞추기 위한 절단은 보안 위험이므로 wcsncpy_s 의 런타임 제약 조건 위반이지만, count 를 대상 배열의 크기에서 1을 뺀 값으로 지정하여 절단 동작을 얻는 것이 가능합니다: 이는 첫 번째 count 개의 와이드 문자를 복사하고 항상 그렇듯이 널 와이드 종결자를 추가할 것입니다: wcsncpy_s ( dst, sizeof dst / sizeof * dst, src, ( sizeof dst / sizeof * dst ) - 1 ) ;

예제

이 코드 실행 
#include <stdio.h>
#include <wchar.h>
#include <locale.h>
int main(void)
{
    const wchar_t src[] = L"わゐ";
    wchar_t dest[6] = {L'あ', L'い', L'う', L'え', L'お'};
    wcsncpy(dest, src, 4); // this will copy わゐ and repeat L'\0' two times
    puts("The contents of dest are: ");
    setlocale(LC_ALL, "en_US.utf8");
    const long dest_size = sizeof dest / sizeof *dest;
    for(wchar_t* p = dest; p-dest != dest_size; ++p) {
        *p ? printf("%lc ", *p)
           : printf("\\0 ");
    }
}

가능한 출력: 

The contents of dest are: 
わ ゐ \0 \0 お \0

참고문헌

  • C17 표준 (ISO/IEC 9899:2018):
  • 7.29.4.2.2 wcsncpy 함수 (p: 314)
  • K.3.9.2.1.2 wcsncpy_s 함수 (p: 464)
  • C11 표준 (ISO/IEC 9899:2011):
  • 7.29.4.2.2 The wcsncpy 함수 (p: 431)
  • K.3.9.2.1.2 The wcsncpy_s 함수 (p: 640-641)
  • C99 표준 (ISO/IEC 9899:1999):
  • 7.24.4.2.2 The wcsncpy function (p: 377)

참고 항목

(C95) (C11)
와이드 문자열을 다른 문자열로 복사합니다
(함수)
(C95) (C11)
두 개의 겹치지 않는 배열 사이에서 지정된 양의 와이드 문자를 복사합니다
(함수)
(C11)
한 문자열에서 다른 문자열로 지정된 양의 문자를 복사합니다
(함수)
C++ documentation for wcsncpy