Coverage Report

Created: 2025-07-14 07:05

/rust/registry/src/index.crates.io-6f17d22bba15001f/itoa-1.0.15/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
//! [`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
45
mod udiv128;
46
47
use core::hint;
48
use core::mem::MaybeUninit;
49
use core::{ptr, slice, str};
50
#[cfg(feature = "no-panic")]
51
use 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
/// ```
63
pub struct Buffer {
64
    bytes: [MaybeUninit<u8>; i128::MAX_STR_LEN],
65
}
66
67
impl Default for Buffer {
68
    #[inline]
69
    fn default() -> Buffer {
70
        Buffer::new()
71
    }
72
}
73
74
impl Copy for Buffer {}
75
76
impl 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
84
impl 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
0
    pub fn new() -> Buffer {
90
0
        let bytes = [MaybeUninit::<u8>::uninit(); i128::MAX_STR_LEN];
91
0
        Buffer { bytes }
92
0
    }
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
0
    pub fn format<I: Integer>(&mut self, i: I) -> &str {
98
0
        let string = i.write(unsafe {
99
0
            &mut *(&mut self.bytes as *mut [MaybeUninit<u8>; i128::MAX_STR_LEN]
100
0
                as *mut <I as private::Sealed>::Buffer)
101
0
        });
102
0
        if string.len() > I::MAX_STR_LEN {
103
0
            unsafe { hint::unreachable_unchecked() };
104
0
        }
105
0
        string
106
0
    }
Unexecuted instantiation: <itoa::Buffer>::format::<i8>
Unexecuted instantiation: <itoa::Buffer>::format::<u8>
Unexecuted instantiation: <itoa::Buffer>::format::<i32>
Unexecuted instantiation: <itoa::Buffer>::format::<u32>
Unexecuted instantiation: <itoa::Buffer>::format::<i128>
Unexecuted instantiation: <itoa::Buffer>::format::<u128>
Unexecuted instantiation: <itoa::Buffer>::format::<i16>
Unexecuted instantiation: <itoa::Buffer>::format::<u16>
Unexecuted instantiation: <itoa::Buffer>::format::<i64>
Unexecuted instantiation: <itoa::Buffer>::format::<u64>
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.
112
pub 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.
119
mod 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
128
const 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
137
macro_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
0
            fn write(self, buf: &mut [MaybeUninit<u8>; $max_len]) -> &str {
150
0
                let is_nonnegative = self >= 0;
151
0
                let mut n = if is_nonnegative {
152
0
                    self as $large_unsigned
153
                } else {
154
                    // Convert negative number to positive by summing 1 to its two's complement.
155
0
                    (!(self as $large_unsigned)).wrapping_add(1)
156
                };
157
0
                let mut curr = buf.len();
158
0
                let buf_ptr = buf.as_mut_ptr() as *mut u8;
159
0
                let lut_ptr = DEC_DIGITS_LUT.as_ptr();
160
161
                // Render 4 digits at a time.
162
0
                while n >= 10000 {
163
0
                    let rem = n % 10000;
164
0
                    n /= 10000;
165
0
166
0
                    let d1 = ((rem / 100) << 1) as usize;
167
0
                    let d2 = ((rem % 100) << 1) as usize;
168
0
                    curr -= 4;
169
0
                    unsafe {
170
0
                        ptr::copy_nonoverlapping(lut_ptr.add(d1), buf_ptr.add(curr), 2);
171
0
                        ptr::copy_nonoverlapping(lut_ptr.add(d2), buf_ptr.add(curr + 2), 2);
172
0
                    }
173
                }
174
175
                // Render 2 more digits, if >2 digits.
176
0
                if n >= 100 {
177
0
                    let d1 = ((n % 100) << 1) as usize;
178
0
                    n /= 100;
179
0
                    curr -= 2;
180
0
                    unsafe {
181
0
                        ptr::copy_nonoverlapping(lut_ptr.add(d1), buf_ptr.add(curr), 2);
182
0
                    }
183
0
                }
184
185
                // Render last 1 or 2 digits.
186
0
                if n < 10 {
187
0
                    curr -= 1;
188
0
                    unsafe {
189
0
                        *buf_ptr.add(curr) = (n as u8) + b'0';
190
0
                    }
191
                } else {
192
0
                    let d1 = (n << 1) as usize;
193
0
                    curr -= 2;
194
0
                    unsafe {
195
0
                        ptr::copy_nonoverlapping(lut_ptr.add(d1), buf_ptr.add(curr), 2);
196
0
                    }
197
                }
198
199
0
                if !is_nonnegative {
200
0
                    curr -= 1;
201
0
                    unsafe {
202
0
                        *buf_ptr.add(curr) = b'-';
203
0
                    }
204
0
                }
205
206
0
                let len = buf.len() - curr;
207
0
                let bytes = unsafe { slice::from_raw_parts(buf_ptr.add(curr), len) };
208
0
                unsafe { str::from_utf8_unchecked(bytes) }
209
0
            }
Unexecuted instantiation: <i8 as itoa::private::Sealed>::write
Unexecuted instantiation: <u8 as itoa::private::Sealed>::write
Unexecuted instantiation: <i16 as itoa::private::Sealed>::write
Unexecuted instantiation: <u16 as itoa::private::Sealed>::write
Unexecuted instantiation: <i32 as itoa::private::Sealed>::write
Unexecuted instantiation: <u32 as itoa::private::Sealed>::write
Unexecuted instantiation: <i64 as itoa::private::Sealed>::write
Unexecuted instantiation: <u64 as itoa::private::Sealed>::write
210
        }
211
    };
212
}
213
214
impl_Integer!(i8[len = 4] as u32);
215
impl_Integer!(u8[len = 3] as u32);
216
impl_Integer!(i16[len = 6] as u32);
217
impl_Integer!(u16[len = 5] as u32);
218
impl_Integer!(i32[len = 11] as u32);
219
impl_Integer!(u32[len = 10] as u32);
220
impl_Integer!(i64[len = 20] as u64);
221
impl_Integer!(u64[len = 20] as u64);
222
223
macro_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
243
impl_Integer_size!(isize as i16 #[cfg(target_pointer_width = "16")]);
244
impl_Integer_size!(usize as u16 #[cfg(target_pointer_width = "16")]);
245
impl_Integer_size!(isize as i32 #[cfg(target_pointer_width = "32")]);
246
impl_Integer_size!(usize as u32 #[cfg(target_pointer_width = "32")]);
247
impl_Integer_size!(isize as i64 #[cfg(target_pointer_width = "64")]);
248
impl_Integer_size!(usize as u64 #[cfg(target_pointer_width = "64")]);
249
250
macro_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
0
            fn write(self, buf: &mut [MaybeUninit<u8>; $max_len]) -> &str {
263
0
                let is_nonnegative = self >= 0;
264
0
                let n = if is_nonnegative {
265
0
                    self as u128
266
                } else {
267
                    // Convert negative number to positive by summing 1 to its two's complement.
268
0
                    (!(self as u128)).wrapping_add(1)
269
                };
270
0
                let mut curr = buf.len();
271
0
                let buf_ptr = buf.as_mut_ptr() as *mut u8;
272
0
273
0
                // Divide by 10^19 which is the highest power less than 2^64.
274
0
                let (n, rem) = udiv128::udivmod_1e19(n);
275
0
                let buf1 = unsafe {
276
0
                    buf_ptr.add(curr - u64::MAX_STR_LEN) as *mut [MaybeUninit<u8>; u64::MAX_STR_LEN]
277
0
                };
278
0
                curr -= rem.write(unsafe { &mut *buf1 }).len();
279
0
280
0
                if n != 0 {
281
                    // Memset the base10 leading zeros of rem.
282
0
                    let target = buf.len() - 19;
283
0
                    unsafe {
284
0
                        ptr::write_bytes(buf_ptr.add(target), b'0', curr - target);
285
0
                    }
286
0
                    curr = target;
287
0
288
0
                    // Divide by 10^19 again.
289
0
                    let (n, rem) = udiv128::udivmod_1e19(n);
290
0
                    let buf2 = unsafe {
291
0
                        buf_ptr.add(curr - u64::MAX_STR_LEN)
292
0
                            as *mut [MaybeUninit<u8>; u64::MAX_STR_LEN]
293
0
                    };
294
0
                    curr -= rem.write(unsafe { &mut *buf2 }).len();
295
0
296
0
                    if n != 0 {
297
                        // Memset the leading zeros.
298
0
                        let target = buf.len() - 38;
299
0
                        unsafe {
300
0
                            ptr::write_bytes(buf_ptr.add(target), b'0', curr - target);
301
0
                        }
302
0
                        curr = target;
303
0
304
0
                        // There is at most one digit left
305
0
                        // because u128::MAX / 10^19 / 10^19 is 3.
306
0
                        curr -= 1;
307
0
                        unsafe {
308
0
                            *buf_ptr.add(curr) = (n as u8) + b'0';
309
0
                        }
310
0
                    }
311
0
                }
312
313
0
                if !is_nonnegative {
314
0
                    curr -= 1;
315
0
                    unsafe {
316
0
                        *buf_ptr.add(curr) = b'-';
317
0
                    }
318
0
                }
319
320
0
                let len = buf.len() - curr;
321
0
                let bytes = unsafe { slice::from_raw_parts(buf_ptr.add(curr), len) };
322
0
                unsafe { str::from_utf8_unchecked(bytes) }
323
0
            }
Unexecuted instantiation: <i128 as itoa::private::Sealed>::write
Unexecuted instantiation: <u128 as itoa::private::Sealed>::write
324
        }
325
    };
326
}
327
328
impl_Integer128!(i128[len = 40]);
329
impl_Integer128!(u128[len = 39]);