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 |
MAX_F32_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_F64_SIZE | The minimum buffer size required to serialize any |
MAX_F64_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_I8_SIZE | The minimum buffer size required to serialize any |
MAX_I8_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_I16_SIZE | The minimum buffer size required to serialize any |
MAX_I16_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_I32_SIZE | The minimum buffer size required to serialize any |
MAX_I32_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_I64_SIZE | The minimum buffer size required to serialize any |
MAX_I64_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_I128_SIZE | The minimum buffer size required to serialize any |
MAX_I128_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_ISIZE_SIZE | The minimum buffer size required to serialize any |
MAX_ISIZE_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_U8_SIZE | The minimum buffer size required to serialize any |
MAX_U8_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_U16_SIZE | The minimum buffer size required to serialize any |
MAX_U16_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_U32_SIZE | The minimum buffer size required to serialize any |
MAX_U32_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_U64_SIZE | The minimum buffer size required to serialize any |
MAX_U64_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_U128_SIZE | The minimum buffer size required to serialize any |
MAX_U128_SIZE_BASE10 | The minimum buffer size required to serialize an |
MAX_USIZE_SIZE | The minimum buffer size required to serialize any |
MAX_USIZE_SIZE_BASE10 | The minimum buffer size required to serialize an |
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. |