Crate lexical_core[−][src]

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 Rust slices.
// The argument is the byte string parsed.
let f = lexical_core::atof64(b"3.5").unwrap();   // 3.5
let i = lexical_core::atoi32(b"15").unwrap();    // 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 {
    // Get an FFI-compatible range.
    let bytes = b"3.5";
    let first = bytes.as_ptr();
    let last = first.add(bytes.len());
    // Get our result and extract our value using C-compatible functions.
    let res = lexical_core::ffi::atof64(first, last);
    let f = lexical_core::ffi::f64_result_ok(res); // Aborts if res is not ok.
}

// The ato* and ffi::ato* parsers are checked, they validate the
// input data is entirely correct, and stop parsing when invalid data
// is found, or upon numerical overflow.
let r = lexical_core::atoi8(b"256"); // Err(ErrorCode::Overflow.into())
let r = lexical_core::atoi8(b"1a5"); // Err(ErrorCode::InvalidDigit.into())

// In order to extract and parse a number from a substring of the input
// data, use the ato*_partial and ffi::ato*_partial parsers.
// These functions return the parsed value and the number of processed
// digits, allowing you to extract and parse the number in a single pass.
let r = lexical_core::atoi8(b"3a5"); // Ok((3, 1))

// Lexical-core includes FFI functions to properly extract data and handle
// errors during routines. All the following functions may be used in
// external libraries, include from C.

