Struct NumberFormatBuilder

Source

pub struct NumberFormatBuilder { /* private fields */ }

Expand description

Validating builder for NumberFormat from the provided specifications.

Some of the core functionality includes support for:

Digit separators: ignored characters used to make numbers more readable, such as 100,000.
Non-decimal radixes: writing or parsing numbers written in binary, hexadecimal, or other bases.
Special numbers: disabling support for special floating-point, such as NaN.
Number components: require signs, significant digits, and more.

Returns NumberFormat on calling build_strict if it was able to compile the format, otherwise, returns None.

§Examples

To create a format valid for Rust number literals, we can use the builder API:

use core::num;

use lexical_util::{NumberFormat, NumberFormatBuilder};

// create the format for literal Rust floats
const RUST: u128 = NumberFormatBuilder::new()
   .digit_separator(num::NonZeroU8::new(b'_'))
   .required_digits(true)
   .no_positive_mantissa_sign(true)
   .no_special(true)
   .internal_digit_separator(true)
   .trailing_digit_separator(true)
   .consecutive_digit_separator(true)
   .build_strict();

// then, access the formats's properties
let format = NumberFormat::<{ RUST }> {};
assert!(format.no_positive_mantissa_sign());
assert!(format.no_special());
assert!(format.internal_digit_separator());
assert!(format.trailing_digit_separator());
assert!(format.consecutive_digit_separator());
assert!(!format.no_exponent_notation());

§Fields

digit_separator: Character to separate digits.
mantissa_radix: Radix for mantissa digits.
exponent_base: Base for the exponent.
exponent_radix: Radix for the exponent digits.
base_prefix: Optional character for the base prefix.
base_suffix: Optional character for the base suffix.
required_integer_digits: If digits are required before the decimal point.
required_fraction_digits: If digits are required after the decimal point.
required_exponent_digits: If digits are required after the exponent character.
required_mantissa_digits: If at least 1 significant digit is required.
no_positive_mantissa_sign: If positive sign before the mantissa is not allowed.
required_mantissa_sign: If positive sign before the mantissa is required.
no_exponent_notation: If exponent notation is not allowed.
no_positive_exponent_sign: If positive sign before the exponent is not allowed.
required_exponent_sign: If sign before the exponent is required.
no_exponent_without_fraction: If exponent without fraction is not allowed.
no_special: If special (non-finite) values are not allowed.
case_sensitive_special: If special (non-finite) values are case-sensitive.
no_integer_leading_zeros: If leading zeros before an integer are not allowed.
no_float_leading_zeros: If leading zeros before a float are not allowed.
required_exponent_notation: If exponent notation is required.
case_sensitive_exponent: If exponent characters are case-sensitive.
case_sensitive_base_prefix: If base prefixes are case-sensitive.
case_sensitive_base_suffix: If base suffixes are case-sensitive.
integer_internal_digit_separator: If digit separators are allowed between integer digits.
fraction_internal_digit_separator: If digit separators are allowed between fraction digits.
exponent_internal_digit_separator: If digit separators are allowed between exponent digits.
integer_leading_digit_separator: If a digit separator is allowed before any integer digits.
fraction_leading_digit_separator: If a digit separator is allowed before any fraction digits.
exponent_leading_digit_separator: If a digit separator is allowed before any exponent digits.
integer_trailing_digit_separator: If a digit separator is allowed after any integer digits.
fraction_trailing_digit_separator: If a digit separator is allowed after any fraction digits.
exponent_trailing_digit_separator: If a digit separator is allowed after any exponent digits.
integer_consecutive_digit_separator: If multiple consecutive integer digit separators are allowed.
fraction_consecutive_digit_separator: If multiple consecutive fraction digit separators are allowed.
special_digit_separator: If any digit separators are allowed in special (non-finite) values.

§Write Integer Fields

No fields are used for writing integers.

§Parse Integer Fields

These fields are used for parsing integers:

