strnlen, strnlen_s, wcsnlenwcsnlen_s_mbsnlen_mbsnlen_l_mbstrnlen_mbstrnlen_l

Получает длину строки, используя текущий или переданный в функцию языковой стандарт. Эти функции являются более безопасными версиями strlen, , wcslen, _mbslen_l_mbslen, _mbstrlen. _mbstrlen_l

Синтаксис

size_t strnlen(
   const char *str,
   size_t numberOfElements
);
size_t strnlen_s(
   const char *str,
   size_t numberOfElements
);
size_t wcsnlen(
   const wchar_t *str,
   size_t numberOfElements
);
size_t wcsnlen_s(
   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 интерпретируют строку как строку однобайтовых символов, поэтому возвращаемое значение всегда равно числу байт, даже если строка содержит многобайтовые символы. 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больше или INT_MAXnumberOfElements больше, _mbstrnlen создается недопустимое исключение параметров, как описано в разделе "Проверка параметров". Если продолжение выполнения разрешено, _mbstrnlen задает для errno значение EINVAL и возвращает значение -1.

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

Сопоставления подпрограмм универсального текста

_mbsnlen и _mbstrnlen возвращают число многобайтовых символов в строке многобайтовых символов. _mbsnlen распознает последовательности многобайтовых символов в соответствии с многобайтовой кодовой страницей, которая в настоящее время используется или в соответствии с переданным языковым стандартом; Он не проверяет допустимость многобайтовых символов. _mbstrnlen проверяет допустимость многобайтовых символов и распознает их последовательности. Если строка, передаваемая в _mbstrnlen, содержит недопустимый многобайтовый символ, для errno задается значение EILSEQ.

Выходное значение зависит от параметра LC_CTYPE категории языкового стандарта. Дополнительные сведения см. в разделе setlocale. Версии этих функций идентичны за исключением того, что версии без суффикса _l используют текущий языковой стандарт для этого поведения, зависимого от языкового стандарта, а версии с суффиксом _l — параметр языкового стандарта, переданный в функцию. Дополнительные сведения см. в разделе Locale.

Требования

Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

// 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_lwcsncat_mbsncat,_mbsncat_l
strncmp, , wcsncmp_mbsncmp_mbsncmp_l
Функции strcoll
strncpy_s, , _strncpy_s_l_wcsncpy_s_lwcsncpy_s_mbsncpy_s,_mbsncpy_s_l
strrchr, , wcsrchr_mbsrchr_mbsrchr_l
_strset, , _strset_l_wcsset_l_wcsset_mbsset,_mbsset_l
strspn, , wcsspn_mbsspn_mbsspn_l