1//! [![github]](https://github.com/dtolnay/itoa) [![crates-io]](https://crates.io/crates/itoa) [![docs-rs]](https://docs.rs/itoa)
2//!
3//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
4//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
5//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
6//!
7//! <br>
8//!
9//! This crate provides a fast conversion of integer primitives to decimal
10//! strings. The implementation comes straight from [libcore] but avoids the
11//! performance penalty of going through [`core::fmt::Formatter`].
12//!
13//! See also [`ryu`] for printing floating point primitives.
14//!
15//! [libcore]: https://github.com/rust-lang/rust/blob/b8214dc6c6fc20d0a660fb5700dca9ebf51ebe89/src/libcore/fmt/num.rs#L201-L254
16//! [`ryu`]: https://github.com/dtolnay/ryu
17//!
18//! # Example
19//!
20//! ```
21//! fn main() {
22//! let mut buffer = itoa::Buffer::new();
23//! let printed = buffer.format(128u64);
24//! assert_eq!(printed, "128");
25//! }
26//! ```
27//!
28//! # Performance (lower is better)
29//!
30//! ![performance](https://raw.githubusercontent.com/dtolnay/itoa/master/performance.png)
31
32#![doc(html_root_url = "https://docs.rs/itoa/1.0.15")]
33#![no_std]
34#![allow(
35 clippy::cast_lossless,
36 clippy::cast_possible_truncation,
37 clippy::cast_possible_wrap,
38 clippy::cast_sign_loss,
39 clippy::expl_impl_clone_on_copy,
40 clippy::must_use_candidate,
41 clippy::needless_doctest_main,
42 clippy::unreadable_literal
43)]
44
45mod udiv128;
46
47use core::hint;
48use core::mem::MaybeUninit;
49use core::{ptr, slice, str};
50#[cfg(feature = "no-panic")]
51use no_panic::no_panic;
52
53/// A correctly sized stack allocation for the formatted integer to be written
54/// into.
55///
56/// # Example
57///
58/// ```
59/// let mut buffer = itoa::Buffer::new();
60/// let printed = buffer.format(1234);
61/// assert_eq!(printed, "1234");
62/// ```
63pub struct Buffer {
64 bytes: [MaybeUninit<u8>; i128::MAX_STR_LEN],
65}
66
67impl Default for Buffer {
68 #[inline]
69 fn default() -> Buffer {
70 Buffer::new()
71 }
72}
73
74impl Copy for Buffer {}
75
76impl Clone for Buffer {
77 #[inline]
78 #[allow(clippy::non_canonical_clone_impl)] // false positive https://github.com/rust-lang/rust-clippy/issues/11072
79 fn clone(&self) -> Self {
80 Buffer::new()
81 }
82}
83
84impl Buffer {
85 /// This is a cheap operation; you don't need to worry about reusing buffers
86 /// for efficiency.
87 #[inline]
88 #[cfg_attr(feature = "no-panic", no_panic)]
89 pub fn new() -> Buffer {
90 let bytes: [MaybeUninit; 40] = [MaybeUninit::<u8>::uninit(); i128::MAX_STR_LEN];
91 Buffer { bytes }
92 }
93
94 /// Print an integer into this buffer and return a reference to its string
95 /// representation within the buffer.
96 #[cfg_attr(feature = "no-panic", no_panic)]
97 pub fn format<I: Integer>(&mut self, i: I) -> &str {
98 let string: &str = i.write(buf:unsafe {
99 &mut *(&mut self.bytes as *mut [MaybeUninit<u8>; i128::MAX_STR_LEN]
100 as *mut <I as private::Sealed>::Buffer)
101 });
102 if string.len() > I::MAX_STR_LEN {
103 unsafe { hint::unreachable_unchecked() };
104 }
105 string
106 }
107}
108
109/// An integer that can be written into an [`itoa::Buffer`][Buffer].
110///
111/// This trait is sealed and cannot be implemented for types outside of itoa.
112pub trait Integer: private::Sealed {
113 /// The maximum length of string that formatting an integer of this type can
114 /// produce on the current target platform.
115 const MAX_STR_LEN: usize;
116}
117
118// Seal to prevent downstream implementations of the Integer trait.
119mod private {
120 #[doc(hidden)]
121 pub trait Sealed: Copy {
122 #[doc(hidden)]
123 type Buffer: 'static;
124 fn write(self, buf: &mut Self::Buffer) -> &str;
125 }
126}
127
128const DEC_DIGITS_LUT: [u8; 200] = *b"\
129 0001020304050607080910111213141516171819\
130 2021222324252627282930313233343536373839\
131 4041424344454647484950515253545556575859\
132 6061626364656667686970717273747576777879\
133 8081828384858687888990919293949596979899";
134
135// Adaptation of the original implementation at
136// https://github.com/rust-lang/rust/blob/b8214dc6c6fc20d0a660fb5700dca9ebf51ebe89/src/libcore/fmt/num.rs#L188-L266
137macro_rules! impl_Integer {
138 ($t:ty[len = $max_len:expr] as $large_unsigned:ty) => {
139 impl Integer for $t {
140 const MAX_STR_LEN: usize = $max_len;
141 }
142
143 impl private::Sealed for $t {
144 type Buffer = [MaybeUninit<u8>; $max_len];
145
146 #[allow(unused_comparisons)]
147 #[inline]
148 #[cfg_attr(feature = "no-panic", no_panic)]
149 fn write(self, buf: &mut [MaybeUninit<u8>; $max_len]) -> &str {
150 let is_nonnegative = self >= 0;
151 let mut n = if is_nonnegative {
152 self as $large_unsigned
153 } else {
154 // Convert negative number to positive by summing 1 to its two's complement.
155 (!(self as $large_unsigned)).wrapping_add(1)
156 };
157 let mut curr = buf.len();
158 let buf_ptr = buf.as_mut_ptr() as *mut u8;
159 let lut_ptr = DEC_DIGITS_LUT.as_ptr();
160
161 // Render 4 digits at a time.
162 while n >= 10000 {
163 let rem = n % 10000;
164 n /= 10000;
165
166 let d1 = ((rem / 100) << 1) as usize;
167 let d2 = ((rem % 100) << 1) as usize;
168 curr -= 4;
169 unsafe {
170 ptr::copy_nonoverlapping(lut_ptr.add(d1), buf_ptr.add(curr), 2);
171 ptr::copy_nonoverlapping(lut_ptr.add(d2), buf_ptr.add(curr + 2), 2);
172 }
173 }
174
175 // Render 2 more digits, if >2 digits.
176 if n >= 100 {
177 let d1 = ((n % 100) << 1) as usize;
178 n /= 100;
179 curr -= 2;
180 unsafe {
181 ptr::copy_nonoverlapping(lut_ptr.add(d1), buf_ptr.add(curr), 2);
182 }
183 }
184
185 // Render last 1 or 2 digits.
186 if n < 10 {
187 curr -= 1;
188 unsafe {
189 *buf_ptr.add(curr) = (n as u8) + b'0';
190 }
191 } else {
192 let d1 = (n << 1) as usize;
193 curr -= 2;
194 unsafe {
195 ptr::copy_nonoverlapping(lut_ptr.add(d1), buf_ptr.add(curr), 2);
196 }
197 }
198
199 if !is_nonnegative {
200 curr -= 1;
201 unsafe {
202 *buf_ptr.add(curr) = b'-';
203 }
204 }
205
206 let len = buf.len() - curr;
207 let bytes = unsafe { slice::from_raw_parts(buf_ptr.add(curr), len) };
208 unsafe { str::from_utf8_unchecked(bytes) }
209 }
210 }
211 };
212}
213
214impl_Integer!(i8[len = 4] as u32);
215impl_Integer!(u8[len = 3] as u32);
216impl_Integer!(i16[len = 6] as u32);
217impl_Integer!(u16[len = 5] as u32);
218impl_Integer!(i32[len = 11] as u32);
219impl_Integer!(u32[len = 10] as u32);
220impl_Integer!(i64[len = 20] as u64);
221impl_Integer!(u64[len = 20] as u64);
222
223macro_rules! impl_Integer_size {
224 ($t:ty as $primitive:ident #[cfg(target_pointer_width = $width:literal)]) => {
225 #[cfg(target_pointer_width = $width)]
226 impl Integer for $t {
227 const MAX_STR_LEN: usize = <$primitive as Integer>::MAX_STR_LEN;
228 }
229
230 #[cfg(target_pointer_width = $width)]
231 impl private::Sealed for $t {
232 type Buffer = <$primitive as private::Sealed>::Buffer;
233
234 #[inline]
235 #[cfg_attr(feature = "no-panic", no_panic)]
236 fn write(self, buf: &mut Self::Buffer) -> &str {
237 (self as $primitive).write(buf)
238 }
239 }
240 };
241}
242
243impl_Integer_size!(isize as i16 #[cfg(target_pointer_width = "16")]);
244impl_Integer_size!(usize as u16 #[cfg(target_pointer_width = "16")]);
245impl_Integer_size!(isize as i32 #[cfg(target_pointer_width = "32")]);
246impl_Integer_size!(usize as u32 #[cfg(target_pointer_width = "32")]);
247impl_Integer_size!(isize as i64 #[cfg(target_pointer_width = "64")]);
248impl_Integer_size!(usize as u64 #[cfg(target_pointer_width = "64")]);
249
250macro_rules! impl_Integer128 {
251 ($t:ty[len = $max_len:expr]) => {
252 impl Integer for $t {
253 const MAX_STR_LEN: usize = $max_len;
254 }
255
256 impl private::Sealed for $t {
257 type Buffer = [MaybeUninit<u8>; $max_len];
258
259 #[allow(unused_comparisons)]
260 #[inline]
261 #[cfg_attr(feature = "no-panic", no_panic)]
262 fn write(self, buf: &mut [MaybeUninit<u8>; $max_len]) -> &str {
263 let is_nonnegative = self >= 0;
264 let n = if is_nonnegative {
265 self as u128
266 } else {
267 // Convert negative number to positive by summing 1 to its two's complement.
268 (!(self as u128)).wrapping_add(1)
269 };
270 let mut curr = buf.len();
271 let buf_ptr = buf.as_mut_ptr() as *mut u8;
272
273 // Divide by 10^19 which is the highest power less than 2^64.
274 let (n, rem) = udiv128::udivmod_1e19(n);
275 let buf1 = unsafe {
276 buf_ptr.add(curr - u64::MAX_STR_LEN) as *mut [MaybeUninit<u8>; u64::MAX_STR_LEN]
277 };
278 curr -= rem.write(unsafe { &mut *buf1 }).len();
279
280 if n != 0 {
281 // Memset the base10 leading zeros of rem.
282 let target = buf.len() - 19;
283 unsafe {
284 ptr::write_bytes(buf_ptr.add(target), b'0', curr - target);
285 }
286 curr = target;
287
288 // Divide by 10^19 again.
289 let (n, rem) = udiv128::udivmod_1e19(n);
290 let buf2 = unsafe {
291 buf_ptr.add(curr - u64::MAX_STR_LEN)
292 as *mut [MaybeUninit<u8>; u64::MAX_STR_LEN]
293 };
294 curr -= rem.write(unsafe { &mut *buf2 }).len();
295
296 if n != 0 {
297 // Memset the leading zeros.
298 let target = buf.len() - 38;
299 unsafe {
300 ptr::write_bytes(buf_ptr.add(target), b'0', curr - target);
301 }
302 curr = target;
303
304 // There is at most one digit left
305 // because u128::MAX / 10^19 / 10^19 is 3.
306 curr -= 1;
307 unsafe {
308 *buf_ptr.add(curr) = (n as u8) + b'0';
309 }
310 }
311 }
312
313 if !is_nonnegative {
314 curr -= 1;
315 unsafe {
316 *buf_ptr.add(curr) = b'-';
317 }
318 }
319
320 let len = buf.len() - curr;
321 let bytes = unsafe { slice::from_raw_parts(buf_ptr.add(curr), len) };
322 unsafe { str::from_utf8_unchecked(bytes) }
323 }
324 }
325 };
326}
327
328impl_Integer128!(i128[len = 40]);
329impl_Integer128!(u128[len = 39]);
330