wcsncat, wcsncat_s

Defined in header `<wchar.h>`
	(1)
wchar_t wcsncat( wchar_t dest, const wchar_t *src, size_t count );		(с 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).

Поведение не определено, если целевой массив недостаточно велик для содержимого как str, так и dest, и заключительного широкого символа конца строки.

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

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

src или dest является указателем null
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 не является указателем null или destsz не равно нулю или больше RSIZE_MAX/sizeof(wchar_t)).

Примечания

Хотя усечение для соответствия буферу назначения представляет собой риск для безопасности и, следовательно, нарушение ограничений во время выполнения для wcsncat_s, можно получить поведение усечения, задав count равным размеру массива назначения минус один: он скопирует первые count широких символов и добавит символ конца строки, как всегда: wcsncat_s(dst, sizeof dst/sizeof *dst, src, (sizeof dst/sizeof *dst)-wcsnlen_s(dst, sizeof dst/sizeof *dst)-1);

Пример

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

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

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

Ссылки

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