Crate lexical_parse_integer

Fast lexical string-to-integer conversion routines.

The default implementations are highly optimized both for simple strings, as well as input with large numbers of digits. In order to keep performance optimal for simple strings, we avoid overly branching to minimize the number of branches (and therefore optimization checks). Most of the branches in the code are resolved at compile-time, and the resulting ASM is monitored to ensure there are no regressions. For larger strings, a limited number of optimization checks are included to try faster, multi-digit parsing algorithms. For 32-bit integers, we try to parse 4 digits at a time, and for 64-bit and larger integers, we try to parse 8 digits at a time. Attempting both checks leads to significant performance penalties for simple strings, so only 1 optimization is used at at a time.

In addition, a compact, fallback algorithm uses a naive, simple algorithm, parsing only a single digit at a time. This avoid any unnecessary branching and produces smaller binaries, but comes at a significant performance penalty for integers with more digits.

Features

• std - Use the standard library.
• power-of-two - Add support for parsing power-of-two integer strings.
• radix - Add support for strings of any radix.
• format - Add support for parsing custom integer formats.
• compact - Reduce code size at the cost of performance.
• safe - Ensure only memory-safe indexing is used.

safe is a no-op, since all parsers are memory-safe by default.

Note

Only documented functionality is considered part of the public API: any of the modules, internal functions, or structs may change release-to-release without major or minor version changes. Use internal implementation details at your own risk.

lexical-parse-integer mainly exists as an implementation detail for lexical-core, although its API is stable. If you would like to use a high-level API that writes to and parses from String and &str, respectively, please look at lexical instead. If you would like an API that supports multiple numeric conversions, please look at lexical-core instead.

Version Support

The minimum, standard, required version is 1.63.0, for const generic support. Older versions of lexical support older Rust versions.

Design

• Algorithm Approach
• Benchmarks
• Comprehensive Benchmarks

Modules

• format
  Public API for the number format packed struct.
• options
  Configuration options for parsing integers.

Macros

• parse_sign
  Parse the sign from the leading digits.

Structs

• NumberFormatBuilder
  Build number format from specifications.
• Options
  Immutable options to customize writing integers.
• OptionsBuilder
  Builder for Options.

Enums

• Error
  Error code during parsing, indicating failure type.

Traits

• FromLexical
  Trait for numerical types that can be parsed from bytes.
• FromLexicalWithOptions
  Trait for numerical types that can be parsed from bytes with custom options.
• ParseOptions
  Shared trait for all parser options.

Type Aliases

• Result
  A specialized Result type for lexical operations.