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

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

Важно!

_mbsnlen, , _mbsnlen_l_mbstrnlenи _mbstrnlen_l не может использоваться в приложениях, которые выполняются в среда выполнения Windows. Дополнительные сведения: Функции CRT, которые не поддерживаются в приложениях универсальной платформы Windows.

Синтаксис

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, если строка содержит недопустимый многобайтовый символ.

Замечания

Примечание.

strnlen не является заменой strlen; функция strnlen предназначена только для вычисления размера входящих недоверенных данных в буфере известного размера, например в сетевом пакете. strnlen вычисляет длину, но не выходит за конец буфера, если строка не определена. В других ситуациях используйте strlen. (Это также применимо к функциям wcsnlen, _mbsnlen и _mbstrnlen.)

Каждая из этих функций возвращает число символов в 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.

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

TCHAR.H Обычной	_UNICODE и _MBCS не определен	_MBCS Определенные	_UNICODE Определенные
_tcsnlen	strnlen	strnlen	wcsnlen
_tcscnlen	strnlen	_mbsnlen	wcsnlen
_tcscnlen_l	strnlen	_mbsnlen_l	wcsnlen

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

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

Требования

Маршрут	Обязательный заголовок
strnlen, strnlen_s	<string.h>
wcsnlen, wcsnlen_s	<string.h> или <wchar.h>
_mbsnlen, _mbsnlen_l	<mbstring.h>
_mbstrnlen, _mbstrnlen_l	<stdlib.h>

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

Пример

// 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