_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l

Artigo
06/09/2015

Converte uma cadeia de caracteres em letras maiúsculas, usando a localidade atual ou uma localidade especificada em que é passada. Essas versões de _strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr têm aprimoramentos de segurança, como descrito em Recursos de segurança no CRT.

Importante

_mbsupr_s e _mbsupr_s_l não podem ser usados em aplicativos executados no Tempo de Execução do Windows.Para obter mais informações, consulte Funções CRT sem suporte pelo /ZW.

errno_t _strupr_s(
   char *str,
   size_t numberOfElements
);
errno_t _wcsupr_s(
   wchar_t * str,
   size_t numberOfElements
);
errno_t _strupr_s_l(
   char * str,
   size_t numberOfElements,
   _locale_t locale
);
errno_t _wcsupr_s_l(
   wchar_t * str,
   size_t numberOfElements,
   _locale_t locale
);
errno_t _mbsupr_s(
   unsigned char *str,
   size_t numberOfElements
);
errno_t _mbsupr_s_l(
   unsigned char *str,
   size_t numberOfElements,
   _locale_t locale
);
template <size_t size>
errno_t _strupr_s(
   char (&str)[size]
); // C++ only
template <size_t size>
errno_t _wcsupr_s(
   wchar_t (&str)[size]
); // C++ only
template <size_t size>
errno_t _strupr_s_l(
   char (&str)[size],
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _wcsupr_s_l(
   wchar_t (&str)[size],
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsupr_s(
   unsigned char (&str)[size]
); // C++ only
template <size_t size>
errno_t _mbsupr_s_l(
   unsigned char (&str)[size],
   _locale_t locale
); // C++ only

Parâmetros

str
Cadeia de caracteres a ser colocada em maiúscula.
numberOfElements
O tamanho do buffer.
locale
A localidade a ser usada.

Valor de retorno

Zero se tiver êxito; um código de erro diferente de zero em uma falha.

Essas funções validam seus parâmetros. Se str for um ponteiro NULL, o manipulador de parâmetro inválido será chamado, como descrito em Validação do parâmetro. Se a execução puder continuar, as funções retornarão EINVAL e definirão errno como EINVAL. Se numberOfElements for menor que o tamanho da cadeia de caracteres, as funções retornarão ERANGE e definirão errno como ERANGE.

Comentários

A função de _strupr_s converte, no lugar, cada letra minúscula em str letras maiúsculas. _wcsupr_s é a versão de caracteres largos de _strupr_s. _mbsupr_s é a versão de caracteres multibyte de _strupr_s.

A conversão é determinada pela configuração da localidade da categoria LC_CTYPE. Outros caracteres não são afetados. Para obter mais informações sobre LC_CTYPE, consulte setlocale. As versões dessas funções sem o sufixo _l usam a localidade atual para esse comportamento dependente da localidade; as versões com o sufixo _l são idênticas, exceto que elas usam o parâmetro de localidade informado. Para obter mais informações, consulte Localidade.

No C++, o uso dessas funções é simplificado por sobrecargas de modelo; as sobrecargas podem interpretar o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente as funções menos seguras mais antigas por correspondentes mais seguras e mais recentes. Para obter mais informações, consulte Sobrecargas de modelo seguras.

As versões de depuração dessas funções preenchem primeiro o buffer com 0xFD. Para desabilitar esse comportamento, use _CrtSetDebugFillThreshold.

Mapeamentos da rotina de texto genérico