lexical

为在 no_std 环境中使用而提供的性能优异的数值转换例程。这不依赖于任何标准库功能，也不依赖于系统分配器。

类似项目

如果您想要 lexical 的浮点数解析算法的最小化、稳定和编译时友好版本，请参阅 minimal-lexical。如果您需要最小化、高效的浮点数解析器，Rust 标准库的最新版本应该 足够使用。

目录

• 入门
• 部分/完整解析器
• no_std
• 功能
• 定制
  • 数字格式 API
  • 选项 API
• 文档
• 验证
• 度量
• 安全性
• 平台支持
• 版本和版本支持
• 变更日志
• 许可
• 贡献

入门

将 lexical 添加到您的 Cargo.toml

[dependencies]
lexical = "^6.0"

并开始使用 lexical

// Number to string
use lexical_core::BUFFER_SIZE;
let mut buffer = [b'0'; BUFFER_SIZE];
lexical_core::write(3.0, &mut buffer);   // "3.0", always has a fraction suffix,
lexical_core::write(3, &mut buffer);     // "3"

// String to number.
let i: i32 = lexical_core::parse("3")?;      // Ok(3), auto-type deduction.
let f: f32 = lexical_core::parse("3.5")?;    // Ok(3.5)
let d: f64 = lexical_core::parse("3.5")?;    // Ok(3.5), error checking parse.
let d: f64 = lexical_core::parse("3a")?;     // Err(Error(_)), failed to parse.

为了在泛型代码中使用 lexical，提供了 FromLexical （用于 parse）和 ToLexical （用于 to_string）的特例约束。

/// Multiply a value in a string by multiplier, and serialize to string.
fn mul_2<T>(value: &str, multiplier: T)
    -> Result<String, lexical_core::Error>
where 
    T: lexical_core::ToLexical + lexical_core::FromLexical,
{
    let value: T = lexical_core::parse(value.as_bytes())?;
    let mut buffer = [b'0'; lexical_core::BUFFER_SIZE];
    let bytes = lexical_core::write(value * multiplier, &mut buffer);
    Ok(std::str::from_utf8(bytes).unwrap())
}

部分/完整解析器

Lexical 同时具有部分和完整解析器：完整解析器确保在解析过程中使用整个缓冲区，而不会忽略尾随字符，部分解析器解析尽可能多的字符，并返回解析值和解析的数字数量。在遇到错误时，lexical 将返回一个错误，指示错误类型和错误在缓冲区内的索引。

完整解析器

// This will return Err(Error::InvalidDigit(3)), indicating
// the first invalid character occurred at the index 3 in the input
// string (the space character).
let x: i32 = lexical_core::parse(b"123 456")?;

部分解析器

// This will return Ok((123, 3)), indicating that 3 digits were successfully
// parsed, and that the returned value is `123`.
let (x, count): (i32, usize) = lexical_core::parse_partial(b"123 456")?;

no_std

lexical-core 不依赖于标准库，也不依赖于系统分配器。要在 no_std 环境中使用 lexical-core，请将以下内容添加到 Cargo.toml

[dependencies.lexical-core]
version = "0.8.5"
default-features = false
# Can select only desired parsing/writing features.
features = ["write-integers", "write-floats", "parse-integers", "parse-floats"]

并开始使用 lexical

// A constant for the maximum number of bytes a formatter will write.
use lexical_core::BUFFER_SIZE;
let mut buffer = [b'0'; BUFFER_SIZE];

// Number to string. The underlying buffer must be a slice of bytes.
let count = lexical_core::write(3.0, &mut buffer);
assert_eq!(buffer[..count], b"3.0");
let count = lexical_core::write(3i32, &mut buffer);
assert_eq!(buffer[..count], b"3");

// String to number. The input must be a slice of bytes.
let i: i32 = lexical_core::parse(b"3")?;      // Ok(3), auto-type deduction.
let f: f32 = lexical_core::parse(b"3.5")?;    // Ok(3.5)
let d: f64 = lexical_core::parse(b"3.5")?;    // Ok(3.5), error checking parse.
let d: f64 = lexical_core::parse(b"3a")?;     // Err(Error(_)), failed to parse.

功能

Lexical 为每个数值转换例程启用功能门，如果某些数值转换，则编译时间更快。这些功能可以针对 lexical-core（不需要系统分配器）和 lexical 启用/禁用。默认情况下，所有转换都启用。

• parse-floats：启用字符串到浮点数的转换。
• parse-integers：启用字符串到整数的转换。
• write-floats：启用浮点数到字符串的转换。
• write-integers: 打开整数到字符串的转换。

Lexical具有高度的可定制性，并包含许多其他可选功能。

• std: 打开使用Rust标准库（默认启用）。
• power-of-two: 打开到非十进制字符串以及从非十进制字符串的转换。

  启用power_of_two后，基数{2, 4, 8, 10, 16, 和 32}是有效的，否则，只有10是有效的。这允许常见的从十进制到十六进制整数/浮点数以及从十六进制整数/浮点数到十进制的转换，无需为其他基数准备大的预计算表。

