itoa, _itoa, ltoa, _ltoa, ultoa, _ultoa_ltow_i64toa_i64tow_ui64toa_itow_ultow,_ui64tow
Converte um inteiro em uma cadeia de caracteres. Estão disponíveis versões mais seguras dessas funções; confira Funções _itoa_s, _itow_s.
Sintaxe
char * _itoa( int value, char *buffer, int radix );
char * _ltoa( long value, char *buffer, int radix );
char * _ultoa( unsigned long value, char *buffer, int radix );
char * _i64toa( long long value, char *buffer, int radix );
char * _ui64toa( unsigned long long value, char *buffer, int radix );
wchar_t * _itow( int value, wchar_t *buffer, int radix );
wchar_t * _ltow( long value, wchar_t *buffer, int radix );
wchar_t * _ultow( unsigned long value, wchar_t *buffer, int radix );
wchar_t * _i64tow( long long value, wchar_t *buffer, int radix );
wchar_t * _ui64tow( unsigned long long value, wchar_t *buffer, int radix );
// These POSIX versions of the functions have deprecated names:
char * itoa( int value, char *buffer, int radix );
char * ltoa( long value, char *buffer, int radix );
char * ultoa( unsigned long value, char *buffer, int radix );
// The following template functions are C++ only:
template <size_t size>
char *_itoa( int value, char (&buffer)[size], int radix );
template <size_t size>
char *_itoa( long value, char (&buffer)[size], int radix );
template <size_t size>
char *_itoa( unsigned long value, char (&buffer)[size], int radix );
template <size_t size>
char *_i64toa( long long value, char (&buffer)[size], int radix );
template <size_t size>
char * _ui64toa( unsigned long long value, char (&buffer)[size], int radix );
template <size_t size>
wchar_t * _itow( int value, wchar_t (&buffer)[size], int radix );
template <size_t size>
wchar_t * _ltow( long value, wchar_t (&buffer)[size], int radix );
template <size_t size>
wchar_t * _ultow( unsigned long value, wchar_t (&buffer)[size], int radix );
template <size_t size>
wchar_t * _i64tow( long long value, wchar_t (&buffer)[size], int radix );
template <size_t size>
wchar_t * _ui64tow( unsigned long long value, wchar_t (&buffer)[size],
int radix );
Parâmetros
value
Número a ser convertido.
buffer
Buffer que mantém o resultado da conversão.
radix
A base a ser usada para a conversão de value, que deve estar no intervalo de 2 a 36.
size
Comprimento do buffer em unidades do tipo de caractere. Esse parâmetro é inferido do argumento buffer no C++.
Valor retornado
Cada uma dessas funções retorna um ponteiro para buffer. Não há retorno de erro.
Comentários
As funções _itoa, _ltoa, _ultoa, _i64toa e _ui64toa convertem os dígitos do argumento value determinado em uma cadeia de caracteres terminada em nulo e armazena o resultado (até 33 caracteres para _itoa, _ltoa e _ultoa e 65 para _i64toa e _ui64toa) em buffer. Se radix for igual a 10 e value for negativo, o primeiro caractere da cadeia de caracteres armazenada será o sinal de menos (-). As funções _itow, _ltow, _ultow, _i64tow e _ui64tow são versões de caractere largo de _itoa, _ltoa, _ultoa, _i64toa e _ui64toa respectivamente.
Importante
Essas funções podem gravar além do final de um buffer que seja muito pequeno. Para evitar saturações de buffer, verifique se ele buffer é grande o suficiente para conter os dígitos convertidos mais o caractere nulo à direita e um caractere de sinal. O uso indevido dessas funções poderá causar sérios problemas de segurança em seu código.
Devido ao seu potencial para problemas de segurança, por padrão, essas funções causam o aviso de substituição C4996: Essa função ou variável pode não ser segura. Considere usar safe_function em vez disso. Para desabilitar a substituição, use _CRT_SECURE_NO_WARNINGS. Recomendamos que você altere o código-fonte para usar a safe_function sugerida pela mensagem de aviso. As funções mais seguras não gravam mais caracteres do que o tamanho do buffer especificado. Para obter mais informações, consulte Funções _itoa_s, _itow_s.
Para usar essas funções sem o aviso de substituição, defina a macro do pré-processador _CRT_SECURE_NO_WARNINGS antes de incluir qualquer cabeçalho do CRT. Você pode defini-lo adicionando a /D_CRT_SECURE_NO_WARNINGS opção do compilador ao cl comando. Ou você pode definir a macro em seus arquivos de origem. Se você usar cabeçalhos pré-compilados, defina a macro na parte superior do arquivo de inclusão do cabeçalho pré-compilado pch.h (stdafx.h no Visual Studio 2017 e anteriores). Para definir a macro no código-fonte, use uma diretiva #define antes de incluir qualquer cabeçalho do CRT, como neste exemplo:
#define _CRT_SECURE_NO_WARNINGS 1
#include <stdlib.h>
No C++, essas funções têm as sobrecargas de modelo que invocam suas correspondentes mais seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.
Por padrão, o estado global dessas funções tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.
Os nomes POSIX itoa, ltoa e ultoa existem como aliases para as funções _itoa, _ltoa e _ultoa. Os nomes POSIX foram preteridos porque não seguem as convenções de nome de função global específicas da implementação do ISO C. Por padrão, essas funções causam o aviso de substituição C4996: O nome POSIX para este item foi preterido. Em vez disso, use o nome compatível com ISO C e C++: new_name. Recomendamos que você altere o código-fonte para usar as versões mais seguras dessas funções, _itoa_s, _ltoa_s ou _ultoa_s. Para obter mais informações, consulte Funções _itoa_s, _itow_s.
Para portabilidade do código-fonte, é preferível manter os nomes POSIX em seu código. Para usar essas funções sem o aviso de substituição, defina as macros do pré-processador _CRT_NONSTDC_NO_WARNINGS e _CRT_SECURE_NO_WARNINGS antes de incluir qualquer cabeçalho do CRT. Você pode defini-los adicionando as opções do /D_CRT_SECURE_NO_WARNINGS compilador e /D_CRT_NONSTDC_NO_WARNINGS ao cl comando. Ou você pode definir as macros em seus arquivos de origem. Se você usar cabeçalhos pré-compilados, defina as macros na parte superior do arquivo de inclusão do cabeçalho pré-compilado. Para definir as macros no código-fonte, use diretivas #define antes de incluir qualquer cabeçalho do CRT, como neste exemplo:
#define _CRT_NONSTDC_NO_WARNINGS 1
#define _CRT_SECURE_NO_WARNINGS 1
#include <stdlib.h>
Macros de contagem máxima de conversão
Para ajudar você a criar buffers seguros para conversões, o CRT inclui algumas macros convenientes. Essas macros definem o tamanho do buffer necessário para converter o valor mais longo possível de cada tipo inteiro, incluindo o terminador nulo e o caractere de sinal, para várias bases comuns. Para garantir que o buffer de conversão seja grande o suficiente para receber qualquer conversão na base especificada por radix, use uma dessas macros definidas ao alocar o buffer. As macros ajudam a evitar erros de saturação de buffer ao converter tipos integrais em cadeias de caracteres. Essas macros são definidas quando você inclui stdlib.h ou wchar.h em seu código.
Para usar uma dessas macros em uma função de conversão de cadeia de caracteres, declare o buffer de conversão do tipo de caractere apropriado e use o valor da macro para o tipo inteiro e a base como a dimensão do buffer. Esta tabela lista as macros apropriadas para cada função para as bases listadas:
| Funções | radix | Macros |
|---|---|---|
_itoa, _itow |
16 10 8 2 |
_MAX_ITOSTR_BASE16_COUNT_MAX_ITOSTR_BASE10_COUNT_MAX_ITOSTR_BASE8_COUNT_MAX_ITOSTR_BASE2_COUNT |
_ltoa, _ltow |
16 10 8 2 |
_MAX_LTOSTR_BASE16_COUNT_MAX_LTOSTR_BASE10_COUNT_MAX_LTOSTR_BASE8_COUNT_MAX_LTOSTR_BASE2_COUNT |
_ultoa, _ultow |
16 10 8 2 |
_MAX_ULTOSTR_BASE16_COUNT_MAX_ULTOSTR_BASE10_COUNT_MAX_ULTOSTR_BASE8_COUNT_MAX_ULTOSTR_BASE2_COUNT |
_i64toa, _i64tow |
16 10 8 2 |
_MAX_I64TOSTR_BASE16_COUNT_MAX_I64TOSTR_BASE10_COUNT_MAX_I64TOSTR_BASE8_COUNT_MAX_I64TOSTR_BASE2_COUNT |
_ui64toa, _ui64tow |
16 10 8 2 |
_MAX_U64TOSTR_BASE16_COUNT_MAX_U64TOSTR_BASE10_COUNT_MAX_U64TOSTR_BASE8_COUNT_MAX_U64TOSTR_BASE2_COUNT |
Este exemplo usa uma macro de contagem de conversão para definir um buffer grande o suficiente para conter um unsigned long long na base 2:
#include <wchar.h>
#include <iostream>
int main()
{
wchar_t buffer[_MAX_U64TOSTR_BASE2_COUNT];
std:wcout << _ui64tow(0xFFFFFFFFFFFFFFFFull, buffer, 2) << std::endl;
}
Mapeamentos de rotina de texto genérico
Rotina Tchar.h |
_UNICODE e _MBCS não definidos |
_MBCS definido |
_UNICODE definido |
|---|---|---|---|
_itot |
_itoa |
_itoa |
_itow |
_ltot |
_ltoa |
_ltoa |
_ltow |
_ultot |
_ultoa |
_ultoa |
_ultow |
_i64tot |
_i64toa |
_i64toa |
_i64tow |
_ui64tot |
_ui64toa |
_ui64toa |
_ui64tow |
Requisitos
| Rotina | Cabeçalho necessário |
|---|---|
itoa, ltoa, ultoa |
<stdlib.h> |
_itoa, _ltoa, _ultoa, _i64toa, _ui64toa |
<stdlib.h> |
_itow, _ltow, _ultow, _i64tow, _ui64tow |
<stdlib.h> ou <wchar.h> |
Essas funções e macros são específicas da Microsoft. Para obter informações sobre compatibilidade, consulte Compatibilidade.
Exemplo
Este exemplo demonstra o uso de algumas das funções de conversão de inteiro. Observe o uso da macro _CRT_SECURE_NO_WARNINGS para silenciar o aviso C4996.
// crt_itoa.c
// Compile by using: cl /W4 crt_itoa.c
// This program makes use of the _itoa functions
// in various examples.
#define _CRT_SECURE_NO_WARNINGS 1
#include <stdio.h> // for printf
#include <string.h> // for strnlen
#include <stdlib.h> // for _countof, _itoa fns, _MAX_COUNT macros
int main(void)
{
char buffer[_MAX_U64TOSTR_BASE2_COUNT];
int r;
for (r = 10; r >= 2; --r)
{
_itoa(-1, buffer, r);
printf("base %d: %s (%d chars)\n", r, buffer,
strnlen(buffer, _countof(buffer)));
}
printf("\n");
for (r = 10; r >= 2; --r)
{
_i64toa(-1LL, buffer, r);
printf("base %d: %s (%d chars)\n", r, buffer,
strnlen(buffer, _countof(buffer)));
}
printf("\n");
for (r = 10; r >= 2; --r)
{
_ui64toa(0xffffffffffffffffULL, buffer, r);
printf("base %d: %s (%d chars)\n", r, buffer,
strnlen(buffer, _countof(buffer)));
}
}
base 10: -1 (2 chars)
base 9: 12068657453 (11 chars)
base 8: 37777777777 (11 chars)
base 7: 211301422353 (12 chars)
base 6: 1550104015503 (13 chars)
base 5: 32244002423140 (14 chars)
base 4: 3333333333333333 (16 chars)
base 3: 102002022201221111210 (21 chars)
base 2: 11111111111111111111111111111111 (32 chars)
base 10: -1 (2 chars)
base 9: 145808576354216723756 (21 chars)
base 8: 1777777777777777777777 (22 chars)
base 7: 45012021522523134134601 (23 chars)
base 6: 3520522010102100444244423 (25 chars)
base 5: 2214220303114400424121122430 (28 chars)
base 4: 33333333333333333333333333333333 (32 chars)
base 3: 11112220022122120101211020120210210211220 (41 chars)
base 2: 1111111111111111111111111111111111111111111111111111111111111111 (64 chars)
base 10: 18446744073709551615 (20 chars)
base 9: 145808576354216723756 (21 chars)
base 8: 1777777777777777777777 (22 chars)
base 7: 45012021522523134134601 (23 chars)
base 6: 3520522010102100444244423 (25 chars)
base 5: 2214220303114400424121122430 (28 chars)
base 4: 33333333333333333333333333333333 (32 chars)
base 3: 11112220022122120101211020120210210211220 (41 chars)
base 2: 1111111111111111111111111111111111111111111111111111111111111111 (64 chars)