core/fmt/num.rs
1//! Integer and floating-point number formatting
2
3use crate::fmt::NumBuffer;
4use crate::mem::MaybeUninit;
5use crate::num::imp::fmt as numfmt;
6use crate::{fmt, str};
7
8/// Formatting of integers with a non-decimal radix.
9macro_rules! radix_integer {
10 (fmt::$Trait:ident for $Signed:ident and $Unsigned:ident, $prefix:literal, $dig_tab:literal) => {
11 #[stable(feature = "rust1", since = "1.0.0")]
12 impl fmt::$Trait for $Unsigned {
13 /// Format unsigned integers in the radix.
14 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
15 // Check macro arguments at compile time.
16 const {
17 assert!($Unsigned::MIN == 0, "need unsigned");
18 assert!($dig_tab.is_ascii(), "need single-byte entries");
19 }
20
21 // ASCII digits in ascending order are used as a lookup table.
22 const DIG_TAB: &[u8] = $dig_tab;
23 const BASE: $Unsigned = DIG_TAB.len() as $Unsigned;
24 const MAX_DIG_N: usize = $Unsigned::MAX.ilog(BASE) as usize + 1;
25
26 // Buffer digits of self with right alignment.
27 let mut buf = [MaybeUninit::<u8>::uninit(); MAX_DIG_N];
28 // Count the number of bytes in buf that are not initialized.
29 let mut offset = buf.len();
30
31 // Accumulate each digit of the number from the least
32 // significant to the most significant figure.
33 let mut remain = *self;
34 loop {
35 let digit = remain % BASE;
36 remain /= BASE;
37
38 offset -= 1;
39 // SAFETY: `remain` will reach 0 and we will break before `offset` wraps
40 unsafe { core::hint::assert_unchecked(offset < buf.len()) }
41 buf[offset].write(DIG_TAB[digit as usize]);
42 if remain == 0 {
43 break;
44 }
45 }
46
47 // SAFETY: Starting from `offset`, all elements of the slice have been set.
48 let digits = unsafe { slice_buffer_to_str(&buf, offset) };
49 f.pad_integral(true, $prefix, digits)
50 }
51 }
52
53 #[stable(feature = "rust1", since = "1.0.0")]
54 impl fmt::$Trait for $Signed {
55 /// Format signed integers in the two’s-complement form.
56 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
57 fmt::$Trait::fmt(&self.cast_unsigned(), f)
58 }
59 }
60 };
61}
62
63/// Formatting of integers with a non-decimal radix.
64macro_rules! radix_integers {
65 ($Signed:ident, $Unsigned:ident) => {
66 radix_integer! { fmt::Binary for $Signed and $Unsigned, "0b", b"01" }
67 radix_integer! { fmt::Octal for $Signed and $Unsigned, "0o", b"01234567" }
68 radix_integer! { fmt::LowerHex for $Signed and $Unsigned, "0x", b"0123456789abcdef" }
69 radix_integer! { fmt::UpperHex for $Signed and $Unsigned, "0x", b"0123456789ABCDEF" }
70 };
71}
72radix_integers! { isize, usize }
73radix_integers! { i8, u8 }
74radix_integers! { i16, u16 }
75radix_integers! { i32, u32 }
76radix_integers! { i64, u64 }
77radix_integers! { i128, u128 }
78
79macro_rules! impl_Debug {
80 ($($T:ident)*) => {
81 $(
82 #[stable(feature = "rust1", since = "1.0.0")]
83 impl fmt::Debug for $T {
84 #[inline]
85 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
86 if f.debug_lower_hex() {
87 fmt::LowerHex::fmt(self, f)
88 } else if f.debug_upper_hex() {
89 fmt::UpperHex::fmt(self, f)
90 } else {
91 fmt::Display::fmt(self, f)
92 }
93 }
94 }
95 )*
96 };
97}
98
99// The string of all two-digit numbers in range 00..99 is used as a lookup table.
100static DECIMAL_PAIRS: &[u8; 200] = b"\
101 0001020304050607080910111213141516171819\
102 2021222324252627282930313233343536373839\
103 4041424344454647484950515253545556575859\
104 6061626364656667686970717273747576777879\
105 8081828384858687888990919293949596979899";
106
107/// This function converts a slice of ascii characters into a `&str` starting from `offset`.
108///
109/// # Safety
110///
111/// `buf` content starting from `offset` index MUST BE initialized and MUST BE ascii
112/// characters.
113unsafe fn slice_buffer_to_str(buf: &[MaybeUninit<u8>], offset: usize) -> &str {
114 // SAFETY: `offset` is always included between 0 and `buf`'s length.
115 let written = unsafe { buf.get_unchecked(offset..) };
116 // SAFETY: (`assume_init_ref`) All buf content since offset is set.
117 // SAFETY: (`from_utf8_unchecked`) Writes use ASCII from the lookup table exclusively.
118 unsafe { str::from_utf8_unchecked(written.assume_init_ref()) }
119}
120
121macro_rules! impl_Display {
122 ($($Signed:ident, $Unsigned:ident),* ; as $T:ident into $fmt_fn:ident) => {
123
124 $(
125 const _: () = {
126 assert!($Signed::MIN < 0, "need signed");
127 assert!($Unsigned::MIN == 0, "need unsigned");
128 assert!($Signed::BITS == $Unsigned::BITS, "need counterparts");
129 assert!($Signed::BITS <= $T::BITS, "need lossless conversion");
130 assert!($Unsigned::BITS <= $T::BITS, "need lossless conversion");
131 };
132
133 #[stable(feature = "rust1", since = "1.0.0")]
134 impl fmt::Display for $Unsigned {
135 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
136 #[cfg(not(feature = "optimize_for_size"))]
137 {
138 const MAX_DEC_N: usize = $Unsigned::MAX.ilog10() as usize + 1;
139 // Buffer decimals for self with right alignment.
140 let mut buf = [MaybeUninit::<u8>::uninit(); MAX_DEC_N];
141
142 // SAFETY: `buf` is always big enough to contain all the digits.
143 unsafe { f.pad_integral(true, "", self._fmt(&mut buf)) }
144 }
145 #[cfg(feature = "optimize_for_size")]
146 {
147 // Lossless conversion (with as) is asserted at the top of
148 // this macro.
149 ${concat($fmt_fn, _small)}(*self as $T, true, f)
150 }
151 }
152 }
153
154 #[stable(feature = "rust1", since = "1.0.0")]
155 impl fmt::Display for $Signed {
156 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
157 #[cfg(not(feature = "optimize_for_size"))]
158 {
159 const MAX_DEC_N: usize = $Unsigned::MAX.ilog10() as usize + 1;
160 // Buffer decimals for self with right alignment.
161 let mut buf = [MaybeUninit::<u8>::uninit(); MAX_DEC_N];
162
163 // SAFETY: `buf` is always big enough to contain all the digits.
164 unsafe { f.pad_integral(*self >= 0, "", self.unsigned_abs()._fmt(&mut buf)) }
165 }
166 #[cfg(feature = "optimize_for_size")]
167 {
168 // Lossless conversion (with as) is asserted at the top of
169 // this macro.
170 return ${concat($fmt_fn, _small)}(self.unsigned_abs() as $T, *self >= 0, f);
171 }
172 }
173 }
174
175 #[cfg(not(feature = "optimize_for_size"))]
176 impl $Unsigned {
177 #[doc(hidden)]
178 #[unstable(
179 feature = "fmt_internals",
180 reason = "specialized method meant to only be used by `SpecToString` implementation",
181 issue = "none"
182 )]
183 pub unsafe fn _fmt<'a>(self, buf: &'a mut [MaybeUninit::<u8>]) -> &'a str {
184 // SAFETY: `buf` will always be big enough to contain all digits.
185 let offset = unsafe { self._fmt_inner(buf) };
186 // SAFETY: Starting from `offset`, all elements of the slice have been set.
187 unsafe { slice_buffer_to_str(buf, offset) }
188 }
189
190 unsafe fn _fmt_inner(self, buf: &mut [MaybeUninit::<u8>]) -> usize {
191 // Count the number of bytes in buf that are not initialized.
192 let mut offset = buf.len();
193 // Consume the least-significant decimals from a working copy.
194 let mut remain = self;
195
196 // Format per four digits from the lookup table.
197 // Four digits need a 16-bit $Unsigned or wider.
198 while size_of::<Self>() > 1 && remain > 999.try_into().expect("branch is not hit for types that cannot fit 999 (u8)") {
199 // SAFETY: All of the decimals fit in buf due to MAX_DEC_N
200 // and the while condition ensures at least 4 more decimals.
201 unsafe { core::hint::assert_unchecked(offset >= 4) }
202 // SAFETY: The offset counts down from its initial buf.len()
203 // without underflow due to the previous precondition.
204 unsafe { core::hint::assert_unchecked(offset <= buf.len()) }
205 offset -= 4;
206
207 // pull two pairs
208 let scale: Self = 1_00_00.try_into().expect("branch is not hit for types that cannot fit 1E4 (u8)");
209 let quad = remain % scale;
210 remain /= scale;
211 let pair1 = (quad / 100) as usize;
212 let pair2 = (quad % 100) as usize;
213 buf[offset + 0].write(DECIMAL_PAIRS[pair1 * 2 + 0]);
214 buf[offset + 1].write(DECIMAL_PAIRS[pair1 * 2 + 1]);
215 buf[offset + 2].write(DECIMAL_PAIRS[pair2 * 2 + 0]);
216 buf[offset + 3].write(DECIMAL_PAIRS[pair2 * 2 + 1]);
217 }
218
219 // Format per two digits from the lookup table.
220 if remain > 9 {
221 // SAFETY: All of the decimals fit in buf due to MAX_DEC_N
222 // and the if condition ensures at least 2 more decimals.
223 unsafe { core::hint::assert_unchecked(offset >= 2) }
224 // SAFETY: The offset counts down from its initial buf.len()
225 // without underflow due to the previous precondition.
226 unsafe { core::hint::assert_unchecked(offset <= buf.len()) }
227 offset -= 2;
228
229 let pair = (remain % 100) as usize;
230 remain /= 100;
231 buf[offset + 0].write(DECIMAL_PAIRS[pair * 2 + 0]);
232 buf[offset + 1].write(DECIMAL_PAIRS[pair * 2 + 1]);
233 }
234
235 // Format the last remaining digit, if any.
236 if remain != 0 || self == 0 {
237 // SAFETY: All of the decimals fit in buf due to MAX_DEC_N
238 // and the if condition ensures (at least) 1 more decimals.
239 unsafe { core::hint::assert_unchecked(offset >= 1) }
240 // SAFETY: The offset counts down from its initial buf.len()
241 // without underflow due to the previous precondition.
242 unsafe { core::hint::assert_unchecked(offset <= buf.len()) }
243 offset -= 1;
244
245 // Either the compiler sees that remain < 10, or it prevents
246 // a boundary check up next.
247 let last = (remain & 15) as usize;
248 buf[offset].write(DECIMAL_PAIRS[last * 2 + 1]);
249 // not used: remain = 0;
250 }
251
252 offset
253 }
254 }
255
256 impl $Signed {
257 /// Formats this integer as a signed decimal number, using the memory pointed to by
258 /// `buf` as storage for the returned string slice.
259 ///
260 /// This method can be used to convert integers to strings without involving the
261 /// dynamic dispatch that using [`Display`][fmt::Display] would.
262 /// This may be more efficient in situations where [`fmt`] is not otherwise used.
263 ///
264 /// # Examples
265 ///
266 /// ```
267 /// use core::fmt::NumBuffer;
268 ///
269 #[doc = concat!("let n = 0", stringify!($Signed), ";")]
270 /// let mut buf = NumBuffer::new();
271 /// assert_eq!(n.format_into(&mut buf), "0");
272 ///
273 #[doc = concat!("let n1 = 32", stringify!($Signed), ";")]
274 /// assert_eq!(n1.format_into(&mut buf), "32");
275 ///
276 #[doc = concat!("let n2 = ", stringify!($Signed), "::MAX;")]
277 #[doc = concat!("assert_eq!(n2.format_into(&mut buf), ", stringify!($Signed), "::MAX.to_string());")]
278 /// ```
279 #[stable(feature = "int_format_into", since = "1.98.0")]
280 pub fn format_into(self, buf: &mut NumBuffer<Self>) -> &str {
281 let mut offset;
282
283 #[cfg(not(feature = "optimize_for_size"))]
284 // SAFETY: `buf` is from a `NumBuffer`, so it will always be big enough to contain all digits.
285 unsafe {
286 offset = self.unsigned_abs()._fmt_inner(&mut buf.buf);
287 }
288 #[cfg(feature = "optimize_for_size")]
289 {
290 // Lossless conversion (with as) is asserted at the top of
291 // this macro.
292 // SAFETY: `buf` is from a `NumBuffer`, so it will always be big enough to contain all digits.
293 offset = unsafe { ${concat($fmt_fn, _in_buf_small)}(self.unsigned_abs() as $T, &mut buf.buf) };
294 }
295 // Only difference between signed and unsigned are these 4 lines.
296 if self < 0 {
297 offset -= 1;
298 buf.buf[offset].write(b'-');
299 }
300 // SAFETY: Starting from `offset`, all elements of the slice have been set.
301 unsafe { slice_buffer_to_str(&buf.buf, offset) }
302 }
303 }
304
305 impl $Unsigned {
306 /// Formats this integer as an unsigned decimal number, using the memory pointed to by
307 /// `buf` as storage for the returned string slice.
308 ///
309 /// This method can be used to convert integers to strings without involving the
310 /// dynamic dispatch that using [`Display`][fmt::Display] would.
311 /// This may be more efficient in situations where [`fmt`] is not otherwise used.
312 ///
313 /// # Examples
314 ///
315 /// ```
316 /// use core::fmt::NumBuffer;
317 ///
318 #[doc = concat!("let n = 0", stringify!($Unsigned), ";")]
319 /// let mut buf = NumBuffer::new();
320 /// assert_eq!(n.format_into(&mut buf), "0");
321 ///
322 #[doc = concat!("let n1 = 32", stringify!($Unsigned), ";")]
323 /// assert_eq!(n1.format_into(&mut buf), "32");
324 ///
325 #[doc = concat!("let n2 = ", stringify!($Unsigned::MAX), ";")]
326 #[doc = concat!("assert_eq!(n2.format_into(&mut buf), ", stringify!($Unsigned::MAX), ".to_string());")]
327 /// ```
328 #[stable(feature = "int_format_into", since = "1.98.0")]
329 pub fn format_into(self, buf: &mut NumBuffer<Self>) -> &str {
330 let offset;
331
332 #[cfg(not(feature = "optimize_for_size"))]
333 // SAFETY: `buf` is from a `NumBuffer`, so it will always be big enough to contain all digits.
334 unsafe {
335 offset = self._fmt_inner(&mut buf.buf);
336 }
337 #[cfg(feature = "optimize_for_size")]
338 {
339 // Lossless conversion (with as) is asserted at the top of
340 // this macro.
341 // SAFETY: `buf` is from a `NumBuffer`, so it will always be big enough to contain all digits.
342 offset = unsafe { ${concat($fmt_fn, _in_buf_small)}(self as $T, &mut buf.buf) };
343 }
344 // SAFETY: Starting from `offset`, all elements of the slice have been set.
345 unsafe { slice_buffer_to_str(&buf.buf, offset) }
346 }
347 }
348
349 )*
350
351 /// # Safety
352 /// The number's decimal representation must fit into the buffer.
353 /// i.e. `n == 0 && buf.len() >= 1 || n.ilog10() + 1 <= buf.len()`
354 ///
355 /// Note that this function is shared across sizes. In particular, `u8` and `u16` use the
356 /// `u32` version of this function, so the buffer length is not always the same; this
357 /// prevents the function from being safe, and/or using `NumBuffer`.
358 #[cfg(feature = "optimize_for_size")]
359 unsafe fn ${concat($fmt_fn, _in_buf_small)}(mut n: $T, buf: &mut [MaybeUninit::<u8>]) -> usize {
360 debug_assert!(n == 0 && buf.len() >= 1 || buf.len() >= n.ilog10() as usize + 1);
361
362 let mut curr = buf.len();
363
364 // SAFETY:
365 // For `n == 0`, we only access index 0, and `buf.len() >= 1`.
366 // Otherwise, it takes `n.ilog10() + 1` divisions by 10 for `n`
367 // to become 0. Hence `curr` is decremented at most that many times.
368 // Then due to `buf.len() >= n.ilog10() + 1`, `curr` can never
369 // wrap, which means it is in-bounds (since it starts in-bounds
370 // and counts down).
371 unsafe {
372 loop {
373 curr -= 1;
374 buf.get_unchecked_mut(curr).write((n % 10) as u8 + b'0');
375 n /= 10;
376
377 if n == 0 {
378 break;
379 }
380 }
381 }
382 curr
383 }
384
385 #[cfg(feature = "optimize_for_size")]
386 fn ${concat($fmt_fn, _small)}(n: $T, is_nonnegative: bool, f: &mut fmt::Formatter<'_>) -> fmt::Result {
387 const MAX_DEC_N: usize = $T::MAX.ilog10() as usize + 1;
388 let mut buf = [MaybeUninit::<u8>::uninit(); MAX_DEC_N];
389
390 // SAFETY: `T::MAX` is the largest possible decimal length, so the buffer is large enough.
391 let offset = unsafe { ${concat($fmt_fn, _in_buf_small)}(n, &mut buf) };
392 // SAFETY: Starting from `offset`, all elements of the slice have been set.
393 let buf_slice = unsafe { slice_buffer_to_str(&buf, offset) };
394 f.pad_integral(is_nonnegative, "", buf_slice)
395 }
396 };
397}
398
399macro_rules! impl_Exp {
400 ($($Signed:ident, $Unsigned:ident),* ; as $T:ident into $fmt_fn:ident) => {
401 const _: () = assert!($T::MIN == 0, "need unsigned");
402
403 fn $fmt_fn(
404 f: &mut fmt::Formatter<'_>,
405 n: $T,
406 is_nonnegative: bool,
407 letter_e: u8
408 ) -> fmt::Result {
409 debug_assert!(letter_e.is_ascii_alphabetic(), "single-byte character");
410
411 // Print the integer as a coefficient in range (-10, 10).
412 let mut exp = n.checked_ilog10().unwrap_or(0) as usize;
413 debug_assert!(n / (10 as $T).pow(exp as u32) < 10);
414
415 // Precisison is counted as the number of digits in the fraction.
416 let mut coef_prec = exp;
417 // Keep the digits as an integer (paired with its coef_prec count).
418 let mut coef = n;
419
420 // A Formatter may set the precision to a fixed number of decimals.
421 let more_prec = match f.precision() {
422 None => {
423 // Omit any and all trailing zeroes.
424 while coef_prec != 0 && coef % 10 == 0 {
425 coef /= 10;
426 coef_prec -= 1;
427 }
428 0
429 },
430
431 Some(fmt_prec) if fmt_prec >= coef_prec => {
432 // Count the number of additional zeroes needed.
433 fmt_prec - coef_prec
434 },
435
436 Some(fmt_prec) => {
437 // Count the number of digits to drop.
438 let less_prec = coef_prec - fmt_prec;
439 assert!(less_prec > 0);
440 // Scale down the coefficient/precision pair. For example,
441 // coef 123456 gets coef_prec 5 (to make 1.23456). To format
442 // the number with 2 decimals, i.e., fmt_prec 2, coef should
443 // be scaled by 10⁵⁻²=1000 to get coef 123 with coef_prec 2.
444
445 // SAFETY: Any precision less than coef_prec will cause a
446 // power of ten below the coef value.
447 let scale = unsafe {
448 (10 as $T).checked_pow(less_prec as u32).unwrap_unchecked()
449 };
450 let floor = coef / scale;
451 // Round half to even conform documentation.
452 let over = coef % scale;
453 let half = scale / 2;
454 let round_up = if over < half {
455 0
456 } else if over > half {
457 1
458 } else {
459 floor & 1 // round odd up to even
460 };
461 // Adding one to a scale down of at least 10 won't overflow.
462 coef = floor + round_up;
463 coef_prec = fmt_prec;
464
465 // The round_up may have caused the coefficient to reach 10
466 // (which is not permitted). For example, anything in range
467 // [9.95, 10) becomes 10.0 when adjusted to precision 1.
468 if round_up != 0 && coef.checked_ilog10().unwrap_or(0) as usize > coef_prec {
469 debug_assert_eq!(coef, (10 as $T).pow(coef_prec as u32 + 1));
470 coef /= 10; // drop one trailing zero
471 exp += 1; // one power of ten higher
472 }
473 0
474 },
475 };
476
477 // Allocate a text buffer with lazy initialization.
478 const MAX_DEC_N: usize = $T::MAX.ilog10() as usize + 1;
479 const MAX_COEF_LEN: usize = MAX_DEC_N + ".".len();
480 const MAX_TEXT_LEN: usize = MAX_COEF_LEN + "e99".len();
481 let mut buf = [MaybeUninit::<u8>::uninit(); MAX_TEXT_LEN];
482
483 // Encode the coefficient in buf[..coef_len].
484 let (lead_dec, coef_len) = if coef_prec == 0 && more_prec == 0 {
485 (coef, 1_usize) // single digit; no fraction
486 } else {
487 buf[1].write(b'.');
488 let fraction_range = 2..(2 + coef_prec);
489
490 // Consume the least-significant decimals from a working copy.
491 let mut remain = coef;
492 #[cfg(feature = "optimize_for_size")] {
493 for i in fraction_range.clone().rev() {
494 let digit = (remain % 10) as usize;
495 remain /= 10;
496 buf[i].write(b'0' + digit as u8);
497 }
498 }
499 #[cfg(not(feature = "optimize_for_size"))] {
500 // Write digits per two at a time with a lookup table.
501 for i in fraction_range.clone().skip(1).rev().step_by(2) {
502 let pair = (remain % 100) as usize;
503 remain /= 100;
504 buf[i - 1].write(DECIMAL_PAIRS[pair * 2 + 0]);
505 buf[i - 0].write(DECIMAL_PAIRS[pair * 2 + 1]);
506 }
507 // An odd number of digits leave one digit remaining.
508 if coef_prec & 1 != 0 {
509 let digit = (remain % 10) as usize;
510 remain /= 10;
511 buf[fraction_range.start].write(b'0' + digit as u8);
512 }
513 }
514
515 (remain, fraction_range.end)
516 };
517 debug_assert!(lead_dec < 10);
518 debug_assert!(lead_dec != 0 || coef == 0, "significant digits only");
519 buf[0].write(b'0' + lead_dec as u8);
520
521 // SAFETY: The number of decimals is limited, captured by MAX.
522 unsafe { core::hint::assert_unchecked(coef_len <= MAX_COEF_LEN) }
523 // Encode the scale factor in buf[coef_len..text_len].
524 buf[coef_len].write(letter_e);
525 let text_len: usize = match exp {
526 ..10 => {
527 buf[coef_len + 1].write(b'0' + exp as u8);
528 coef_len + 2
529 },
530 10..100 => {
531 #[cfg(feature = "optimize_for_size")] {
532 buf[coef_len + 1].write(b'0' + (exp / 10) as u8);
533 buf[coef_len + 2].write(b'0' + (exp % 10) as u8);
534 }
535 #[cfg(not(feature = "optimize_for_size"))] {
536 buf[coef_len + 1].write(DECIMAL_PAIRS[exp * 2 + 0]);
537 buf[coef_len + 2].write(DECIMAL_PAIRS[exp * 2 + 1]);
538 }
539 coef_len + 3
540 },
541 _ => {
542 const { assert!($T::MAX.ilog10() < 100) };
543 // SAFETY: A `u256::MAX` would get exponent 77.
544 unsafe { core::hint::unreachable_unchecked() }
545 }
546 };
547 // SAFETY: All bytes up until text_len have been set.
548 let text = unsafe { buf[..text_len].assume_init_ref() };
549
550 if more_prec == 0 {
551 // SAFETY: Text is set with ASCII exclusively: either a decimal,
552 // or a LETTER_E, or a dot. ASCII implies valid UTF-8.
553 let as_str = unsafe { str::from_utf8_unchecked(text) };
554 f.pad_integral(is_nonnegative, "", as_str)
555 } else {
556 let parts = &[
557 numfmt::Part::Copy(&text[..coef_len]),
558 numfmt::Part::Zero(more_prec),
559 numfmt::Part::Copy(&text[coef_len..]),
560 ];
561 let sign = if !is_nonnegative {
562 "-"
563 } else if f.sign_plus() {
564 "+"
565 } else {
566 ""
567 };
568 // SAFETY: Text is set with ASCII exclusively: either a decimal,
569 // or a LETTER_E, or a dot. ASCII implies valid UTF-8.
570 unsafe { f.pad_formatted_parts(&numfmt::Formatted { sign, parts }) }
571 }
572 }
573
574 $(
575 const _: () = {
576 assert!($Signed::MIN < 0, "need signed");
577 assert!($Unsigned::MIN == 0, "need unsigned");
578 assert!($Signed::BITS == $Unsigned::BITS, "need counterparts");
579 assert!($Signed::BITS <= $T::BITS, "need lossless conversion");
580 assert!($Unsigned::BITS <= $T::BITS, "need lossless conversion");
581 };
582 #[stable(feature = "integer_exp_format", since = "1.42.0")]
583 impl fmt::LowerExp for $Signed {
584 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
585 $fmt_fn(f, self.unsigned_abs() as $T, *self >= 0, b'e')
586 }
587 }
588 #[stable(feature = "integer_exp_format", since = "1.42.0")]
589 impl fmt::LowerExp for $Unsigned {
590 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
591 $fmt_fn(f, *self as $T, true, b'e')
592 }
593 }
594 #[stable(feature = "integer_exp_format", since = "1.42.0")]
595 impl fmt::UpperExp for $Signed {
596 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
597 $fmt_fn(f, self.unsigned_abs() as $T, *self >= 0, b'E')
598 }
599 }
600 #[stable(feature = "integer_exp_format", since = "1.42.0")]
601 impl fmt::UpperExp for $Unsigned {
602 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
603 $fmt_fn(f, *self as $T, true, b'E')
604 }
605 }
606 )*
607
608 };
609}
610
611impl_Debug! {
612 i8 i16 i32 i64 i128 isize
613 u8 u16 u32 u64 u128 usize
614}
615
616// Include wasm32 in here since it doesn't reflect the native pointer size, and
617// often cares strongly about getting a smaller code size.
618#[cfg(any(target_pointer_width = "64", target_arch = "wasm32"))]
619#[doc(auto_cfg = false)]
620mod imp {
621 use super::*;
622 impl_Display!(i8, u8, i16, u16, i32, u32, i64, u64, isize, usize; as u64 into display_u64);
623 impl_Exp!(i8, u8, i16, u16, i32, u32, i64, u64, isize, usize; as u64 into exp_u64);
624}
625
626#[cfg(not(any(target_pointer_width = "64", target_arch = "wasm32")))]
627#[doc(auto_cfg = false)]
628mod imp {
629 use super::*;
630 impl_Display!(i8, u8, i16, u16, i32, u32, isize, usize; as u32 into display_u32);
631 impl_Display!(i64, u64; as u64 into display_u64);
632
633 impl_Exp!(i8, u8, i16, u16, i32, u32, isize, usize; as u32 into exp_u32);
634 impl_Exp!(i64, u64; as u64 into exp_u64);
635}
636impl_Exp!(i128, u128; as u128 into exp_u128);
637
638const U128_MAX_DEC_N: usize = u128::MAX.ilog10() as usize + 1;
639
640#[stable(feature = "rust1", since = "1.0.0")]
641impl fmt::Display for u128 {
642 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
643 let mut buf = [MaybeUninit::<u8>::uninit(); U128_MAX_DEC_N];
644
645 // SAFETY: `buf` is always big enough to contain all the digits.
646 unsafe { f.pad_integral(true, "", self._fmt(&mut buf)) }
647 }
648}
649
650#[stable(feature = "rust1", since = "1.0.0")]
651impl fmt::Display for i128 {
652 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
653 // This is not a typo, we use the maximum number of digits of `u128`, hence why we use
654 // `U128_MAX_DEC_N`.
655 let mut buf = [MaybeUninit::<u8>::uninit(); U128_MAX_DEC_N];
656
657 let is_nonnegative = *self >= 0;
658 // SAFETY: `buf` is always big enough to contain all the digits.
659 unsafe { f.pad_integral(is_nonnegative, "", self.unsigned_abs()._fmt(&mut buf)) }
660 }
661}
662
663impl u128 {
664 /// Format optimized for u128. Computation of 128 bits is limited by processing
665 /// in batches of 16 decimals at a time.
666 #[doc(hidden)]
667 #[unstable(
668 feature = "fmt_internals",
669 reason = "specialized method meant to only be used by `SpecToString` implementation",
670 issue = "none"
671 )]
672 pub unsafe fn _fmt<'a>(self, buf: &'a mut [MaybeUninit<u8>]) -> &'a str {
673 // SAFETY: `buf` will always be big enough to contain all digits.
674 let offset = unsafe { self._fmt_inner(buf) };
675 // SAFETY: Starting from `offset`, all elements of the slice have been set.
676 unsafe { slice_buffer_to_str(buf, offset) }
677 }
678
679 unsafe fn _fmt_inner(self, buf: &mut [MaybeUninit<u8>]) -> usize {
680 // Optimize common-case zero, which would also need special treatment due to
681 // its "leading" zero.
682 if self == 0 {
683 let offset = buf.len() - 1;
684 buf[offset].write(b'0');
685 return offset;
686 }
687 // Take the 16 least-significant decimals.
688 let (quot_1e16, mod_1e16) = div_rem_1e16(self);
689 let (mut remain, mut offset) = if quot_1e16 == 0 {
690 (mod_1e16, U128_MAX_DEC_N)
691 } else {
692 // Write digits at buf[23..39].
693 //
694 // SAFETY: `mod_1e16 < 1e16` (remainder), and `U128_MAX_DEC_N - 16 + 16 == buf.len()`.
695 unsafe { enc_16lsd::<{ U128_MAX_DEC_N - 16 }>(buf, mod_1e16) };
696
697 // Take another 16 decimals.
698 let (quot2, mod2) = div_rem_1e16(quot_1e16);
699 if quot2 == 0 {
700 (mod2, U128_MAX_DEC_N - 16)
701 } else {
702 // Write digits at buf[7..23].
703 //
704 // SAFETY: `mod2 < 1e16` (remainder), and `U128_MAX_DEC_N - 32 + 16 <= buf.len()`.
705 unsafe { enc_16lsd::<{ U128_MAX_DEC_N - 32 }>(buf, mod2) };
706
707 // Quot2 has at most 7 decimals remaining after two 1e16 divisions.
708 (quot2 as u64, U128_MAX_DEC_N - 32)
709 }
710 };
711
712 // Format per four digits from the lookup table.
713 while remain > 999 {
714 // SAFETY: All of the decimals fit in buf due to U128_MAX_DEC_N
715 // and the while condition ensures at least 4 more decimals.
716 unsafe { core::hint::assert_unchecked(offset >= 4) }
717 // SAFETY: The offset counts down from its initial buf.len()
718 // without underflow due to the previous precondition.
719 unsafe { core::hint::assert_unchecked(offset <= buf.len()) }
720 offset -= 4;
721
722 let quad = remain % 1_00_00;
723 remain /= 1_00_00;
724
725 // SAFETY: quad is a remainder modulo 10_000. The offset checks
726 // above reserve exactly four bytes in buf.
727 unsafe {
728 write_quad(buf.get_unchecked_mut(offset..offset + 4), quad);
729 }
730 }
731
732 // Format per two digits from the lookup table.
733 if remain > 9 {
734 // SAFETY: All of the decimals fit in buf due to U128_MAX_DEC_N
735 // and the if condition ensures at least 2 more decimals.
736 unsafe { core::hint::assert_unchecked(offset >= 2) }
737 // SAFETY: The offset counts down from its initial buf.len()
738 // without underflow due to the previous precondition.
739 unsafe { core::hint::assert_unchecked(offset <= buf.len()) }
740 offset -= 2;
741
742 let pair = (remain % 100) as usize;
743 remain /= 100;
744 buf[offset + 0].write(DECIMAL_PAIRS[pair * 2 + 0]);
745 buf[offset + 1].write(DECIMAL_PAIRS[pair * 2 + 1]);
746 }
747
748 // Format the last remaining digit, if any.
749 if remain != 0 {
750 // SAFETY: All of the decimals fit in buf due to U128_MAX_DEC_N
751 // and the if condition ensures (at least) 1 more decimals.
752 unsafe { core::hint::assert_unchecked(offset >= 1) }
753 // SAFETY: The offset counts down from its initial buf.len()
754 // without underflow due to the previous precondition.
755 unsafe { core::hint::assert_unchecked(offset <= buf.len()) }
756 offset -= 1;
757
758 // Either the compiler sees that remain < 10, or it prevents
759 // a boundary check up next.
760 let last = (remain & 15) as usize;
761 buf[offset].write(DECIMAL_PAIRS[last * 2 + 1]);
762 // not used: remain = 0;
763 }
764 offset
765 }
766
767 /// Formats this integer as an unsigned decimal number, using the memory pointed to by
768 /// `buf` as storage for the returned string slice.
769 ///
770 /// This method can be used to convert integers to strings without involving the
771 /// dynamic dispatch that using [`Display`][fmt::Display] would.
772 /// This may be more efficient in situations where [`fmt`] is not otherwise used.
773 ///
774 /// # Examples
775 ///
776 /// ```
777 /// use core::fmt::NumBuffer;
778 ///
779 /// let n = 0u128;
780 /// let mut buf = NumBuffer::new();
781 /// assert_eq!(n.format_into(&mut buf), "0");
782 ///
783 /// let n1 = 32u128;
784 /// let mut buf1 = NumBuffer::new();
785 /// assert_eq!(n1.format_into(&mut buf1), "32");
786 ///
787 /// let n2 = u128::MAX;
788 /// let mut buf2 = NumBuffer::new();
789 /// assert_eq!(n2.format_into(&mut buf2), u128::MAX.to_string());
790 /// ```
791 #[stable(feature = "int_format_into", since = "1.98.0")]
792 pub fn format_into(self, buf: &mut NumBuffer<Self>) -> &str {
793 let diff = buf.buf.len() - U128_MAX_DEC_N;
794 // FIXME: Once const generics are better, use `NumberBufferTrait::BUF_SIZE` as generic const
795 // for `fmt_u128_inner`.
796 //
797 // In the meantime, we have to use a slice starting at index 1 and add 1 to the returned
798 // offset to ensure the number is correctly generated at the end of the buffer.
799 // SAFETY: `diff` will always be between 0 and its initial value.
800 unsafe { self._fmt(buf.buf.get_unchecked_mut(diff..)) }
801 }
802}
803
804impl i128 {
805 /// Formats this integer as a signed decimal number, using the memory pointed to by
806 /// `buf` as storage for the returned string slice.
807 ///
808 /// This method can be used to convert integers to strings without involving the
809 /// dynamic dispatch that using [`Display`][fmt::Display] would.
810 /// This may be more efficient in situations where [`fmt`] is not otherwise used.
811 ///
812 /// # Examples
813 ///
814 /// ```
815 /// use core::fmt::NumBuffer;
816 ///
817 /// let n = 0i128;
818 /// let mut buf = NumBuffer::new();
819 /// assert_eq!(n.format_into(&mut buf), "0");
820 ///
821 /// let n1 = i128::MIN;
822 /// assert_eq!(n1.format_into(&mut buf), i128::MIN.to_string());
823 ///
824 /// let n2 = i128::MAX;
825 /// assert_eq!(n2.format_into(&mut buf), i128::MAX.to_string());
826 /// ```
827 #[stable(feature = "int_format_into", since = "1.98.0")]
828 pub fn format_into(self, buf: &mut NumBuffer<Self>) -> &str {
829 let diff = buf.buf.len() - U128_MAX_DEC_N;
830 // FIXME: Once const generics are better, use `NumberBufferTrait::BUF_SIZE` as generic const
831 // for `fmt_u128_inner`.
832 //
833 // In the meantime, we have to use a slice starting at index 1 and add 1 to the returned
834 // offset to ensure the number is correctly generated at the end of the buffer.
835 let mut offset =
836 // SAFETY: `buf` will always be big enough to contain all digits.
837 unsafe { self.unsigned_abs()._fmt_inner(buf.buf.get_unchecked_mut(diff..)) };
838 // We put back the offset at the right position.
839 offset += diff;
840 // Only difference between signed and unsigned are these 4 lines.
841 if self < 0 {
842 offset -= 1;
843 // SAFETY: `buf` will always be big enough to contain all digits plus the minus sign.
844 unsafe {
845 buf.buf.get_unchecked_mut(offset).write(b'-');
846 }
847 }
848 // SAFETY: Starting from `offset`, all elements of the slice have been set.
849 unsafe { slice_buffer_to_str(&buf.buf, offset) }
850 }
851}
852
853/// Writes `quad` as exactly four digits (for example: `42` becomes `"0042"`).
854///
855/// # Safety
856///
857/// `quad` must be below 10_000 and `buf` must contain exactly four bytes.
858#[inline(always)]
859unsafe fn write_quad(buf: &mut [MaybeUninit<u8>], quad: u64) {
860 // SAFETY: These are this function's caller-provided invariants.
861 unsafe {
862 core::hint::assert_unchecked(quad < 10_000);
863 core::hint::assert_unchecked(buf.len() == 4);
864 }
865
866 let quad = quad as u32;
867
868 // Note: this is equivalent to `quad / 100`, but contains no division instructions.
869 let high = (quad * const { (1 << 19) / 100 + 1 }) >> 19;
870 let low = quad - high * 100;
871 let high = high as usize;
872 let low = low as usize;
873
874 // SAFETY: `high` and `low` are below 100 because `quad` is below 10_000.
875 unsafe { core::hint::assert_unchecked(high < 100 && low < 100) }
876
877 buf[0..2].write_copy_of_slice(&DECIMAL_PAIRS[high * 2..high * 2 + 2]);
878 buf[2..4].write_copy_of_slice(&DECIMAL_PAIRS[low * 2..low * 2 + 2]);
879}
880
881/// Encodes the 16 least-significant decimals of n into `buf[OFFSET .. OFFSET +
882/// 16 ]`.
883///
884/// # Safety
885///
886/// `n` must be below 1e16, and `buf` must be at least `OFFSET + 16` bytes long.
887unsafe fn enc_16lsd<const OFFSET: usize>(buf: &mut [MaybeUninit<u8>], n: u64) {
888 // SAFETY: Every caller passes a remainder produced by division by 10^16,
889 // and every used `OFFSET` specialization reserves sixteen bytes in `buf`.
890 unsafe {
891 core::hint::assert_unchecked(n < 10_000_000_000_000_000);
892 core::hint::assert_unchecked(OFFSET + 16 <= buf.len());
893 }
894
895 // Peel four digits at a time from right to left (12345678 -> 1234 | 5678).
896 // Since 10_000 is constant, LLVM replaces each division with multiply or shift.
897 let mut remain = n;
898
899 for quad_index in (1..4).rev() {
900 let quad = remain % 1_00_00;
901 remain /= 1_00_00;
902
903 // SAFETY: `OFFSET + quad_index * 4` starts one of the four
904 // non-overlapping four-byte regions proven in bounds above.
905 unsafe {
906 write_quad(
907 buf.get_unchecked_mut(OFFSET + quad_index * 4..OFFSET + (quad_index + 1) * 4),
908 quad,
909 );
910 }
911 }
912
913 // SAFETY: OFFSET starts the first four-byte region proven in bounds above.
914 unsafe {
915 write_quad(buf.get_unchecked_mut(OFFSET..OFFSET + 4), remain);
916 }
917}
918
919/// Euclidean division plus remainder with constant 1E16 basically consumes 16
920/// decimals from n.
921///
922/// The integer division algorithm is based on the following paper:
923///
924/// T. Granlund and P. Montgomery, “Division by Invariant Integers Using Multiplication”
925/// in Proc. of the SIGPLAN94 Conference on Programming Language Design and
926/// Implementation, 1994, pp. 61–72
927///
928#[inline]
929fn div_rem_1e16(n: u128) -> (u128, u64) {
930 const D: u128 = 1_0000_0000_0000_0000;
931 // The check inlines well with the caller flow.
932 if n < D {
933 return (0, n as u64);
934 }
935
936 // These constant values are computed with the CHOOSE_MULTIPLIER procedure
937 // from the Granlund & Montgomery paper, using N=128, prec=128 and d=1E16.
938 const M_HIGH: u128 = 76624777043294442917917351357515459181;
939 const SH_POST: u8 = 51;
940
941 let quot = n.carrying_mul(M_HIGH, 0).1 >> SH_POST;
942 let rem = n - quot * D;
943 (quot, rem as u64)
944}