You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/c-runtime-library/reference/itoa-i64toa-ui64toa-itow-i64tow-ui64tow.md
+76-131
Original file line number
Diff line number
Diff line change
@@ -27,82 +27,49 @@ Converts an integer to a string. More secure versions of these functions are ava
27
27
## Syntax
28
28
29
29
```C
30
-
char *_itoa(
31
-
int value,
32
-
char *buffer,
33
-
int radix
34
-
);
35
-
char *_ltoa(
36
-
long value,
37
-
char *buffer,
38
-
int radix
39
-
);
40
-
char *_ultoa(
41
-
unsigned long value,
42
-
char *buffer,
43
-
int radix
44
-
);
45
-
char *_i64toa(
46
-
__int64 value,
47
-
char *buffer,
48
-
int radix
49
-
);
50
-
char * _ui64toa(
51
-
unsigned _int64 value,
52
-
char *buffer,
53
-
int radix
54
-
);
55
-
wchar_t * _itow(
56
-
int value,
57
-
wchar_t *buffer,
58
-
int radix
59
-
);
60
-
wchar_t * _i64tow(
61
-
__int64 value,
62
-
wchar_t *buffer,
63
-
int radix
64
-
);
65
-
wchar_t * _ui64tow(
66
-
unsigned __int64 value,
67
-
wchar_t *buffer,
68
-
int radix
69
-
);
30
+
char * _itoa( int value, char *buffer, int radix );
31
+
char * _ltoa( long value, char *buffer, int radix );
32
+
char * _ultoa( unsigned long value, char *buffer, int radix );
33
+
char * _i64toa( long long value, char *buffer, int radix );
34
+
char * _ui64toa( unsigned long long value, char *buffer, int radix );
35
+
36
+
wchar_t * _itow( int value, wchar_t *buffer, int radix );
37
+
wchar_t * _ltow( long value, wchar_t *buffer, int radix );
38
+
wchar_t * _ultow( unsigned long value, wchar_t *buffer, int radix );
39
+
wchar_t * _i64tow( long long value, wchar_t *buffer, int radix );
40
+
wchar_t * _ui64tow( unsigned long long value, wchar_t *buffer, int radix );
41
+
42
+
// The following template functions are C++ only:
70
43
template <size_t size>
71
-
char *_itoa(
72
-
int value,
73
-
char (&buffer)[size],
74
-
int radix
75
-
); // C++ only
44
+
char *_itoa( int value, char (&buffer)[size], int radix );
45
+
46
+
template <size_t size>
47
+
char *_itoa( long value, char (&buffer)[size], int radix );
48
+
76
49
template <size_t size>
77
-
char *_i64toa(
78
-
__int64 value,
79
-
char (&buffer)[size],
80
-
int radix
81
-
); // C++ only
50
+
char *_itoa( unsigned long value, char (&buffer)[size], int radix );
51
+
82
52
template <size_t size>
83
-
char * _ui64toa(
84
-
unsigned _int64 value,
85
-
char (&buffer)[size],
86
-
int radix
87
-
); // C++ only
53
+
char *_i64toa( long long value, char (&buffer)[size], int radix );
54
+
88
55
template <size_t size>
89
-
wchar_t * _itow(
90
-
int value,
91
-
wchar_t (&buffer)[size],
92
-
int radix
93
-
); // C++ only
56
+
char * _ui64toa( unsigned long long value, char (&buffer)[size], int radix );
57
+
94
58
template <size_t size>
95
-
wchar_t * _i64tow(
96
-
__int64 value,
97
-
wchar_t (&buffer)[size],
98
-
int radix
99
-
); // C++ only
59
+
wchar_t * _itow( int value, wchar_t (&buffer)[size], int radix );
60
+
100
61
template <size_t size>
101
-
wchar_t * _ui64tow(
102
-
unsigned __int64 value,
103
-
wchar_t (&buffer)[size],
104
-
int radix
105
-
); // C++ only
62
+
wchar_t * _ltow( long value, wchar_t (&buffer)[size], int radix );
63
+
64
+
template <size_t size>
65
+
wchar_t * _ultow( unsigned long value, wchar_t (&buffer)[size], int radix );
66
+
67
+
template <size_t size>
68
+
wchar_t * _i64tow( long long value, wchar_t (&buffer)[size], int radix );
69
+
70
+
template <size_t size>
71
+
wchar_t * _ui64tow( unsigned long long value, wchar_t (&buffer)[size],
72
+
int radix );
106
73
```
107
74
108
75
### Parameters
@@ -114,92 +81,69 @@ Number to be converted.
114
81
String result.
115
82
116
83
*radix*<br/>
117
-
Base of *value*; which must be in the range 2-36.
84
+
The base to use for the conversion of *value*, which must be in the range 2-36.
118
85
119
86
*size*<br/>
120
-
Length of the buffer in units of the character type. This parameter is inferred in C++.
87
+
Length of the buffer in units of the character type. This parameter is inferred from the *buffer* argument in C++.
121
88
122
89
## Return Value
123
90
124
91
Each of these functions returns a pointer to *buffer*. There is no error return.
125
92
126
93
## Remarks
127
94
128
-
The `_itoa`, `_i64toa`, and `_ui64toa` functions convert the digits of the given *value* argument to a null-terminated character string and stores the result (up to 33 characters for `_itoa` and 65 for `_i64toa` and `_ui64toa`) in *buffer*. If *radix* equals 10 and *value* is negative, the first character of the stored string is the minus sign ( `-` ). `_itow`, `_i64tow`, and `_ui64tow` are wide-character versions of `_itoa`, `_i64toa`, and `_ui64toa`, respectively.
129
-
130
-
> [!IMPORTANT]
131
-
> To prevent buffer overruns, ensure that the *buffer* buffer is large enough to hold the converted digits plus the trailing null-character and a sign character. For convenience, stdlib.h and wchar.h define macros that specify the required count of narrow or wide characters required for each type of conversion. For more information, see [Maximum conversion count macros](#maximum-conversion-count-macros).
95
+
The `_itoa`, `_ltoa`, `_ultoa`, `_i64toa`, and `_ui64toa` functions convert the digits of the given *value* argument to a null-terminated character string and stores the result (up to 33 characters for `_itoa`, `_ltoa`, and `_ultoa`, and 65 for `_i64toa` and `_ui64toa`) in *buffer*. If *radix* equals 10 and *value* is negative, the first character of the stored string is the minus sign ( `-` ). The `_itow`, `_ltow`, `_ultow`, `_i64tow`, and `_ui64tow` functions are wide-character versions of `_itoa`, `_ltoa`, `_ultoa`, `_i64toa`, and `_ui64toa`, respectively.
132
96
133
97
In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md).
134
98
99
+
> [!IMPORTANT]
100
+
> To prevent buffer overruns, ensure that *buffer* is large enough to hold the converted digits plus the trailing null-character and a sign character.
101
+
135
102
### Maximum conversion count macros
136
103
137
-
The Microsoft implementation of the CRT includes some convenient macros for the size of the buffer required to convert the longest possible integer of each type. To ensure that your conversion buffer is large enough to receive any conversion in the base specified by *radix*, use one of these defined macros when you allocate the buffer. This helps to prevent buffer overrun errors when you convert integral types to strings.
104
+
To help you create secure buffers for conversions, the Microsoft implementation of the CRT includes some convenient macros for the size of the buffer required to convert the longest possible integer of each type, including the null terminator and sign character, for several common bases. To ensure that your conversion buffer is large enough to receive any conversion in the base specified by *radix*, use one of these defined macros when you allocate the buffer. This helps to prevent buffer overrun errors when you convert integral types to strings. These macros are defined when you include either stdlib.h or wchar.h in your source.
138
105
139
-
These macros are defined when you include either stdlib.h or wchar.h in your source:
140
-
141
-
```C
142
-
// Maximum number of elements, including null terminator (and negative sign
143
-
// where appropriate), needed for integer-to-string conversions for several
144
-
// bases and integer types.
145
-
#define_MAX_ITOSTR_BASE16_COUNT (8 + 1)
146
-
#define _MAX_ITOSTR_BASE10_COUNT (1 + 10 + 1)
147
-
#define _MAX_ITOSTR_BASE8_COUNT (11 + 1)
148
-
#define _MAX_ITOSTR_BASE2_COUNT (32 + 1)
149
-
150
-
#define_MAX_LTOSTR_BASE16_COUNT (8 + 1)
151
-
#define _MAX_LTOSTR_BASE10_COUNT (1 + 10 + 1)
152
-
#define _MAX_LTOSTR_BASE8_COUNT (11 + 1)
153
-
#define _MAX_LTOSTR_BASE2_COUNT (32 + 1)
154
-
155
-
#define_MAX_ULTOSTR_BASE16_COUNT (8 + 1)
156
-
#define _MAX_ULTOSTR_BASE10_COUNT (10 + 1)
157
-
#define _MAX_ULTOSTR_BASE8_COUNT (11 + 1)
158
-
#define _MAX_ULTOSTR_BASE2_COUNT (32 + 1)
159
-
160
-
#define_MAX_I64TOSTR_BASE16_COUNT (16 + 1)
161
-
#define _MAX_I64TOSTR_BASE10_COUNT (1 + 19 + 1)
162
-
#define _MAX_I64TOSTR_BASE8_COUNT (22 + 1)
163
-
#define _MAX_I64TOSTR_BASE2_COUNT (64 + 1)
164
-
165
-
#define_MAX_U64TOSTR_BASE16_COUNT (16 + 1)
166
-
#define _MAX_U64TOSTR_BASE10_COUNT (20 + 1)
167
-
#define _MAX_U64TOSTR_BASE8_COUNT (22 + 1)
168
-
#define _MAX_U64TOSTR_BASE2_COUNT (64 + 1)
169
-
```
170
-
171
-
To use one of these macros, declare your conversion buffer of the appropriate type and use the macro value for the dimension. For example,
106
+
To use one of these macros in a string conversion function, declare your conversion buffer of the appropriate character type and use the macro value for the integer type and base as the buffer dimension. This table lists the macros that are appropriate for each function for the listed bases:
0 commit comments