• radix: 允许到非十进制字符串以及从非十进制字符串的转换。

  启用基数后，2到36（含）的任何基数都有效，否则，只有10有效。

• format: 定制数字解析和写入时接受的数字格式。

  启用格式后，数字格式由打包进一个u128的位标志和掩码决定。这些决定了解析和写入的数字的有效语法，包括启用数字分隔符、要求整数或小数位数以及切换大小写敏感的指数字符。

• compact: 以性能为代价优化二进制大小。

  这最小化了预计算表的使用，产生了显著更小的二进制文件。

• safe: 要求所有数组索引进行边界检查。

  对于数字解析器来说，这实际上是无效操作，因为它们除了可以轻易证明无需边界检查的索引是正确的之外，都使用安全的索引。数字写入器频繁使用不安全的索引，因为我们很容易高估输出中的数字数量，因为输入是固定长度的。

• f16: 添加对16位浮点数的数值转换支持。

  添加了f16，一个半精度IEEE-754浮点类型，以及bf16，Brain Float 16类型，并提供了这些浮点数到和从这些浮点数的数值转换。注意，由于这些是存储格式，因此没有本地算术运算，所有转换都使用一个中间的f32。

为确保在禁用边界检查时的安全性，我们广泛地对所有数值转换例程进行了模糊测试。有关更多信息，请参阅下面的安全性部分。

Lexical还非常重视代码膨胀：既有优化性能的算法，也有优化大小的算法。默认情况下，这侧重于性能，但是，使用compact功能，您也可以选择以性能为代价减少代码大小。紧凑算法以性能为代价最小化了预计算表和其他优化的使用。

定制

⚠ 警告：如果更改写入的有效数字位数、禁用指数记法或更改指数记法阈值，BUFFER_SIZE可能不足以容纳结果输出。WriteOptions::buffer_size将提供写入的字节数的正确上限。如果提供了不足长度的缓冲区，lexical-core将恐慌。

每种语言都有有效的数值输入的竞争性规范，这意味着Rust的数值解析器将错误地接受或拒绝不同编程或数据语言的输入。例如

// Valid in Rust strings.
// Not valid in JSON.
let f: f64 = lexical_core::parse(b"3.e7")?;  // 3e7

// Let's only accept JSON floats.
const JSON: u128 = lexical_core::format::JSON;
let options = ParseFloatOptions::new();
let f: f64 = lexical_core::parse_with_options::<JSON>(b"3.0e7", &options)?; // 3e7
let f: f64 = lexical_core::parse_with_options::<JSON>(b"3.e7", &options)?;  // Errors!

由于不同编程和数据语言中数值语法的极高可变性，我们提供了2个不同的API来简化具有不同语法要求的数值转换。

• 数字格式API（通过 format 或 power-of-two 功能开启）。

  这是一个包含指定数字解析或写入编译时语法的标志的打包结构体。这包括诸如数字字符串的基数、数字分隔符、大小写敏感的指数字符、可选的基数前缀/后缀等特性。

• 选项API。

  这包含了解析和写入数字的运行时规则。这包括指数断点、舍入模式、指数和十进制点字符，以及NaN和Infinity的字符串表示。

以下列出了功能的一个有限子集的文档，但完整的规范可以在API参考文档中找到。

数字格式 API

数字格式类提供了许多标志，用于在解析或写入时指定数字语法。当启用 power-of-two 功能时，会添加额外的标志

• 有效数字的基数（默认 10）。
• 指数基数的基数（默认 10）。
• 指数数字的基数（默认 10）。

当启用 format 功能时，还会启用许多其他语法和数字分隔符标志，包括

• 一个数字分隔符字符，用于将数字分组以提高可读性。
• 是否允许前导、尾随、内部和连续数字分隔符。
• 切换所需浮点组件，例如小数点前的数字。
• 切换是否允许特殊浮点数或它们是否大小写敏感。

因此存在许多预定义的常量来简化常见用例，包括

• JSON、XML、TOML、YAML、SQLite等。
• Rust、Python、C#、FORTRAN、COBOL字面量和字符串等。

以下是一个构建自定义数字格式的示例

const FORMAT: u128 = lexical_core::NumberFormatBuilder::new()
    // Disable exponent notation.
    .no_exponent_notation(true)
    // Disable all special numbers, such as Nan and Inf.
    .no_special(true)
    .build();

// Due to use in a `const fn`, we can't panic or expect users to unwrap invalid
// formats, so it's up to the caller to verify the format. If an invalid format
// is provided to a parser or writer, the function will error or panic, respectively.
debug_assert!(lexical_core::format_is_valid::<FORMAT>());

选项 API

选项API允许在运行时自定义数字解析和写入，例如指定最大有效数字位数、指数字符等。

以下是一个构建自定义选项结构的示例

use std::num;