digit_separator: Character to separate digits.
mantissa_radix: Radix for mantissa digits.
base_prefix: Optional character for the base prefix.
base_suffix: Optional character for the base suffix.
no_positive_mantissa_sign: If positive sign before the mantissa is not allowed.
required_mantissa_sign: If positive sign before the mantissa is required.
no_integer_leading_zeros: If leading zeros before an integer are not allowed.
integer_internal_digit_separator: If digit separators are allowed between integer digits.
integer_leading_digit_separator: If a digit separator is allowed before any integer digits.
integer_trailing_digit_separator: If a digit separator is allowed after any integer digits.
integer_consecutive_digit_separator: If multiple consecutive integer digit separators are allowed.

§Write Float Fields

These fields are used for writing floats:

mantissa_radix: Radix for mantissa digits.
exponent_base: Base for the exponent.
exponent_radix: Radix for the exponent digits.
no_positive_mantissa_sign: If positive sign before the mantissa is not allowed.
required_mantissa_sign: If positive sign before the mantissa is required.
no_exponent_notation: If exponent notation is not allowed.
no_positive_exponent_sign: If positive sign before the exponent is not allowed.
required_exponent_sign: If sign before the exponent is required.
required_exponent_notation: If exponent notation is required.

§Parse Float Fields

These fields are used for parsing floats:

digit_separator: Character to separate digits.
mantissa_radix: Radix for mantissa digits.
exponent_base: Base for the exponent.
exponent_radix: Radix for the exponent digits.
base_prefix: Optional character for the base prefix.
base_suffix: Optional character for the base suffix.
required_mantissa_digits: If at least 1 significant digit is required.
required_integer_digits: If digits are required before the decimal point.
required_fraction_digits: If digits are required after the decimal point.
required_exponent_digits: If digits are required after the exponent character.
no_positive_mantissa_sign: If positive sign before the mantissa is not allowed.
required_mantissa_sign: If positive sign before the mantissa is required.
no_exponent_notation: If exponent notation is not allowed.
no_positive_exponent_sign: If positive sign before the exponent is not allowed.
required_exponent_sign: If sign before the exponent is required.
no_exponent_without_fraction: If exponent without fraction is not allowed.
no_special: If special (non-finite) values are not allowed.
case_sensitive_special: If special (non-finite) values are case-sensitive.
no_integer_leading_zeros: If leading zeros before an integer are not allowed.
no_float_leading_zeros: If leading zeros before a float are not allowed.
required_exponent_notation: If exponent notation is required.
case_sensitive_exponent: If exponent characters are case-sensitive.
case_sensitive_base_prefix: If base prefixes are case-sensitive.
case_sensitive_base_suffix: If base suffixes are case-sensitive.
integer_internal_digit_separator: If digit separators are allowed between integer digits.
fraction_internal_digit_separator: If digit separators are allowed between fraction digits.
exponent_internal_digit_separator: If digit separators are allowed between exponent digits.
integer_leading_digit_separator: If a digit separator is allowed before any integer digits.
fraction_leading_digit_separator: If a digit separator is allowed before any fraction digits.
exponent_leading_digit_separator: If a digit separator is allowed before any exponent digits.
integer_trailing_digit_separator: If a digit separator is allowed after any integer digits.
fraction_trailing_digit_separator: If a digit separator is allowed after any fraction digits.
exponent_trailing_digit_separator: If a digit separator is allowed after any exponent digits.
integer_consecutive_digit_separator: If multiple consecutive integer digit separators are allowed.
fraction_consecutive_digit_separator: If multiple consecutive fraction digit separators are allowed.
special_digit_separator: If any digit separators are allowed in special (non-finite) values.

Implementations§

Source §

impl NumberFormatBuilder

Source

pub const fn new() -> NumberFormatBuilder

Create new NumberFormatBuilder with default arguments.

The default values are:

digit_separator - None
base_prefix - None
base_suffix - None
mantissa_radix - 10
exponent_base - None
exponent_radix - None
required_integer_digits - false
required_fraction_digits - false
required_exponent_digits - true
required_mantissa_digits - true
no_positive_mantissa_sign - false
required_mantissa_sign - false
no_exponent_notation - false
no_positive_exponent_sign - false
required_exponent_sign - false
no_exponent_without_fraction - false
no_special - false
case_sensitive_special - false
no_integer_leading_zeros - false
no_float_leading_zeros - false
required_exponent_notation - false
case_sensitive_exponent - false
case_sensitive_base_prefix - false
case_sensitive_base_suffix - false
integer_internal_digit_separator - false
fraction_internal_digit_separator - false
exponent_internal_digit_separator - false
integer_leading_digit_separator - false
fraction_leading_digit_separator - false
exponent_leading_digit_separator - false
integer_trailing_digit_separator - false
fraction_trailing_digit_separator - false
exponent_trailing_digit_separator - false
integer_consecutive_digit_separator - false
fraction_consecutive_digit_separator - false
exponent_consecutive_digit_separator - false
special_digit_separator - false

Source

pub const fn decimal() -> u128

Create number format for standard, decimal number.

Source

pub const fn get_digit_separator(&self) -> Option<NonZero<u8>>

Get the digit separator for the number format.

Digit separators are frequently used in number literals to group digits: 1,000,000 is a lot more readable than 1000000, but the , characters should be ignored in the parsing of the number.

Can only be modified with feature format. Defaults to None, or no digit separators allowed.

§Examples

Using a digit separator of _ (note that the validity oh where a digit separator can appear depends on the other digit separator flags).

Input	Valid?
`1`	✔️
`1_4`	✔️
`+_14`	✔️
`+14e3_5`	✔️
`1_d`	❌

§Used For

Parse Float
Parse Integer

Source

pub const fn get_mantissa_radix(&self) -> u8

Get the radix for mantissa digits.

This is only used for the significant digits, that is, the integral and fractional components. Can only be modified with feature power-of-two or radix. Defaults to 10.

Radix	String	Number
2	“10011010010”	1234
3	“1200201”	1234
8	“2322”	1234
10	“1234”	1234
16	“4d2”	1234
31	“18p”	1234

§Used For

Parse Float
Parse Integer
Write Float
Write Integer

Source

pub const fn get_exponent_base(&self) -> Option<NonZero<u8>>

Get the radix for the exponent.

For example, in 1.234e3, it means 1.234 * 10^3, and the exponent base here is 10. Some programming languages, like C, support hex floats with an exponent base of 2, for example 0x1.8p3, or 1.5 * 2^3. Defaults to 10. Can only be modified with feature power-of-two or radix. Defaults to 10.

§Used For

Parse Float
Parse Integer

Source

pub const fn get_exponent_radix(&self) -> Option<NonZero<u8>>

Get the radix for exponent digits.

This is only used for the exponent digits. We assume the radix for the significant digits (get_mantissa_radix) is 10 as is the exponent base. Defaults to 10. Can only be modified with feature power-of-two or radix. Defaults to 10.

Radix	String	Number
2	“1.234^1100”	1.234e9
3	“1.234^110”	1.234e9
8	“1.234^14”	1.234e9
10	“1.234^12”	1.234e9
16	“1.234^c”	1.234e9
31	“1.234^c”	1.234e9

§Used For

Parse Float
Parse Integer

Source

pub const fn get_base_prefix(&self) -> Option<NonZero<u8>>

Get the optional character for the base prefix.

This character will come after a leading zero, so for example setting the base prefix to x means that a leading 0x will be ignore, if present. Can only be modified with feature power-of-two or radix along with format. Defaults to None, or no base prefix allowed.

§Examples

Using a base prefix of x.

Input	Valid?
`0x1`	✔️
`x1`	❌
`1`	✔️
`1x`	❌
`1x1`	❌

§Used For

Parse Float
Parse Integer

