Coverage Report

Created: 2025-07-11 06:39

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