1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243
//! 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](https://crates.io/crates/lexical) instead. //! //! # Getting Started //! //! ```rust //! 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"); //! ``` // FEATURES // Require intrinsics in a no_std context. #![cfg_attr(not(feature = "std"), no_std)] #![cfg_attr(all(not(feature = "std"), feature = "correct", feature = "radix"), feature(alloc))] #![cfg_attr(not(feature = "std"), feature(core_intrinsics))] #![cfg_attr(all(not(test), not(feature = "std")), feature(lang_items))] // DEPENDENCIES #[macro_use] extern crate cfg_if; #[cfg(feature = "correct")] #[allow(unused_imports)] // Not used before 1.26. #[macro_use] extern crate static_assertions; // Testing assertions for floating-point equality. #[cfg(test)] #[macro_use] extern crate approx; // Test against randomly-generated data. #[cfg(all(test, feature = "property_tests"))] #[macro_use] extern crate quickcheck; // Test against randomly-generated guided data. #[cfg(all(test, feature = "std", feature = "property_tests"))] #[macro_use] extern crate proptest; // Use vec if there is a system allocator, which we require only if // we're using the correct and radix features. #[cfg(all(not(feature = "std"), feature = "correct", feature = "radix"))] #[cfg_attr(test, macro_use)] extern crate alloc; // Use stackvector for atof. #[cfg(feature = "correct")] #[macro_use] extern crate stackvector; // Ensure only one back-end is enabled. #[cfg(all(feature = "grisu3", feature = "ryu"))] compile_error!("Lexical only accepts one of the following backends: `grisu3` or `ryu`."); // Import the back-end, if applicable. cfg_if! { if #[cfg(feature = "grisu3")] { extern crate dtoa; } else if #[cfg(feature = "ryu")] { extern crate ryu; }} // cfg_if /// Facade around the core features for name mangling. pub(crate) mod lib { #[cfg(feature = "std")] pub(crate) use std::*; #[cfg(not(feature = "std"))] pub(crate) use core::*; cfg_if! { if #[cfg(all(feature = "correct", feature = "radix"))] { #[cfg(feature = "std")] pub(crate) use std::vec::Vec; #[cfg(not(feature = "std"))] pub(crate) use alloc::vec::Vec; }} // cfg_if } // lib // PANIC // Need to define a panic handler when we're not testing (panic handler // then becomes "unwind" but there is no_std). This causes us to fail // with doctests, so ensure `--tests` is passed to `cargo test` whenever // we are in a `no_std` context. cfg_if! { if #[cfg(all(not(test), not(feature = "std")))] { use lib::intrinsics; use lib::panic::PanicInfo; #[panic_handler] fn panic(_: &PanicInfo) -> ! { unsafe { intrinsics::abort(); } } #[lang = "eh_personality"] extern fn eh_personality() {} }} // cfg_if // API // Hide implementation details #[macro_use] mod util; mod atof; mod atoi; mod float; mod ftoa; mod itoa; // Publicly expose the FFI module for documentation purposes. pub mod ffi; // Publicly re-export the low-level string-to-float functions. pub use atof::*; // Publicly re-export the low-level string-to-integer functions. pub use atoi::*; // Publicly re-export the low-level float-to-string functions. pub use ftoa::*; // Publicly re-export the low-level integer-to-string functions. pub use itoa::*; // Re-export configuration and utilities globally. pub use util::*;