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 のコピー完了前に到達した場合、結果のワイド文字配列はnull終端されません。
src から終端ナルワイド文字をコピーした後、 count に達していない場合、追加のナルワイド文字が dest に書き込まれ、合計で count 文字が書き込まれるまで続きます。
文字列が重なる場合、動作は未定義です。
2) (1) と同様だが、以下の点が異なる：この関数は count までパディングするために宛先配列にゼロを書き続けることはせず、終端ナル文字を書き込んだ後で停止する（ソースにナル文字が存在しなかった場合は、 dest [ count ] にナル文字を書き込んで停止する）。また、以下のエラーが実行時に検出され、現在設定されている constraint handler 関数を呼び出す：
  • 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 がnullポインタの場合、または destsz がゼロもしくは RSIZE_MAX / sizeof ( wchar_t ) より大きい場合を除く）。また、宛先配列の残りの部分を未規定の値で上書きする可能性があります。

注記

一般的な使用法では、 count は宛先配列内の要素数です。

宛先バッファに収まるように切り詰めることはセキュリティリスクであり、したがって wcsncpy_s の実行時制約違反となりますが、 count を宛先配列のサイズから1を引いた値に指定することで、切り詰め動作を実現することが可能です：これは最初の 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関数 (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関数 (p: 377)

関連項目

(C95) (C11)
ワイド文字列を別のワイド文字列にコピーする
(関数)
(C95) (C11)
二つの重ならない配列間で指定された量のワイド文字をコピーする
(関数)
(C11)
文字列から別の文字列へ指定された量の文字をコピーする
(関数)
C++ documentation for wcsncpy