wcsncpy, wcsncpy_s

< c‎ | string‎ | wide
 
C
 
字符串库
 
空终止宽字符串
函数
字符操作
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C99)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
转换成数值格式
(C95)(C99)
(C95)(C99)
(C99)(C95)(C99)
(C99)(C99)
字符串操作
(C95)(C11)
(C95)(C11)
wcsncpywcsncpy_s
(C95)(C11)
(C95)(C11)
(C95)(C11)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)
(C95)(C11)
数组操作
(C95)(C11)
(C95)(C11)
(C95)
(C95)
(C95)
 
定义于头文件 <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 n);
 (C99 起)
errno_t wcsncpy_s( wchar_t *restrict dest, rsize_t destsz,
                   const wchar_t *restrict src, rsize_t n);
 (2) (C11 起)
1) 复制 src 所指向的宽字符串的至多 count 个字符（包含终止空宽字符）到 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) ，换言之，会出现截断
  • 源与目标字符串间会出现重叠
同所有边界检查函数， wcsncpy_s 仅若实现定义了 __STDC_LIB_EXT1__ ，且用户在包含 wchar.h 前定义 __STDC_WANT_LIB_EXT1__ 为整数常量 1 才保证可用。

参数

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)
{
    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");
    for(wchar_t* p = dest; p-dest < sizeof dest / sizeof *dest; ++p) {
        if(*p)
            printf("%lc ", *p);
        else
            printf("\\0 ");
    }
}

可能的输出： 

The contents of dest are: 
わ ゐ \0 \0 お \0

引用

  • C11 standard (ISO/IEC 9899:2011):
  • 7.29.4.2.2 The wcsncpy function (p: 431)
  • K.3.9.2.1.2 The wcsncpy_s function (p: 640-641)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.24.4.2.2 The wcsncpy function (p: 377)

参阅

(C95)(C11)
 将一个宽字符串复制给另一个
(函数)
(C95)(C11)
 在两个不重叠的数组间复制一定数量的宽字符
(函数)
(C11)
 从一个字符串复制一定数量的字符到另一个
(函数)