| 1 |
minimal-lexical |
| 2 |
=============== |
| 3 |
|
| 4 |
This is a minimal version of [rust-lexical](https://github.com/Alexhuszagh/rust-lexical), meant to allow efficient round-trip float parsing. minimal-lexical implements a correct, fast float parser. |
| 5 |
|
| 6 |
Due to the small, stable nature of minimal-lexical, it is also well-adapted to private forks. If you do privately fork minimal-lexical, I recommend you contact me via [email](mailto:[email protected]) or [Twitter](https://twitter.com/KardOnIce), so I can notify you of feature updates, bug fixes, or security vulnerabilities, as well as help you implement custom feature requests. I will not use your information for any other purpose, including, but not limited to disclosing your project or organization's use of minimal-lexical. |
| 7 |
|
| 8 |
minimal-lexical is designed for fast compile times and small binaries sizes, at the expense of a minor amount of performance. For improved performance, feel free to fork minimal-lexical with more aggressive inlining. |
| 9 |
|
| 10 |
**Similar Projects** |
| 11 |
|
| 12 |
For a high-level, all-in-one number conversion routines, see [rust-lexical](https://github.com/Alexhuszagh/rust-lexical). |
| 13 |
|
| 14 |
**Table Of Contents** |
| 15 |
|
| 16 |
- [Getting Started](#getting-started) |
| 17 |
- [Recipes](#recipes) |
| 18 |
- [Algorithms](#algorithms) |
| 19 |
- [Platform Support](platform-support) |
| 20 |
- [Minimum Version Support](minimum-version-support) |
| 21 |
- [Changelog](#changelog) |
| 22 |
- [License](#license) |
| 23 |
- [Contributing](#contributing) |
| 24 |
|
| 25 |
# Getting Started |
| 26 |
|
| 27 |
First, add the following to your `Cargo.toml`. |
| 28 |
|
| 29 |
```toml |
| 30 |
[dependencies] |
| 31 |
minimal-lexical = "0.2" |
| 32 |
``` |
| 33 |
|
| 34 |
Next, to parse a simple float, use the following: |
| 35 |
|
| 36 |
```rust |
| 37 |
extern crate minimal_lexical; |
| 38 |
|
| 39 |
// Let's say we want to parse "1.2345". |
| 40 |
// First, we need an external parser to extract the integer digits ("1"), |
| 41 |
// the fraction digits ("2345"), and then parse the exponent to a 32-bit |
| 42 |
// integer (0). |
| 43 |
// Warning: |
| 44 |
// -------- |
| 45 |
// Please note that leading zeros must be trimmed from the integer, |
| 46 |
// and trailing zeros must be trimmed from the fraction. This cannot |
| 47 |
// be handled by minimal-lexical, since we accept iterators |
| 48 |
let integer = b"1"; |
| 49 |
let fraction = b"2345"; |
| 50 |
let float: f64 = minimal_lexical::parse_float(integer.iter(), fraction.iter(), 0); |
| 51 |
println!("float={:?}", float); // 1.235 |
| 52 |
``` |
| 53 |
|
| 54 |
# Recipes |
| 55 |
|
| 56 |
You may be asking: where is the actual parser? Due to variation in float formats, and the goal of integrating utility for various data-interchange language parsers, such functionality would be beyond the scope of this library. |
| 57 |
|
| 58 |
For example, the following float is valid in Rust strings, but is invalid in JSON or TOML: |
| 59 |
```json |
| 60 |
1.e7 |
| 61 |
``` |
| 62 |
|
| 63 |
Therefore, to use the library, you need functionality that extracts the significant digits to pass to `create_float`. Please see [simple-example](https://github.com/Alexhuszagh/minimal-lexical/blob/master/examples/simple.rs) for a simple, annotated example on how to use minimal-lexical as a parser. |
| 64 |
|
| 65 |
# Algorithms |
| 66 |
|
| 67 |
For an in-depth explanation on the algorithms minimal-lexical uses, please see [lexical-core#string-to-float](https://github.com/Alexhuszagh/rust-lexical/tree/master/lexical-core#string-to-float). |
| 68 |
|
| 69 |
# Platform Support |
| 70 |
|
| 71 |
minimal-lexical is tested on a wide variety of platforms, including big and small-endian systems, to ensure portable code. Supported architectures include: |
| 72 |
- x86_64 Linux, Windows, macOS, Android, iOS, FreeBSD, and NetBSD. |
| 73 |
- x86 Linux, macOS, Android, iOS, and FreeBSD. |
| 74 |
- aarch64 (ARM8v8-A) Linux, Android, and iOS. |
| 75 |
- armv7 (ARMv7-A) Linux, Android, and iOS. |
| 76 |
- arm (ARMv6) Linux, and Android. |
| 77 |
- mips (MIPS) Linux. |
| 78 |
- mipsel (MIPS LE) Linux. |
| 79 |
- mips64 (MIPS64 BE) Linux. |
| 80 |
- mips64el (MIPS64 LE) Linux. |
| 81 |
- powerpc (PowerPC) Linux. |
| 82 |
- powerpc64 (PPC64) Linux. |
| 83 |
- powerpc64le (PPC64LE) Linux. |
| 84 |
- s390x (IBM Z) Linux. |
| 85 |
|
| 86 |
minimal-lexical should also work on a wide variety of other architectures and ISAs. If you have any issue compiling minimal-lexical on any architecture, please file a bug report. |
| 87 |
|
| 88 |
# Minimum Version Support |
| 89 |
|
| 90 |
Minimal-lexical is tested to support Rustc 1.36+, including stable, beta, and nightly. Please report any errors compiling a supported lexical version on a compatible Rustc version. Please note we may increment the MSRV for compiler versions older than 18 months, to support at least the current Debian stable version, without breaking changes. |
| 91 |
|
| 92 |
# Changelog |
| 93 |
|
| 94 |
All changes are documented in [CHANGELOG](CHANGELOG). |
| 95 |
|
| 96 |
# License |
| 97 |
|
| 98 |
Minimal-lexical is dual licensed under the Apache 2.0 license as well as the MIT license. See the [LICENSE.md](LICENSE.md) file for full license details. |
| 99 |
|
| 100 |
# Contributing |
| 101 |
|
| 102 |
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in minimal-lexical by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. |