É recomendável usar o Visual Studio 2017

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

 

Para obter a documentação mais recente do Visual Studio 2017 RC, consulte a documentação do Visual Studio 2017 RC.

Obtém o tamanho de uma cadeia de caracteres usando a localidade atual ou uma que foi enviada. Essas são versões mais seguras do strlen, wcslen, mbslen, mbslen_l, mbstrlen, mbstrlen_l.

System_CAPS_ICON_important.jpg Importante

_mbsnlen, _mbsnlen_l, _mbstrnlen e _mbstrnlen_l não podem ser usados em aplicativos executados no Tempo de Execução do Windows. Para obter mais informações, consulte funções de CRT não têm suportadas com /ZW.

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

Parâmetros

str
Cadeia de caracteres terminada em nulo.

numberOfElements
O tamanho do buffer da cadeia de caracteres.

locale
Localidade a usar.

Essas funções retornam o número de caracteres na cadeia de caracteres, sem incluir o caractere de terminação nula. Se não houver terminador nulo dentro dos primeiros numberOfElements bytes da cadeia de caracteres (ou caracteres largos para wcsnlen), numberOfElements é retornado para indicar a condição de erro; a cadeia de caracteres de terminação nula tem comprimento estritamente menor que numberOfElements.

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

System_CAPS_ICON_note.jpg Observação

strnlen não é uma substituição de strlen; strnlen é feito para ser usado apenas para calcular o tamanho dos dados não confiáveis recebidos em um buffer de tamanho conhecido, por exemplo, um pacote de rede. strnlen calcula o tamanho, mas não passa do fim do buffer se a cadeia de caracteres não estiver terminada. Para ter outras situações, use strlen. (O mesmo se aplica a wcsnlen, _mbsnlen e _mbstrnlen.)

Cada uma dessas funções retorna o número de caracteres em str, sem incluir o caractere de terminação nula. Porém, strnlen e strnlen_s interpretam a cadeia de caracteres como uma cadeia de caracteres de byte único e, portanto, o valor retornado é sempre igual ao número de bytes, mesmo que a cadeia de caracteres contenha caracteres multibyte. wcsnlen e wcsnlen_s são versões de caractere largo de strnlen e strnlen_s, respectivamente; os argumentos para wcsnlen e wcsnlen_s são cadeia de caracteres larga e a contagem de caracteres ficam em unidades de caractere largo. Caso contrário, wcsnlen e strnlen comportam-se de modo idêntico, assim como strnlen_s e wcsnlen_s.

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

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

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

Mapeamentos da rotina de texto genérico

Rotina TCHAR.H_UNICODE e _MBCS não definidos_MBCS definido_UNICODE definido
_tcsnlenstrnlenstrnlenwcsnlen
_tcscnlenstrnlen_mbsnlenwcsnlen
_tcscnlen_lstrnlen_mbsnlen_lwcsnlen

_mbsnlen e _mbstrnlen retorna o número de caracteres multibyte em uma cadeia de caracteres multibyte. O _mbsnlen reconhece sequências de caracteres multibyte de acordo com a página de código multibyte que está em uso no momento ou com a localidade informada; não testa a validade de caracteres multibyte. O _mbstrnlen testa a validade de caracteres multibyte e reconhece sequências de caracteres multibyte. Se a cadeia de caracteres enviada para _mbstrnlen contiver um caractere multibyte inválido, errno é definido para EILSEQ.

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

RotinaCabeçalho necessário
strnlen, strnlen_s<string.h>
wcsnlen, wcsnlen_s<string.h> ou <wchar.h>
_mbsnlen, _mbsnlen_l<mbstring.h>
_mbstrnlen, _mbstrnlen_l<stdlib.h>

Para obter informações adicionais sobre compatibilidade, consulte compatibilidade.

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

System::String::Length

Manipulação de cadeia de caracteres
Localidade
Interpretação de sequências de caracteres Multibyte
setlocale, wsetlocale
strncat, _strncat_l, wcsncat, _wcsncat_l, mbsncat, mbsncat_l
strncmp, wcsncmp, mbsncmp, mbsncmp_l
Funções 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

Mostrar: