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 指向的宽字符数组。
如果在复制整个字符串 src 之前达到 count ，则生成的宽字符数组不会以空字符结尾。
若从 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 ) ，换言之，将发生截断
  • 源字符串与目标字符串存在重叠
与所有边界检查函数一样，仅当实现定义了 __STDC_LIB_EXT1__ 且用户在包含 <wchar.h> 之前将 __STDC_WANT_LIB_EXT1__ 定义为整型常量 1 时，才保证 wcsncpy_s 可用。

目录

参数

dest - 指向目标宽字符数组的指针
src - 指向源宽字符串的指针
count - 要复制的最大宽字符数
destsz - 目标缓冲区的大小

返回值

1) 返回 dest 的副本
2) 成功时返回零，错误时返回非零值。此外，在发生错误时，会向 dest [ 0 ] 写入 L ' \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); // 这将复制 わゐ 并重复两个 L'\0'
    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 函数 (p: 314)
  • K.3.9.2.1.2 wcsncpy_s 函数 (p: 464)
  • C11 标准 (ISO/IEC 9899:2011):
  • 7.29.4.2.2 wcsncpy 函数 (p: 431)
  • K.3.9.2.1.2 wcsncpy_s 函数 (p: 640-641)
  • C99标准（ISO/IEC 9899:1999）：
  • 7.24.4.2.2 wcsncpy函数（页码：377）

参见

(C95) (C11)
复制一个宽字符串到另一个
(函数)
(C95) (C11)
在两个非重叠数组间复制指定数量的宽字符
(函数)
(C11)
从一个字符串复制指定数量的字符到另一个字符串
(函数)
C++ 文档 for wcsncpy