Source

pub const fn get_base_suffix(&self) -> Option<NonZero<u8>>

Get the optional character for the base suffix.

This character will at the end of the buffer, so for example setting the base prefix to x means that a trailing x will be ignored, if present. Can only be modified with feature power-of-two or radix along with format. Defaults to None, or no base suffix allowed.

§Examples

Using a base suffix of x.

Input	Valid?
`1`	✔️
`1x`	✔️
`1d`	❌

§Used For

Parse Float
Parse Integer

Source

pub const fn get_required_integer_digits(&self) -> bool

Get if digits are required before the decimal point.

Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`1.1`	✔️
`0.1`	✔️
`1`	✔️
`.1`	❌

§Used For

Parse Float

Source

pub const fn get_required_fraction_digits(&self) -> bool

Get if digits are required after the decimal point, if the decimal point is present.

Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`1.1`	✔️
`1`	✔️
`1.`	❌

§Used For

Parse Float

Source

pub const fn get_required_exponent_digits(&self) -> bool

Get if digits are required after the exponent character, if the exponent is present.

Can only be modified with feature format. Defaults to true.

§Examples

Input	Valid?
`1.1e+3`	✔️
`1.1e3`	✔️
`1.1e+`	❌
`1.1e`	❌

§Used For

Parse Float

Source

pub const fn get_required_mantissa_digits(&self) -> bool

Get if at least 1 significant digit is required.

If not required, then values like . (0) are valid, but empty strings are still invalid. Can only be modified with feature format. Defaults to true.

§Examples

Input	Valid?
`1.1`	✔️
`.`	✔️
`e10`	✔️
`.e10`	✔️
	❌

§Used For

Parse Float

Source

pub const fn get_no_positive_mantissa_sign(&self) -> bool

Get if a positive sign before the mantissa is not allowed.

Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`1.1`	✔️
`-1.1`	✔️
`+1.1`	❌

§Used For

Parse Float
Parse Integer
Write Float

Source

pub const fn get_required_mantissa_sign(&self) -> bool

Get if a sign symbol before the mantissa is required.

Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`1.1`	❌
`-1.1`	✔️
`+1.1`	✔️

§Used For

Parse Float
Parse Integer
Write Float

Source

pub const fn get_no_exponent_notation(&self) -> bool

Get if exponent notation is not allowed.

Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`1`	✔️
`1.1`	✔️
`1.1e`	❌
`1.1e5`	❌

§Used For

Parse Float
Write Float

Source

pub const fn get_no_positive_exponent_sign(&self) -> bool

Get if a positive sign before the exponent is not allowed.

Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`1.1e3`	✔️
`1.1e-3`	✔️
`1.1e+3`	❌

§Used For

Parse Float
Write Float

Source

pub const fn get_required_exponent_sign(&self) -> bool

Get if a sign symbol before the exponent is required.

Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`1.1e3`	❌
`1.1e-3`	✔️
`1.1e+3`	✔️

§Used For

Parse Float
Write Float

Source

pub const fn get_no_exponent_without_fraction(&self) -> bool

Get if an exponent without fraction is not allowed.

Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`1e3`	❌
`1.e3`	❌
`1.1e`	✔️
`.1e3`	✔️

§Used For

Parse Float

Source

pub const fn get_no_special(&self) -> bool

Get if special (non-finite) values are not allowed.

Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`NaN`	❌
`inf`	❌
`-Infinity`	❌
`1.1e`	✔️

§Used For

Parse Float

Source

pub const fn get_case_sensitive_special(&self) -> bool

Get if special (non-finite) values are case-sensitive.

If set to true, then NaN and nan are treated as the same value (Not a Number). Can only be modified with feature format. Defaults to false.

§Used For

Parse Float

Source

pub const fn get_no_integer_leading_zeros(&self) -> bool

Get if leading zeros before an integer are not allowed.

Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`01`	❌
`0`	✔️
`10`	✔️

§Used For

Parse Integer

Source

