wcsncpy, wcsncpy_s

Объявлено в заголовочном файле <wchar.h>

Объявлено в заголовочном файле `<wchar.h>`
wchar_t* wcsncpy( wchar_t* dest, const wchar_t* src, size_t count );	(1)	(начиная с 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)

wchar_t* wcsncpy( wchar_t* dest, const wchar_t* src, size_t count );

(1)

(начиная с 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 является нулевым указателем
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 не является нулевым указателем, а destsz не равно нулю и не больше RSIZE_MAX / sizeof(wchar_t)) и может перезаписать остальную часть массива назначения неопределёнными значениями.

Примечания

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

Хотя усечение для размещения в буфере назначения представляет угрозу безопасности и поэтому является нарушением ограничений времени выполнения для wcsncpy_s, усечения можно добиться, указав count равным размеру массива назначения минус один: будут скопированы первые count широких символов, а в конце, как обычно, будет добавлен завершающий нулевой широкий символ:

size_t count = sizeof dst / sizeof *dst;
wcsncpy_s(dst, count, src, count - 1);

Пример

#include <locale.h>
#include <stdio.h>
#include <wchar.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

Ссылки

Стандарт C23 (ISO/IEC 9899:2024):

7.31.4.2.2 Функция wcsncpy (стр. 438)
K.3.9.3.1.2 Функция wcsncpy_s (стр. 663–664)

Стандарт 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/c/string/wide/wcsncpy