let options = lexical_core::WriteFloatOptions::builder()
    // Only write up to 5 significant digits, IE, `1.23456` becomes `1.2345`.
    .max_significant_digits(num::NonZeroUsize::new(5))
    // Never write less than 5 significant digits, `1.1` becomes `1.1000`.
    .min_significant_digits(num::NonZeroUsize::new(5))
    // Trim the trailing `.0` from integral float strings.
    .trim_floats(true)
    // Use a European-style decimal point.
    .decimal_point(b',')
    // Panic if we try to write NaN as a string.
    .nan_string(None)
    // Write infinity as "Infinity".
    .inf_string(Some(b"Infinity"))
    .build()
    .unwrap();

文档

Lexical的API参考可以在 docs.rs 上找到，同样lexical-core的。算法的详细描述可以在这里找到

• 解析整数
• 解析浮点数
• 写入整数
• 写入浮点数

此外，还记录了lexical如何处理 数字分隔符 以及实现 大整数算术。

验证

浮点数解析

正确进行浮点数解析很困难，从 libstdc++'s strtod 到 Python 的实现中发现了许多重大错误。为了验证lexical的准确性，我们采用了以下外部测试

1. Hrvoje Abraham的 strtod 测试用例。
2. Rust的 test-float-parse 单元测试。
3. Testbase的将十进制转换为二进制的 压力测试。
4. Nigel Tao从 Freetype、Google的 double-conversion 库、IBM的 IEEE-754R 兼容性测试以及其他许多精心挑选的示例中提取的 测试。
5. 各种 困难 情况 在博客上报告。

尽管词法分析器可能包含导致舍入误差的错误，但它已经通过了针对随机数据和近似中点表示的综合测试套件，应该对大多数用例快速且正确。

度量

这里展示了各种基准、二进制大小和编译时间。

构建时间

启用所有数值转换时的编译时间。对于更详细的分解，请参阅构建时间。

二进制大小

在优化级别“2”编译的剥离二进制文件的大小。对于更详细的分解，请参阅二进制大小。

基准测试 -- 解析整数

对在整个范围内均匀分布的随机生成的整数进行基准测试。对于更详细的分解，请参阅基准测试。

基准测试 -- 解析浮点数

对从各种实际数据集解析浮点数的基准测试。对于更详细的分解，请参阅基准测试。

基准测试 -- 写入整数

对在整个范围内均匀分布的随机整数进行写入的基准测试。对于更详细的分解，请参阅基准测试。

基准测试 -- 写入浮点数

对通过随机数生成器生成的浮点数进行写入和从JSON文档解析的基准测试。对于更详细的分解，请参阅基准测试。

安全性

由于整数和浮点数写入器中使用了内存不安全代码，我们对浮点数写入器和解析器进行了广泛的模糊测试。模糊测试工具可以在fuzz下找到，并且是持续运行的。到目前为止，我们已经解析和写入了超过720亿个浮点数。

由于整数写入器的简单逻辑和整数解析器中缺乏内存安全性，我们对两者都进行了有限的模糊测试，并使用边缘情况进行了测试，迄今为止没有出现内存安全问题。

平台支持

lexical-core在包括大端和小端系统在内的多种平台上进行了测试，以确保代码的可移植性。支持的架构包括

• x86_64 Linux、Windows、macOS、Android、iOS、FreeBSD和NetBSD。
• x86 Linux、macOS、Android、iOS和FreeBSD。
• aarch64 (ARM8v8-A) Linux、Android和iOS。
• armv7 (ARMv7-A) Linux、Android和iOS。
• arm (ARMv6) Linux和Android。
• mips (MIPS) Linux。
• mipsel (MIPS LE) Linux。
• mips64 (MIPS64 BE) Linux。
• mips64el (MIPS64 LE) Linux。
• powerpc (PowerPC) Linux。
• powerpc64 (PPC64) Linux。
• powerpc64le (PPC64LE) Linux。
• s390x (IBM Z) Linux。

lexical-core还应适用于广泛的其他架构和指令集。如果您在任何架构上编译lexical-core时遇到任何问题，请提交错误报告。

版本和版本支持

版本支持

目前支持的版本是

• v0.8.x
• v0.7.x（维护）
• v0.6.x（维护）

Rustc 兼容性

• v0.8.x 支持 1.51+，包括稳定版、beta版和nightly版本。
• v0.7.x 支持 1.37+，包括稳定版、beta版和nightly版本。
• v0.6.x 支持 Rustc 1.24+，包括稳定版、beta版和nightly版本。

请报告在兼容的Rustc版本上编译支持的lexical-core版本时出现的任何错误。

版本控制

lexical使用语义版本控制。移除对最新稳定Debian或Ubuntu版本之后的Rustc版本的支持被认为是API不兼容的更改，需要主要版本更改。

变更日志

所有更改均记录在变更日志中。

许可

Lexical同时遵循Apache 2.0许可协议和MIT许可协议。请参阅LICENSE.md文件以获取完整的许可详情。

贡献

除非您明确表示，否则您根据Apache-2.0许可协议提交的任何有意包含在lexical中的贡献，将如上所述双重许可，不附加任何额外的条款或条件。向仓库贡献意味着遵守行为准则。

有关如何贡献给lexical的流程，请参阅开发快速入门指南。