pub const fn get_no_float_leading_zeros(&self) -> bool

Get if leading zeros before a float are not allowed.

This is before the significant digits of the float, that is, if there is 1 or more digits in the integral component and the leading digit is 0, Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`01`	❌
`01.0`	❌
`0`	✔️
`10`	✔️
`0.1`	✔️

§Used For

Parse Float

Source

pub const fn get_required_exponent_notation(&self) -> bool

Get if exponent notation is required.

Can only be modified with feature format. Defaults to false.

§Examples

Input	Valid?
`1`	❌
`1.0`	❌
`1e3`	✔️
`1.1e3`	✔️

§Used For

Parse Float
Write Float

Source

pub const fn get_case_sensitive_exponent(&self) -> bool

Get if exponent characters are case-sensitive.

If set to true, then the exponent character e would be considered the different from E. Can only be modified with feature format. Defaults to false.

§Used For

Parse Float

Source

pub const fn get_case_sensitive_base_prefix(&self) -> bool

Get if base prefixes are case-sensitive.

If set to true, then the base prefix x would be considered the different from X. Can only be modified with feature power-of-two or radix along with format. Defaults to false.

§Used For

Parse Float
Parse Integer

Source

pub const fn get_case_sensitive_base_suffix(&self) -> bool

Get if base suffixes are case-sensitive.

If set to true, then the base suffix x would be considered the different from X. Can only be modified with feature power-of-two or radix along with format. Defaults to false.

§Used For

Parse Float
Parse Integer

Source

pub const fn get_integer_internal_digit_separator(&self) -> bool

Get if digit separators are allowed between integer digits.

This will not consider an input of only the digit separator to be a valid separator: the digit separator must be surrounded by digits. Can only be modified with feature format. Defaults to false.

§Examples

Using a digit separator of _.

Input	Valid?
`1`	✔️
`_`	❌
`1_1`	✔️
`1_`	❌
`_1`	❌

§Used For

Parse Float
Parse Integer

Source

pub const fn get_fraction_internal_digit_separator(&self) -> bool

Get if digit separators are allowed between fraction digits.

This will not consider an input of only the digit separator to be a valid separator: the digit separator must be surrounded by digits. Can only be modified with feature format. Defaults to false.

§Examples

Using a digit separator of _.

Input	Valid?
`1.1`	✔️
`1._`	❌
`1.1_1`	✔️
`1.1_`	❌
`1._1`	❌

§Used For

Parse Float

Source

pub const fn get_exponent_internal_digit_separator(&self) -> bool

Get if digit separators are allowed between exponent digits.

This will not consider an input of only the digit separator to be a valid separator: the digit separator must be surrounded by digits. Can only be modified with feature format. Defaults to false.

§Examples

Using a digit separator of _.

Input	Valid?
`1.1e1`	✔️
`1.1e_`	❌
`1.1e1_1`	✔️
`1.1e1_`	❌
`1.1e_1`	❌

§Used For

Parse Float

Source

pub const fn get_integer_leading_digit_separator(&self) -> bool

Get if a digit separator is allowed before any integer digits.

This will consider an input of only the digit separator to be a identical to empty input. Can only be modified with feature format. Defaults to false.

§Examples

Using a digit separator of _.

Input	Valid?
`1`	✔️
`_`	❌
`1_1`	❌
`1_`	❌
`_1`	✔️

§Used For

Parse Float
Parse Integer

Source

pub const fn get_fraction_leading_digit_separator(&self) -> bool

Get if a digit separator is allowed before any fraction digits.

This will consider an input of only the digit separator to be a identical to empty input. Can only be modified with feature format. Defaults to false.

§Examples

Using a digit separator of _.

Input	Valid?
`1.1`	✔️
`1._`	❌
`1.1_1`	❌
`1.1_`	❌
`1._1`	✔️

§Used For

Parse Float

Source

pub const fn get_exponent_leading_digit_separator(&self) -> bool

