strnlen, strnlen_s, wcsnlen, wcsnlen_s_mbsnlen, _mbsnlen_l, _mbstrnlen, _mbstrnlen_l

Obtém o comprimento de uma cadeia de caracteres usando a localidade atual ou uma que foi passada. Estas funções são versões mais seguras de strlen, wcslen, , _mbslen, _mbstrlen_mbslen_l, _mbstrlen_l.

Sintaxe

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

Parâmetros

str
Cadeia de caracteres terminada em nulo.

numberOfElements
O tamanho do buffer de cadeia de caracteres.

locale
Localidade a ser usada.

Valor de retorno

Essas funções retornam o número de caracteres na cadeia de caracteres, não incluindo o caractere nulo de terminação. Se não houver nenhum terminador nulo nos primeiros numberOfElements bytes da cadeia de caracteres (ou caracteres largos para wcsnlen), então numberOfElements será retornado para indicar a condição de erro; as cadeias de caracteres terminadas nulas têm comprimentos que são estritamente menores que numberOfElements.

_mbstrnlen e retorne -1 se a cadeia de caracteres contiver um caractere _mbstrnlen_l multibyte inválido.

Observações

Cada uma dessas funções retorna o número de caracteres no str, não incluindo o caractere nulo de terminação. No entanto, strnlen e strnlen_s interpretar a cadeia de caracteres como uma cadeia de caracteres de byte único e, portanto, o valor de retorno é sempre igual ao número de bytes, mesmo se a cadeia de caracteres contém caracteres multibyte. wcsnlen e wcsnlen_s são versões de caracteres largos de strnlen e strnlen_s respectivamente, os argumentos para wcsnlen e wcsnlen_s são cadeias de caracteres largos e a contagem de caracteres estão em unidades de caracteres largos. Caso contrário, wcsnlen e strnlen comportar-se de forma idêntica, como fazem strnlen_s e wcsnlen_s.

strnlen, wcsnlene não validam _mbsnlen seus parâmetros. Se str for NULL, ocorre uma violação de acesso.

strnlen_s e wcsnlen_s validar os seus parâmetros. Se str for NULL, as funções retornam 0.

_mbstrnlen também valida seus parâmetros. Se str for NULL, ou se numberOfElements for maior que INT_MAX, _mbstrnlen gera uma exceção de parâmetro inválida, conforme descrito em Validação de parâmetro. Se a execução for permitida para continuar, _mbstrnlen define errno como EINVAL e retorna -1.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Mapeamentos de rotina de texto genérico

_mbsnlen e _mbstrnlen retornar o número de caracteres multibyte em uma cadeia de caracteres de vários bytes. _mbsnlen reconhece sequências de caracteres multibyte de acordo com a página de código multibyte que está atualmente em uso ou de acordo com a localidade que é passada; ele não testa a validade de caracteres multibyte. _mbstrnlen testa a validade de caracteres multibyte e reconhece sequências de caracteres multibyte. Se a cadeia de caracteres passada para _mbstrnlen contiver um caractere multibyte inválido, errno será definida como EILSEQ.

O valor de saída é afetado pela configuração da LC_CTYPE categoria da localidade. Para obter mais informações, consulte setlocale. As versões dessas funções são idênticas, exceto que as que não têm o sufixo _l usam a localidade atual para esse comportamento dependente da localidade e as versões que têm o sufixo _l usam o parâmetro locale que é passado. Para obter mais informações, consulte Localidade.

Requerimentos

Para obter mais informações sobre compatibilidade, consulte Compatibilidade.

Example

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

Consulte também

Manipulação de cadeias de caracteres
Locale
Interpretação de sequências de caracteres multibyte
setlocale, _wsetlocale
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strcoll funções
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