strnlen、 strnlen_s、 wcsnlen、 wcsnlen_s、 _mbsnlen、 _mbsnlen_l、 _mbstrnlen、 _mbstrnlen_l

現在のロケールまたは渡されたロケールを使用して、文字列の長さを取得します。 これらの関数は、 strlen、 wcslen、 _mbslen、 _mbslen_l、 _mbstrlen、 _mbstrlen_lのより安全なバージョンです。

構文

size_t strnlen(
   const char *str,
   size_t numberOfElements
);
size_t strnlen_s( // See note in remarks section about linkage
   const char *str,
   size_t numberOfElements
);
size_t wcsnlen(
   const wchar_t *str,
   size_t numberOfElements
);
size_t wcsnlen_s( // See note in remarks section about linkage
   const wchar_t *str,
   size_t numberOfElements
);
size_t _mbsnlen(
   const unsigned char *str,
   size_t numberOfElements
);
size_t _mbsnlen_l(
   const unsigned char *str,
   size_t numberOfElements,
   _locale_t locale
);
size_t _mbstrnlen(
   const char *str,
   size_t numberOfElements
);
size_t _mbstrnlen_l(
   const char *str,
   size_t numberOfElements,
   _locale_t locale
);

パラメーター

str
NULL で終わる文字列。

numberOfElements
文字列バッファーのサイズ。

locale
使用するロケール。

戻り値

これらの関数は、文字列内の文字数を返します (終端の null 文字は含まれません)。 文字列の最初の numberOfElements バイト (または wcsnlenのワイド文字) 内に null ターミネータがない場合は、エラー状態を示すために numberOfElements が返されます。null で終わる文字列の長さは厳密に numberOfElements未満です。

_mbstrnlen および _mbstrnlen_l は、文字列に無効なマルチバイト文字が含まれている場合は -1 を返します。

解説

これらの各関数は、str 内の文字数を返します (終端の null 文字は含まれません)。 ただし、strnlen および strnlen_s は文字列を 1 バイト文字列として扱うため、マルチバイト文字が含まれている場合でも、戻り値は常にバイト数と同じです。 wcsnlen および wcsnlen_s は、それぞれ strnlen および strnlen_s のワイド文字バージョンです。wcsnlen および wcsnlen_s の引数はワイド文字列で、文字数はワイド文字単位です。 それ以外では、wcsnlen と strnlen の動作は同じです。strnlen_s と wcsnlen_s の場合も同様です。

strnlen、 wcsnlen、および _mbsnlen はパラメーターを検証しません。 str が NULL の場合、アクセス違反が発生します。

strnlen_s および wcsnlen_s は、パラメーターを検証します。 str が NULL の場合、関数は 0 を返します。

_mbstrnlen もそのパラメーターを検証します。 strがNULLされている場合、またはnumberOfElementsがINT_MAXより大きい場合は、「パラメーターの検証」で説明されているように、_mbstrnlenは無効なパラメーター例外を生成。 実行の継続が許可された場合、_mbstrnlen は errno を EINVAL に設定し、-1 を返します。

既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 この動作を変更するには、「CRT でのグローバル状態」を参照してください。

汎用テキスト ルーチンのマップ

_mbsnlen と _mbstrnlen は、マルチバイト文字列のマルチバイト文字数を返します。 _mbsnlen は、現在使用中のマルチバイト コード ページまたは渡されたロケールに従って、マルチバイト文字シーケンスを認識します。マルチバイト文字の有効性はテストされません。 _mbstrnlen は、マルチバイト文字の有効性をテストし、マルチバイト文字のシーケンスを認識します。 _mbstrnlen に渡された文字列に無効なマルチバイト文字が含まれている場合、errno は EILSEQ に設定されます。

出力値は、ロケールの LC_CTYPE カテゴリ設定の設定によって影響を受けます。 詳細については、setlocaleを参照してください。 _l サフィックスが付いていないバージョンがこのロケールに依存する動作に現在のロケールを使用し、_l サフィックスが付いているバージョンが渡されたロケール パラメーターを代わりに使用する点を除いて、これらの関数のバージョンは同じです。 詳細については、「 Locale」を参照してください。

要件

互換性の詳細については、「 Compatibility」を参照してください。

例

// crt_strnlen.c

#include <string.h>

int main()
{
   // str1 is 82 characters long. str2 is 159 characters long

   char* str1 = "The length of a string is the number of characters\n"
               "excluding the terminating null.";
   char* str2 = "strnlen takes a maximum size. If the string is longer\n"
                "than the maximum size specified, the maximum size is\n"
                "returned rather than the actual size of the string.";
   size_t len;
   size_t maxsize = 100;

   len = strnlen(str1, maxsize);
   printf("%s\n Length: %d \n\n", str1, len);

   len = strnlen(str2, maxsize);
   printf("%s\n Length: %d \n", str2, len);
}

The length of a string is the number of characters
excluding the terminating null.
Length: 82

strnlen takes a maximum size. If the string is longer
than the maximum size specified, the maximum size is
returned rather than the actual size of the string.
Length: 100

関連項目

文字列操作
ロケール
マルチバイト文字のシーケンスの解釈
setlocale, _wsetlocale
strncat、 _strncat_l、 wcsncat、 _wcsncat_l、 _mbsncat、 _mbsncat_l
strncmp、 wcsncmp、 _mbsncmp、 _mbsncmp_l
strcoll 関数
strncpy_s、 _strncpy_s_l、 wcsncpy_s、 _wcsncpy_s_l、 _mbsncpy_s、 _mbsncpy_s_l
strrchr、 wcsrchr、 _mbsrchr、 _mbsrchr_l
_strset、 _strset_l、 _wcsset、 _wcsset_l、 _mbsset、 _mbsset_l
strspn、 wcsspn、 _mbsspn、 _mbsspn_l