strnlen, strnlen_s, , wcsnlen, wcsnlen_s_mbsnlen, , _mbsnlen_l, , _mbstrnlen_mbstrnlen_l

Pobiera długość ciągu przy użyciu bieżących ustawień regionalnych lub tych, które zostały przekazane. Te funkcje są bezpieczniejsze wersje strlen, , wcslen, _mbslen_mbslen_l, _mbstrlen, _mbstrlen_l.

Składnia

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
);

Parametry

str
Ciąg zakończony wartością null.

numberOfElements
Rozmiar buforu ciągu.

locale
Ustawienia regionalne do użycia.

Wartość zwracana

Te funkcje zwracają liczbę znaków w ciągu, a nie w tym znak null zakończenia. Jeśli w pierwszych numberOfElements bajtach ciągu (lub znakach szerokich wcsnlen) nie ma wartości null, zwracany jest parametr , aby numberOfElements wskazać warunek błędu; ciągi zakończone wartością null mają długości, które są ściśle mniejsze niż numberOfElements.

_mbstrnlen i _mbstrnlen_l zwraca -1, jeśli ciąg zawiera nieprawidłowy znak wielobajtowy.

Uwagi

Każda z tych funkcji zwraca liczbę znaków w strelemecie , a nie zawiera znaku zerowego zakończenia. strnlen Jednak i strnlen_s interpretować ciąg jako ciąg znaków jednobajtowych, a zatem wartość zwracana jest zawsze równa liczbie bajtów, nawet jeśli ciąg zawiera znaki wielobajtowe. wcsnlen i wcsnlen_s są odpowiednio wersjami strnlen znaków i strnlen_s ; argumenty dla wcsnlen i wcsnlen_s są ciągami szerokoznakowymi, a liczba znaków jest w jednostkach szerokich znaków. wcsnlen W przeciwnym razie i strnlen zachowują się identycznie, jak strnlen_s i wcsnlen_s.

strnlen, wcsnleni _mbsnlen nie weryfikuj ich parametrów. Jeśli str jest NULLto , następuje naruszenie dostępu.

strnlen_s i wcsnlen_s zweryfikuj ich parametry. Jeśli str parametr ma NULLwartość , funkcje zwracają wartość 0.

_mbstrnlen weryfikuje również jego parametry. Jeśli str parametr ma NULLwartość , lub numberOfElements jest większy niż INT_MAX, _mbstrnlen generuje nieprawidłowy wyjątek parametru, zgodnie z opisem w temacie Walidacja parametru. Jeśli wykonywanie jest dozwolone do kontynuowania, _mbstrnlen ustawia wartość errnoEINVAL i zwraca wartość -1.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Mapowania procedur tekstu ogólnego

_mbsnlen i _mbstrnlen zwraca liczbę znaków wielobajtowych w ciągu wielobajtowym. _mbsnlen rozpoznaje sekwencje wielobajtowe według strony kodowej wielobajtowej, która jest obecnie używana lub zgodnie z ustawieniami regionalnymi, które są przekazywane; nie testuje ważności znaków wielobajtowych. _mbstrnlen testuje ważność znaków wielobajtowych i rozpoznaje sekwencje znaków wielobajtowych. Jeśli przekazany _mbstrnlen ciąg zawiera nieprawidłowy znak wielobajtowy, errno jest ustawiony na EILSEQwartość .

Na wartość wyjściową ma wpływ ustawienie LC_CTYPE ustawienia kategorii ustawień regionalnych. Aby uzyskać więcej informacji, zobacz setlocale. Wersje tych funkcji są identyczne, z tą różnicą, że te, które nie mają _l sufiksu, używają bieżących ustawień regionalnych dla tego zachowania zależnego od ustawień regionalnych i wersji, które mają _l sufiks, zamiast tego używają parametru ustawień regionalnych, który jest przekazywany. Aby uzyskać więcej informacji, zobacz Ustawienia regionalne.

Wymagania

Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

Przykład

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

Zobacz też

Manipulowanie ciągami
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych
setlocale, _wsetlocale
strncat, , _strncat_l, wcsncat, _wcsncat_l, , _mbsncat_mbsncat_l
strncmp, , wcsncmp, , _mbsncmp_mbsncmp_l
strcoll, funkcje
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