wcsncat, wcsncat_s

 

C

編譯器支援

語言

標頭檔案

型別支援

程式工具

變參函式支援

錯誤處理

動態記憶體管理

字串庫

演算法

數值

日期和時間工具

輸入/輸出支援

本地化支援

併發支援 (C11)

技術規範

符號索引

 

字串庫

空終止位元組字串

空終止多位元組字串

空終止寬字串

 

空終止寬字串

函式 字元分類 iswalnum (C95) iswalpha (C95) iswlower (C95) iswupper (C95) iswdigit (C95) iswxdigit (C95)   iswblank (C99) iswctype (C95) iswcntrl (C95) iswgraph (C95) iswspace (C95) iswprint (C95) iswpunct (C95) wctype (C95) 字元操作 towlower (C95) towupper (C95) wctrans (C95) towctrans (C95) 轉換為數字格式 wcstolwcstoll (C95)(C99) wcstofwcstodwcstold (C99)(C95)(C99) wcstoulwcstoull (C95)(C99) wcstoimaxwcstoumax (C99)(C99)     字串操作 wcscpywcscpy_s (C95)(C11) wcsncpywcsncpy_s (C95)(C11) wcsxfrm (C95) wcscatwcscat_s (C95)(C11) wcsncatwcsncat_s (C95)(C11)

字串檢查 wcslenwcsnlen_s (C95)(C11) wcsstr (C95) wcscmp (C95) wcsncmp (C95) wcscoll (C95) wcschr (C95) wcsrchr (C95) wcspbrk (C95) wcsspn (C95) wcscspn (C95) wcstokwcstok_s (C95)(C11) 陣列操作 wmemcpywmemcpy_s (C95)(C11) wmemmovewmemmove_s (C95)(C11)   wmemcmp (C95) wmemchr (C95) wmemset (C95) 型別 wchar_t wint_t (C95) wctrans_t wctype_t (C95)(C95) 宏 WCHAR_MIN WCHAR_MAX (C95)(C95) WEOF (C95)

 

在標頭檔案 <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` 是空指標
• `destsz` 或 `count` 為零或大於 RSIZE_MAX/sizeof(wchar_t)
• `dest` 的前 `destsz` 個寬字元中沒有空寬字元
• 將發生截斷：`count` 或 `src` 的長度（取較小者）超出了 `dest` 的空終止符和 `destsz` 之間可用的空間。
• 源字串和目標字串之間會發生重疊

與所有邊界檢查函式一樣，`wcsncat_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)）。

注意

儘管截斷以適應目標緩衝區是安全風險，因此對於 `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 函式 (p: 315)

• K.3.9.2.2.2 wcsncat_s 函式 (p: 466-467)

• C11 標準 (ISO/IEC 9899:2011)

• 7.29.4.3.2 wcsncat 函式 (p: 432-433)

• K.3.9.2.2.2 wcsncat_s 函式 (p: 643-644)

• C99 標準 (ISO/IEC 9899:1999)

• 7.24.4.3.2 wcsncat 函式 (p: 378-379)

另請參閱

wcscatwcscat_s (C95)(C11)	將一個寬字串的副本追加到另一個寬字串 (函式)
strncatstrncat_s (C11)	連線兩個字串的特定數量的字元 (函式)
wcscpywcscpy_s (C95)(C11)	將一個寬字串複製到另一個寬字串 (函式)
C++ 文件，關於 wcsncat