Crate lexical_core

Expand description

Fast lexical conversion routines with a C FFI for a no_std environment.

Getting Started

lexical-core is a low-level, partially FFI-compatible API for number-to-string and string-to-number conversions, without requiring a system allocator. If you would like to use a convenient, high-level API, please look at lexical instead.

Getting Started

extern crate lexical_core;

// String to number using slices
// The argument is the byte string parsed.
let f = lexical_core::atof64_slice(b"3.5");   // 3.5
let i = lexical_core::atoi32_slice(b"15");    // 15

// String to number using pointer ranges, for FFI-compatible code.
// The first argument is a pointer to the start of the parsed byte array,
// and the second argument is a pointer to 1-past-the-end. It will process
// bytes in the range [first, last).
unsafe {
    let bytes = b"3.5";
    let first = bytes.as_ptr();
    let last = first.add(bytes.len());
    let f = lexical_core::atof64_range(first, last);
}

// If and only if the `radix` feature is enabled, you may use the radix
// overloads to parse non-decimal floats and strings.
#[cfg(feature = "radix")]
let f = lexical_core::atof32_radix_slice(2, b"11.1");   // 3.5
#[cfg(feature = "radix")]
let i = lexical_core::atoi32_radix_slice(2, b"1111");   // 15

// The ato*_slice and ato*_range parsers are not checked, they do not
// validate that the input data is entirely correct, and discard trailing
// bytes that are found. The explicit behavior is to wrap on overflow, and
// to discard invalid digits.
let i = lexical_core::atoi8_slice(b"256");    // 0, wraps from 256
let i = lexical_core::atoi8_slice(b"1a5");    // 1, discards "a5"

// You should prefer the checked parsers, whenever possible. These detect
// numeric overflow, and no invalid trailing digits are present.
// The error code for success is 0, all errors are less than 0.

// Ideally, everything works great.
let res = lexical_core::try_atoi8_slice(b"15");
assert_eq!(res.error.code, lexical_core::ErrorCode::Success);
assert_eq!(res.value, 15);

// However, it detects numeric overflow, setting `res.error.code`
// to the appropriate value.
let res = lexical_core::try_atoi8_slice(b"256");
assert_eq!(res.error.code, lexical_core::ErrorCode::Overflow);

// Errors occurring prematurely terminating the parser due to invalid
// digits return the index in the buffer where the invalid digit was
// seen. This may useful in contexts like serde, which require numerical
// parsers from complex data without having to extract a substring
// containing only numeric data ahead of time. If the error is set
// to a `InvalidDigit`, the value is guaranteed to be accurate up until
// that point. For example, if the trailing data is whitespace,
// the value from an invalid digit may be perfectly valid in some contexts.
let res = lexical_core::try_atoi8_slice(b"15 45");
assert_eq!(res.error.code, lexical_core::ErrorCode::InvalidDigit);
assert_eq!(res.error.index, 2);
assert_eq!(res.value, 15);

// Number to string using slices.
// The first argument is the value, the second argument is the radix,
// and the third argument is the buffer to write to.
// The function returns a subslice of the original buffer, and will
// always start at the same position (`buf.as_ptr() == slc.as_ptr()`).
let mut buf = [b'0'; lexical_core::MAX_I64_SIZE];
let slc = lexical_core::i64toa_slice(15, &mut buf);
assert_eq!(slc, b"15");

// If an insufficiently long buffer is passed, the serializer will panic.
// PANICS
let mut buf = [b'0'; 1];
//let slc = lexical_core::i64toa_slice(15, &mut buf);

// In order to guarantee the buffer is long enough, always ensure there
// are at least `MAX_XX_SIZE`, where XX is the type name in upperase,
// IE, for `isize`, `MAX_ISIZE_SIZE`.
let mut buf = [b'0'; lexical_core::MAX_F64_SIZE];
let slc = lexical_core::f64toa_slice(15.1, &mut buf);
assert_eq!(slc, b"15.1");

Structs

Error

C-compatible error for FFI.

Result

C-compatible result type from parsing strings-to-numbers for FFI.

Enums

ErrorCode

Error code, indicating success or failure.

RoundingKind

Rounding type for float-parsing.

Constants

BUFFER_SIZE

The maximum number of bytes that any number-to-string function may write.

MAX_F32_SIZE

The minimum buffer size required to serialize any f32 value.

MAX_F64_SIZE

The minimum buffer size required to serialize any f64 value.

MAX_I8_SIZE

The minimum buffer size required to serialize any i8 value.

MAX_I16_SIZE

The minimum buffer size required to serialize any i16 value.

