wcsncat, wcsncat_s

Определено в заголовочном файле <wchar.h>

Определено в заголовочном файле `<wchar.h>`
wchar_t* wcsncat( wchar_t* dest, const wchar_t* src, size_t count );	(1)	(начиная с C95) (до C99)
wchar_t* wcsncat( wchar_t* restrict dest, const wchar_t* restrict src, size_t count );		(начиная с C99)
errno_t wcsncat_s( wchar_t* restrict dest, rsize_t destsz, const wchar_t* restrict src, rsize_t count );	(2)	(начиная с C11)

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

(1)

(начиная с C95)
(до C99)

wchar_t* wcsncat( wchar_t* restrict dest,
                  const wchar_t* restrict src, size_t count );

(начиная с C99)

errno_t wcsncat_s( wchar_t* restrict dest, rsize_t destsz,
                   const wchar_t* restrict src, rsize_t count );

(2)

(начиная с C11)

1) Добавляет не более count широких символов из широкой строки, на которую указывает src, прекращая копирование, если копируется нулевой символ, в конец символьной строки, на которую указывает dest. Широкий символ src[0] заменяет нулевой символ в конце dest. Нулевой символ всегда добавляется в конце (поэтому максимальное количество широких символов, которое может записать функция, равно count + 1).

Поведение не определено, если массив назначения недостаточно велик для содержимого обеих строк — src и dest — и завершающего нулевого широкого символа.

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

2) То же, что и (1), за исключением того, что эта функция может изменить оставшуюся часть массива назначения (от последнего записанного широкого символа до destsz), а также во время выполнения обнаруживаются следующие ошибки и вызывается установленная в данный момент функция обработчика ограничений:

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

Как и для всех функций с проверкой границ, wcsncat_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)).

Примечания

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

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

Пример

#include <locale.h>
#include <stdio.h>
#include <wchar.h>
 
int main(void)
{
    wchar_t str[50] = L"Земля, прощай.";
    wcsncat(str, L" ", 1);
    wcsncat(str, L"В добрый путь.", 8); // only append the first 8 wide chars
    setlocale(LC_ALL, "en_US.utf8");
    printf("%ls", str);
}

Возможный вывод:

Земля, прощай. В добрый

Ссылки

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

7.31.4.3.2 Функция wcsncat (стр. 439)
K.3.9.3.2.2 Функция wcsncat_s (стр. 666)

Стандарт C17 (ISO/IEC 9899:2018):

7.29.4.3.2 Функция wcsncat (стр. 315)
K.3.9.2.2.2 Функция wcsncat_s (стр. 466–467)

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

7.29.4.3.2 Функция wcsncat (стр. 432–433)
K.3.9.2.2.2 Функция wcsncat_s (стр. 643–644)

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

7.24.4.3.2 Функция wcsncat (стр. 378–379)

См. также

wcscatwcscat_s (C95)(C11)	добавляет копию одной широкой строки в конец другой (функция)
strncatstrncat_s (C11)	объединяет заданное количество символов двух строк (функция)
wcscpywcscpy_s (C95)(C11)	копирует одну широкую строку в другую (функция)
Документация по C++ для `wcsncat`

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