unsafe {
    unsafe fn to_range(bytes: &'static [u8]) -> (*const u8, *const u8) {
        let first = bytes.as_ptr();
        let last = first.add(bytes.len());
        (first, last)
    }

    // Ideally, everything works great.
    let (first, last) = to_range(b"15");
    let res = lexical_core::ffi::atoi8(first, last);
    if lexical_core::ffi::i8_result_is_ok(res) {
        let i = lexical_core::ffi::i8_result_ok(res);
        assert_eq!(i, 15);
    }

    // However, it detects numeric overflow, returning an error with
    // an error code equal to `ErrorCode::Overflow`.
    let (first, last) = to_range(b"256");
    let res = lexical_core::ffi::atoi8(first, last);
    if lexical_core::ffi::i8_result_is_err(res) {
        let err = lexical_core::ffi::i8_result_err(res);
        assert_eq!(err.code, lexical_core::ffi::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.
    let (first, last) = to_range(b"15 45");
    let res = lexical_core::ffi::atoi8(first, last);
    if lexical_core::ffi::i8_result_is_err(res) {
        let err = lexical_core::ffi::i8_result_err(res);
        assert_eq!(err.code, lexical_core::ffi::ErrorCode::InvalidDigit);
        assert_eq!(err.index, 2);
    }

    // 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(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(15, &mut buf);

// In order to guarantee the buffer is long enough, always ensure there
// are at least `MAX_*_SIZE`, where * 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(15.1, &mut buf);
assert_eq!(slc, b"15.1");

// When the `radix` feature is enabled, for base10 floats, using `MAX_*_SIZE`
// may significantly overestimate the space required to format the number.
// Therefore, the `MAX_*_SIZE_BASE10` constants allow you to get a much
// tighter bound on the space required.
let mut buf = [b'0'; lexical_core::MAX_F64_SIZE_BASE10];
let slc = lexical_core::f64toa(15.1, &mut buf);
assert_eq!(slc, b"15.1");

Modules

ffi	Foreign-function interface declarations.

Structs

Error

C-compatible error for FFI.

Enums

ErrorCode	Error code, indicating failure type.
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_F32_SIZE_BASE10	The minimum buffer size required to serialize an `f32` value in base 10.
MAX_F64_SIZE	The minimum buffer size required to serialize any `f64` value.
MAX_F64_SIZE_BASE10	The minimum buffer size required to serialize an `f64` value in base 10.
MAX_I8_SIZE	The minimum buffer size required to serialize any `i8` value.
MAX_I8_SIZE_BASE10	The minimum buffer size required to serialize an `i8` value in base 10.
MAX_I16_SIZE	The minimum buffer size required to serialize any `i16` value.
MAX_I16_SIZE_BASE10	The minimum buffer size required to serialize an `i16` value in base 10.
MAX_I32_SIZE	The minimum buffer size required to serialize any `i32` value.
MAX_I32_SIZE_BASE10	The minimum buffer size required to serialize an `i32` value in base 10.
MAX_I64_SIZE	The minimum buffer size required to serialize any `i64` value.
MAX_I64_SIZE_BASE10	The minimum buffer size required to serialize an `i64` value in base 10.
MAX_I128_SIZE	The minimum buffer size required to serialize any `i128` value.
MAX_I128_SIZE_BASE10	The minimum buffer size required to serialize an `i128` value in base 10.
MAX_ISIZE_SIZE	The minimum buffer size required to serialize any `isize` value.
MAX_ISIZE_SIZE_BASE10	The minimum buffer size required to serialize an `isize` value in base 10.
MAX_U8_SIZE	The minimum buffer size required to serialize any `u8` value.
MAX_U8_SIZE_BASE10	The minimum buffer size required to serialize an `u8` value in base 10.
MAX_U16_SIZE	The minimum buffer size required to serialize any `u16` value.
MAX_U16_SIZE_BASE10	The minimum buffer size required to serialize an `u16` value in base 10.
MAX_U32_SIZE	The minimum buffer size required to serialize any `u32` value.
MAX_U32_SIZE_BASE10	The minimum buffer size required to serialize an `u32` value in base 10.
MAX_U64_SIZE	The minimum buffer size required to serialize any `u64` value.
MAX_U64_SIZE_BASE10	The minimum buffer size required to serialize an `u64` value in base 10.
MAX_U128_SIZE	The minimum buffer size required to serialize any `u128` value.
MAX_U128_SIZE_BASE10	The minimum buffer size required to serialize an `u128` value in base 10.
MAX_USIZE_SIZE	The minimum buffer size required to serialize any `usize` value.
MAX_USIZE_SIZE_BASE10	The minimum buffer size required to serialize an `usize` value in base 10.

Statics

EXPONENT_DEFAULT_CHAR

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

Functions

atof32	Checked parser for a string-to-number conversion using Rust slices.
atof32_lossy	Checked parser for a string-to-number conversion using Rust slices.
atof32_partial	Checked parser for a string-to-number conversion using Rust slices.
atof32_partial_lossy	Checked parser for a string-to-number conversion using Rust slices.
atof64	Checked parser for a string-to-number conversion using Rust slices.
atof64_lossy	Checked parser for a string-to-number conversion using Rust slices.
atof64_partial	Checked parser for a string-to-number conversion using Rust slices.
atof64_partial_lossy	Checked parser for a string-to-number conversion using Rust slices.
atoi8	Checked parser for a string-to-number conversion using Rust slices.
atoi8_partial	Checked parser for a string-to-number conversion using Rust slices.
atoi16	Checked parser for a string-to-number conversion using Rust slices.
atoi16_partial	Checked parser for a string-to-number conversion using Rust slices.
atoi32	Checked parser for a string-to-number conversion using Rust slices.
atoi32_partial	Checked parser for a string-to-number conversion using Rust slices.
atoi64	Checked parser for a string-to-number conversion using Rust slices.
atoi64_partial	Checked parser for a string-to-number conversion using Rust slices.
atoi128	Checked parser for a string-to-number conversion using Rust slices.
atoi128_partial	Checked parser for a string-to-number conversion using Rust slices.
atoisize	Checked parser for a string-to-number conversion using Rust slices.
atoisize_partial	Checked parser for a string-to-number conversion using Rust slices.
atou8	Checked parser for a string-to-number conversion using Rust slices.
atou8_partial	Checked parser for a string-to-number conversion using Rust slices.
atou16	Checked parser for a string-to-number conversion using Rust slices.
atou16_partial	Checked parser for a string-to-number conversion using Rust slices.
atou32	Checked parser for a string-to-number conversion using Rust slices.
atou32_partial	Checked parser for a string-to-number conversion using Rust slices.
atou64	Checked parser for a string-to-number conversion using Rust slices.
atou64_partial	Checked parser for a string-to-number conversion using Rust slices.
atou128	Checked parser for a string-to-number conversion using Rust slices.
atou128_partial	Checked parser for a string-to-number conversion using Rust slices.
atousize	Checked parser for a string-to-number conversion using Rust slices.
atousize_partial	Checked parser for a string-to-number conversion using Rust slices.
f32toa	Serializer for a number-to-string conversion using Rust slices.
f64toa	Serializer for a number-to-string conversion using Rust slices.
get_inf_string	Get the short representation of an Infinity literal as a byte slice.
get_infinity_string	Get the long representation of an Infinity literal as a byte slice.
get_nan_string	Get string representation of Not a Number as a byte slice.
i8toa	Serializer for a number-to-string conversion using Rust slices.
i16toa	Serializer for a number-to-string conversion using Rust slices.
i32toa	Serializer for a number-to-string conversion using Rust slices.
i64toa	Serializer for a number-to-string conversion using Rust slices.
i128toa	Serializer for a number-to-string conversion using Rust slices.
isizetoa	Serializer for a number-to-string conversion using Rust slices.
set_inf_string ^⚠	Set the short representation of Infinity from a byte slice.
set_infinity_string ^⚠	Set the long representation of Infinity from a byte slice.
set_nan_string ^⚠	Set representation of Not a Number from a byte slice.
u8toa	Serializer for a number-to-string conversion using Rust slices.
u16toa	Serializer for a number-to-string conversion using Rust slices.
u32toa	Serializer for a number-to-string conversion using Rust slices.
u64toa	Serializer for a number-to-string conversion using Rust slices.
u128toa	Serializer for a number-to-string conversion using Rust slices.
usizetoa	Serializer for a number-to-string conversion using Rust slices.

Type Definitions

Result

Rust intrinsic result type from parsing strings-to-numbers for FFI.

Crate lexical_core⎘[−][src]

Crate lexical_core[−][src]