pub trait ToLexicalWithOptions: FormattedSize + Number {
type Options: WriteOptions;
// Required method
fn to_lexical_with_options<'a, const FORMAT: u128>(
self,
bytes: &'a mut [u8],
options: &Self::Options,
) -> &'a mut [u8] ⓘ;
}
write-floats
or write-integers
only.Expand description
Trait for numerical types that can be serialized to bytes with custom options.
To determine the number of bytes required to serialize a value to string, check the associated constants from a required trait:
FORMATTED_SIZE
: The number of bytes required for any number for any radix, that is,2
to36
.FORMATTED_SIZE_DECIMAL
: The number of bytes required for decimal (base 10) numbers.
The Options
type specifies the configurable options to provide.
Required Associated Types§
Sourcetype Options: WriteOptions
type Options: WriteOptions
Custom formatting options for writing a number.
Required Methods§
Sourcefn to_lexical_with_options<'a, const FORMAT: u128>(
self,
bytes: &'a mut [u8],
options: &Self::Options,
) -> &'a mut [u8] ⓘ
fn to_lexical_with_options<'a, const FORMAT: u128>( self, bytes: &'a mut [u8], options: &Self::Options, ) -> &'a mut [u8] ⓘ
Serializer for a number-to-string conversion.
Returns a subslice of the input buffer containing the written bytes,
starting from the same address in memory as the input slice. That
is, the bytes
provided to the function and the returned buffer
reference the same buffer, just with the number of elements truncated
to the written digits.
FORMAT
- Flags and characters designating the number grammar.value
- Number to serialize.bytes
- Buffer to write number to.options
- Options for number formatting.
FORMAT
should be built using NumberFormatBuilder
and includes
options such as the numerical radix for writing the value to string.
options
specificies extra, additional configurations such as
special values like NaN
or +Infinity
for how to serialize
the number.
§Examples
use core::str;
use lexical_core::{format, FormattedSize, WriteIntegerOptions, ToLexicalWithOptions};
const FORMAT: u128 = format::STANDARD;
const OPTIONS: WriteIntegerOptions = WriteIntegerOptions::new();
const BUFFER_SIZE: usize = OPTIONS.buffer_size_const::<u64, FORMAT>();
let value: u64 = 1234;
let mut buffer = [0u8; BUFFER_SIZE];
let digits = value.to_lexical_with_options::<FORMAT>(&mut buffer, &OPTIONS);
assert_eq!(str::from_utf8(digits), Ok("1234"));
§Panics
Panics if the buffer is not of sufficient size. The caller
must provide a slice of sufficient size. In order to ensure
the function will not panic, ensure the buffer has at least
Options::buffer_size_const
elements. This is required
only when changing the number of significant digits, the
exponent break point, or disabling scientific notation.
If you are not using min_significant_digits
(floats only),
1200 bytes is always enough to hold the the output for a custom
radix, and 400
is always enough for decimal strings.
Floats Only
These panics are only when using uncommon features for float writing, represent configuration errors, so runtime error handling is not provided.
Also panics if the provided number format is invalid, or if the mantissa radix is not equal to the exponent base and the mantissa radix/exponent base combinations are not in the following list:
4, 2
8, 2
16, 2
32, 2
16, 4
Panics as well if the
NaN or Inf
string provided to the writer
is disabled, but the value provided is NaN
or Inf
, respectively.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.