wcsncpy, wcsncpy_s

Defined in header `<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) Копирует не более count символов широкой строки, на которую указывает src, (включая завершающий нулевой широкий символ) в массив широких символов, на который указывает dest.

Если count достигнуто до того, как вся строка src была скопирована, результирующий массив широких символов не завершается нулём.

Если после копирования завершающего нулевого широкого символа из src, count не достигнуто, дополнительные нулевые широкие символы записываются в dest до тех пор, пока не будет записано всего count символов.

Если строки перекрываются, поведение не определено.

2) Аналогично (1), за исключением того, что функция не продолжает запись нулей в целевой массив для дополнения до count, она останавливается после записи завершающего нулевого символа (если в источнике не было нуля, она записывает его в dest[count] и затем останавливается). Кроме того, следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную функцию обработчика ограничений обработчика ограничений:

src или dest — указатель null
destsz или count равно нулю или больше RSIZE_MAX/sizeof(wchar_t)
count больше или равно destsz, но destsz меньше или равно wcsnlen_s(src, count), другими словами, произойдёт усечение
произойдёт перекрытие между исходной и целевой строками

Как и во всех функциях с проверкой границ, wcsncpy_s гарантировано доступен только в том случае, если __STDC_LIB_EXT1__ определено реализацией, и если пользователь определяет __STDC_WANT_LIB_EXT1__ в качестве целочисленной константы 1 перед включением <wchar.h>.

Параметры

dest	-	указатель на массив широких символов, в который копируется
src	-	указатель на широкую строку, из которой копируется
count	-	максимальное количество широких символов для копирования
destsz	-	размер буфера назначения

Возвращаемое значение

1) возвращает копию dest

2) возвращает ноль при успехе, ненулевое значение при ошибке. Также при ошибке записывает L'\0' в dest[0] (если dest не является указателем null или destsz не равно нулю или больше RSIZE_MAX/sizeof(wchar_t)) и может перезаписать остальную часть целевого массива неопределёнными значениями.

Примечания

В типичном использовании, count является количеством элементов в массиве назначения.

Хотя усечение для соответствия буферу назначения является риском безопасности, и поэтому нарушением ограничений во время выполнения для wcsncpy_s, можно получить усеченное поведение, установив count равным размеру массива назначения минус один: он скопирует первые 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 (с. 314)
K.3.9.2.1.2 Функция wcsncpy_s (с. 464)

Стандарт C11 (ISO/IEC 9899:2011):

7.29.4.2.2 Функция wcsncpy (с. 431)
K.3.9.2.1.2 Функция wcsncpy_s (с. 640-641)

Стандарт C99 (ISO/IEC 9899:1999):

7.24.4.2.2 Функция wcsncpy (с. 377)

См. также

wcscpywcscpy_s (C95)(C11)	копирует одну широкую строку в другую (функция)
wmemcpywmemcpy_s (C95)(C11)	копирует определённое количество широких символов между двумя неперекрывающимися массивами (функция)
strncpystrncpy_s (C11)	копирует определённое количество символов из одной строки в другую (функция)
Документация C++ для `wcsncpy`

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/c/string/wide/wcsncpy