MAX_I32_SIZE

The minimum buffer size required to serialize any i32 value.

MAX_I64_SIZE

The minimum buffer size required to serialize any i64 value.

MAX_I128_SIZE

The minimum buffer size required to serialize any i128 value.

MAX_ISIZE_SIZE

The minimum buffer size required to serialize any isize value.

MAX_U8_SIZE

The minimum buffer size required to serialize any u8 value.

MAX_U16_SIZE

The minimum buffer size required to serialize any u16 value.

MAX_U32_SIZE

The minimum buffer size required to serialize any u32 value.

MAX_U64_SIZE

The minimum buffer size required to serialize any u64 value.

MAX_U128_SIZE

The minimum buffer size required to serialize any u128 value.

MAX_USIZE_SIZE

The minimum buffer size required to serialize any usize value.

Statics

BUFFER_SIZE_FFI

Symbol-generating constant for the maximum number of bytes that any number-to-string function may write.

EXPONENT_DEFAULT_CHAR

Default character for scientific notation, used when the radix < 15.

FLOAT_ROUNDING

The rounding scheme for float conversions.

INFINITY_STRING

Long infinity literal

INF_STRING

Short infinity literal

MAX_F32_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any f32 value.

MAX_F64_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any f64 value.

MAX_I8_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any i8 value.

MAX_I16_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any i16 value.

MAX_I32_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any i32 value.

MAX_I64_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any i64 value.

MAX_I128_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any i128 value.

MAX_ISIZE_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any isize value.

MAX_U8_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any u8 value.

MAX_U16_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any u16 value.

MAX_U32_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any u32 value.

MAX_U64_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any u64 value.

MAX_U128_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any u128 value.

MAX_USIZE_SIZE_FFI

Symbol-generating constant for the minimum buffer required to serialize any usize value.

NAN_STRING

Not a Number literal

Functions

atof32_lossy_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atof32_lossy_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atof32_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atof32_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atof64_lossy_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atof64_lossy_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atof64_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atof64_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atoi8_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atoi8_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atoi16_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atoi16_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atoi32_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atoi32_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atoi64_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atoi64_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atoi128_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atoi128_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atoisize_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atoisize_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atou8_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atou8_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atou16_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atou16_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atou32_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atou32_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atou64_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atou64_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atou128_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atou128_slice

Unchecked parser for a string-to-number conversion using Rust slices.

atousize_range^⚠

Unchecked parser for a string-to-number conversion using pointer ranges.

atousize_slice

Unchecked parser for a string-to-number conversion using Rust slices.

f32toa_range^⚠

Serializer for a number-to-string conversion using pointer ranges.

f32toa_slice

Serializer for a number-to-string conversion using Rust slices.

f64toa_range^⚠

Serializer for a number-to-string conversion using pointer ranges.

f64toa_slice

Serializer for a number-to-string conversion using Rust slices.

get_inf_string^⚠

Get INF_STRING as a pointer and size.

get_infinity_string^⚠

Get INFINITY_STRING as a pointer and size.

get_nan_string^⚠

Get NAN_STRING as a pointer and size.

i8toa_range^⚠

Serializer for a number-to-string conversion using pointer ranges.

i8toa_slice

Serializer for a number-to-string conversion using Rust slices.

i16toa_range^⚠

Serializer for a number-to-string conversion using pointer ranges.

i16toa_slice

Serializer for a number-to-string conversion using Rust slices.

i32toa_range^⚠

Serializer for a number-to-string conversion using pointer ranges.

i32toa_slice

Serializer for a number-to-string conversion using Rust slices.

i64toa_range^⚠

Serializer for a number-to-string conversion using pointer ranges.

i64toa_slice

Serializer for a number-to-string conversion using Rust slices.

i128toa_range^⚠

Serializer for a number-to-string conversion using pointer ranges.

i128toa_slice

Serializer for a number-to-string conversion using Rust slices.

is_empty

Check if the error code designates an empty byte array was encountered.

is_invalid_digit

Check if the error code designates an invalid digit was encountered.

is_overflow

Check if the error code designates integer overflow.

is_success

Check if the error code is successful.

isizetoa_range^⚠

Serializer for a number-to-string conversion using pointer ranges.

isizetoa_slice

Serializer for a number-to-string conversion using Rust slices.

set_inf_string^⚠

Set INF_STRING from a pointer and size.

set_infinity_string^⚠

Set INFINITY_STRING from a pointer and size.

set_nan_string^⚠

Set NAN_STRING from a pointer and size.

try_atof32_lossy_range^⚠