Tracking Issue for integer formatting into a fixed-size buffer

[hanna-kruppe]

View all comments

Feature gate: #![feature(int_format_into)]

This is a tracking issue for efficient decimal integer formatting into a fixed-size buffer.

Public API

// core::fmt

pub struct NumBuffer<T: NumBufferTrait> { .. }
impl<T: NumBufferTrait> NumBuffer<T> {
    pub const fn new() -> Self;
    pub const fn capacity(&self) -> usize;
}
impl<T: NumBufferTrait + Debug> Debug for NumBuffer<T>;

pub trait NumBufferTrait {
    const BUF_SIZE: usize;
}

impl $Int {
    fn format_into(self, &mut NumBuffer<Self>) -> &str;
}

Steps / History

• ACP: Efficient integer formatting into fixed-size buffer libs-team#546
• Implementation: Implement int_format_into feature #142098
• Final comment period (FCP)¹
• Stabilization PR: Stabilize int_format_into feature #152544

Unresolved Questions

• Should this return &[ascii::Char] in the future? Efficient integer formatting into fixed-size buffer libs-team#546 (comment)
• Should NumBuffer be NumBuffer<$Int> so that the reserved space can be tailored to the specific integer's size? Not a big difference with current integer types, but may be significant if we gain u8192 in the future.
• Naming of core::num::NumBuffer.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[hanna-kruppe]

Implementation should be a straightforward refactoring of the existing code, but I don't know if and when I'll have time to do that, so I'd welcome if someone else wants to implement it.

@rustbot label E-easy E-help-wanted

[madhav-madhusoodanan]

Hi, I'd love to implement this
@rustbot claim

[Kijewski]

In my experience with itoa, one problem with the equally sized buffers for all int types u8 to u128 is that a memcpy is generated when there is no need to. A u8 won't stringify to 20 bytes and it won't benefit from "smarter" copy implementations. A 3 byte buffer for u8, 4 bytes for i8, … would generate much better byte code. I guess this will be the same with this feature.

[hanna-kruppe]

As I understand it, the main problem with the memcpy is that the number of bytes to copy is variable (determined at runtime), not that the underlying buffer is oversized. An u32 may turn into anything between one and 10 ASCII digits, so there’s no nice, fixed sequence of loads and stores to emit instead of a memcpy call. It’s possible to come up with marginally better inline code for specific length bounds (an oversized buffer can actually be helpful for this) but the real solution is to change the algorithm to avoid the variable-length copy to begin with. If you compute the number of digits up-front you can generate digits directly into the right place of the destination buffer and don’t need any memcpy.

However, that would be a more invasive change to the current standard library implementation and to the API sketch that was accepted in the ACP. Of course I’d be happy to see an even better solution for this functionality but after thinking about it for quite some time, I’m not sure of this is possible without tough trade-offs. So I’d rather see Rust ship something that’s going to work well for the libraries that happily use itoa today than never shipping anything because perfection is hard.

[madhav-madhusoodanan]

Implementation should be a straightforward refactoring of the existing code, but I don't know if and when I'll have time to do that, so I'd welcome if someone else wants to implement it.

By refactor, did you mean actually create an implementation from scratch?
Also as I understand it, there isn't a Buffer implementation so we'd need to create the NumBuffer type right?

Looking forward to learning a lot by implementing this feature.

[hanna-kruppe]

I mean that the code that implements the formatting doesn’t have to change except being refactored to expose it’s existing functionality in a new way (accept a buffer as argument instead of writing into its local variable buf, return as_str to the caller instead of always passing it to f.pad_integral). You’re right that the NumBuffer type needs to be created from scratch, but that type doesn’t do anything complicated, it just needs to contain a sufficiently large array of MaybeUninit<u8> to replace the local variable buf in the formatting implementation.

[KaustubhKhulbe]

Is there still available work on this? I'd like to get involved :)