Get if a digit separator is allowed before any exponent digits.

This will consider an input of only the digit separator to be a identical to empty input. Can only be modified with feature format. Defaults to false.

§Examples

Using a digit separator of _.

Input	Valid?
`1.1e1`	✔️
`1.1e_`	❌
`1.1e1_1`	❌
`1.1e1_`	❌
`1.1e_1`	✔️

§Used For

Parse Float

Source

pub const fn get_integer_trailing_digit_separator(&self) -> bool

Get if a digit separator is allowed after any integer digits.

This will consider an input of only the digit separator to be a identical to empty input. Can only be modified with feature format. Defaults to false.

§Examples

Using a digit separator of _.

Input	Valid?
`1`	✔️
`_`	❌
`1_1`	❌
`1_`	✔️
`_1`	❌

§Used For

Parse Float
Parse Integer

Source

pub const fn get_fraction_trailing_digit_separator(&self) -> bool

Get if a digit separator is allowed after any fraction digits.

This will consider an input of only the digit separator to be a identical to empty input. Can only be modified with feature format. Defaults to false. # Examples

Using a digit separator of _.

Input	Valid?
`1.1`	✔️
`1._`	❌
`1.1_1`	❌
`1.1_`	✔️
`1._1`	❌

§Used For

Parse Float

Source

pub const fn get_exponent_trailing_digit_separator(&self) -> bool

Get if a digit separator is allowed after any exponent digits.

This will consider an input of only the digit separator to be a identical to empty input. Can only be modified with feature format. Defaults to false.

§Examples

Using a digit separator of _.

Input	Valid?
`1.1e1`	✔️
`1.1e_`	❌
`1.1e1_1`	❌
`1.1e1_`	✔️
`1.1e_1`	❌

§Used For

Parse Float

Source

pub const fn get_integer_consecutive_digit_separator(&self) -> bool

Get if multiple consecutive integer digit separators are allowed.

That is, using _ as a digit separator __ would be allowed where any digit separators (leading, trailing, internal) are allowed in the integer. Can only be modified with feature format. Defaults to false.

§Used For

Parse Float
Parse Integer

Source

pub const fn get_fraction_consecutive_digit_separator(&self) -> bool

Get if multiple consecutive fraction digit separators are allowed.

That is, using _ as a digit separator __ would be allowed where any digit separators (leading, trailing, internal) are allowed in the fraction. Can only be modified with feature format. Defaults to false.

§Used For

Parse Float

Source

pub const fn get_exponent_consecutive_digit_separator(&self) -> bool

Get if multiple consecutive exponent digit separators are allowed.

That is, using _ as a digit separator __ would be allowed where any digit separators (leading, trailing, internal) are allowed in the exponent. Can only be modified with feature format. Defaults to false.

§Used For

Parse Float

Source

pub const fn get_special_digit_separator(&self) -> bool

Get if any digit separators are allowed in special (non-finite) values.

This enables leading, trailing, internal, and consecutive digit separators for any special floats: for example, N__a_N_ is considered the same as NaN. Can only be modified with feature format. Defaults to false.

§Used For

Parse Float

Source

pub const fn build_unchecked(&self) -> u128

Create 128-bit, packed number format struct from builder options.

This function will never fail. It is up to the caller to ensure the format is valid using NumberFormat::is_valid.

Source

pub const fn build_strict(&self) -> u128

Build the packed number format, panicking if the builder is invalid.

§Panics

If the built format is not valid. This should always be used within a const context to avoid panics at runtime.

Source

pub const fn build(&self) -> u128

👎Deprecated: Use build_strict or build_unchecked instead.

Create 128-bit, packed number format struct from builder options.

This function will never fail. It is up to the caller to ensure the format is valid using NumberFormat::is_valid. This function is soft-deprecated and you should prefer build_unchecked and handle if the result is invalid instead, or use build_strict to panic on any errors. This exists when compatibility with older Rust versions was required.

Source