diff --git a/src/d2s.rs b/src/d2s.rs index 0d42299..cd61b6f 100644 --- a/src/d2s.rs +++ b/src/d2s.rs @@ -532,7 +532,8 @@ unsafe fn to_chars(v: FloatingDecimal64, sign: bool, result: *mut u8) -> usize { index as usize } -/// Print f64 to the given buffer and return number of bytes written. +/// Print f64 to the given buffer and return number of bytes written. Ryū's +/// original formatting. /// /// At most 24 bytes will be written. /// diff --git a/src/f2s.rs b/src/f2s.rs index a6569b5..818fd1d 100644 --- a/src/f2s.rs +++ b/src/f2s.rs @@ -444,7 +444,8 @@ unsafe fn to_chars(v: FloatingDecimal32, sign: bool, result: *mut u8) -> usize { index as usize } -/// Print f32 to the given buffer and return number of bytes written. +/// Print f32 to the given buffer and return number of bytes written. Ryū's +/// original formatting. /// /// At most 15 bytes will be written. /// diff --git a/src/lib.rs b/src/lib.rs index 24f172e..bef5719 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -63,4 +63,6 @@ pub use buffer::{Buffer, Float}; pub mod raw { pub use d2s::d2s_buffered_n; pub use f2s::f2s_buffered_n; + pub use pretty::d2s_buffered_n as pretty_d2s_buffered_n; + pub use pretty::f2s_buffered_n as pretty_f2s_buffered_n; } diff --git a/src/pretty/mod.rs b/src/pretty/mod.rs index 413f1f4..6b8095c 100644 --- a/src/pretty/mod.rs +++ b/src/pretty/mod.rs @@ -13,6 +13,41 @@ use f2s::*; #[cfg(feature = "no-panic")] use no_panic::no_panic; +/// Print f64 to the given buffer and return number of bytes written. Human +/// readable formatting. +/// +/// At most 24 bytes will be written. +/// +/// ## Special cases +/// +/// This function **does not** check for NaN or infinity. If the input +/// number is not a finite float, the printed representation will be some +/// correctly formatted but unspecified numerical value. +/// +/// Please check [`is_finite`] yourself before calling this function, or +/// check [`is_nan`] and [`is_infinite`] and handle those cases yourself. +/// +/// [`is_finite`]: https://doc.rust-lang.org/std/primitive.f64.html#method.is_finite +/// [`is_nan`]: https://doc.rust-lang.org/std/primitive.f64.html#method.is_nan +/// [`is_infinite`]: https://doc.rust-lang.org/std/primitive.f64.html#method.is_infinite +/// +/// ## Safety +/// +/// The `result` pointer argument must point to sufficiently many writable bytes +/// to hold Ryū's representation of `f`. +/// +/// ## Example +/// +/// ```rust +/// let f = 1.234f64; +/// +/// unsafe { +/// let mut buffer: [u8; 24] = std::mem::uninitialized(); +/// let n = ryu::raw::pretty_d2s_buffered_n(f, &mut buffer[0]); +/// let s = std::str::from_utf8_unchecked(&buffer[..n]); +/// assert_eq!(s, "1.234"); +/// } +/// ``` #[cfg_attr(must_use_return, must_use)] #[cfg_attr(feature = "no-panic", no_panic)] pub unsafe fn d2s_buffered_n(f: f64, result: *mut u8) -> usize { @@ -83,6 +118,41 @@ pub unsafe fn d2s_buffered_n(f: f64, result: *mut u8) -> usize { } } +/// Print f32 to the given buffer and return number of bytes written. Human +/// readable formatting. +/// +/// At most 16 bytes will be written. +/// +/// ## Special cases +/// +/// This function **does not** check for NaN or infinity. If the input +/// number is not a finite float, the printed representation will be some +/// correctly formatted but unspecified numerical value. +/// +/// Please check [`is_finite`] yourself before calling this function, or +/// check [`is_nan`] and [`is_infinite`] and handle those cases yourself. +/// +/// [`is_finite`]: https://doc.rust-lang.org/std/primitive.f32.html#method.is_finite +/// [`is_nan`]: https://doc.rust-lang.org/std/primitive.f32.html#method.is_nan +/// [`is_infinite`]: https://doc.rust-lang.org/std/primitive.f32.html#method.is_infinite +/// +/// ## Safety +/// +/// The `result` pointer argument must point to sufficiently many writable bytes +/// to hold Ryū's representation of `f`. +/// +/// ## Example +/// +/// ```rust +/// let f = 1.234f32; +/// +/// unsafe { +/// let mut buffer: [u8; 16] = std::mem::uninitialized(); +/// let n = ryu::raw::pretty_f2s_buffered_n(f, &mut buffer[0]); +/// let s = std::str::from_utf8_unchecked(&buffer[..n]); +/// assert_eq!(s, "1.234"); +/// } +/// ``` #[cfg_attr(must_use_return, must_use)] #[cfg_attr(feature = "no-panic", no_panic)] pub unsafe fn f2s_buffered_n(f: f32, result: *mut u8) -> usize {