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) Копирует не более 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 широких символов и добавит нулевой широкий терминатор как обычно: 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)

Смотрите также

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