当前位置： C语言 -- 附录 -- wcsncat_s

wcsncat_s函数

概要：

#define __STDC_WANT_LIB_EXT1__ 1
#include <wchar.h>
errno_t wcsncat_s(wchar_t * restrict s1,
      rsize_t s1max,
      const wchar_t * restrict s2, 
      rsize_t n);

描述：

假设： m表示表达式s1max - wcsnlen_s(s1, s1max)的值。

该函数从参数s2指向的数组中添加不超过n个连续宽字符(空宽字符后面的宽字符不会被复制。)到参数s1指向宽字符串的末尾。参数s2指向数组的初始宽字符覆盖参数s1指向宽字符串的终止空宽字符。如果未能从s2中复制空宽字符，函数将s1[s1max-m+n]设置为空宽字符。

wcsncat_s函数返回时，参数s1指向的、大小为s1max个宽字符的数组中wcsncat_s函数写入的终止空宽字符（如果存在。）之后的所有元素值都是未指定的。这允许实现在将宽字符从s2添加到s1的同时，检查这些宽字符是否存在空宽字符。这种方式可能在发现第一个元素设置为空宽字符前，已向s1的每个元素都写入了一个宽字符。

运行约束：

参数s1和参数s2不能是空指针。参数s1max和参数n应不大于RSIZE_MAX/sizeof(wchar_t)。参数s1max和m不等于0（m等于0意味着：进入wcsncat_s函数时，s1不是以空宽字符结尾的。）。如果参数n不小于m，m应大于wcsnlen_s(s2, m)。复制不应发生在重叠对象之间。

在存在运行约束违规的情况下，如果参数s1不是空指针，参数s1max大于0且不大于RSIZE_MAX/sizeof(wchar_t)，函数将s1[0]设置为空宽字符。

参数：

wchar_t * restrict s1

指向目标数组的指针，结果宽字符串将存入该数组。

rsize_t s1max

目标数组中修改的最大宽字符数。

const wchar_t * restrict s2

指向源数组的指针，从该数组中读取宽字符。

rsize_t n

最多可以添加的宽字符数。

返回值：

如果不存在运行约束违规，函数返回0；否则函数返回非0值。

函数返回0意味着：从s2指向宽字符串中请求的所有宽字符都已成功添加到s1指向宽字符串的末尾，并且s1中的结果字符串以空宽字符终止。

范例：

/*安全函数wcsncat_s范例*/

#define __STDC_WANT_LIB_EXT1__ 1
#include <locale.h>
#include <wchar.h>

#define LENGTH 100
#define N 2

int main(void)
{
    setlocale(LC_ALL, "");
    
    wchar_t wStrOne[LENGTH] = L"早安";
    const wchar_t wStrTwo[] = L"中国上海";

    if(!wcsncat_s(wStrOne, LENGTH, wStrTwo, N))
        wprintf_s(L"%ls\n", wStrOne);
    
    return 0;
}

输出：

早安中国

（注：使用Visual Studio编译。）