fast_float2/
lib.rs

1//! This crate provides a super-fast decimal number parser from strings into
2//! floats.
3//!
4//! ## Usage
5//!
6//! There's two top-level functions provided: [`parse`](crate::parse()) and
7//! [`parse_partial`](crate::parse_partial()), both taking
8//! either a string or a bytes slice and parsing the input into either `f32` or
9//! `f64`:
10//!
11//! - [`parse`](crate::parse()) treats the whole string as a decimal number and
12//!   returns an error if there are invalid characters or if the string is
13//!   empty.
14//! - [`parse_partial`](crate::parse_partial()) tries to find the longest
15//!   substring at the beginning of the given input string that can be parsed as
16//!   a decimal number and, in the case of success, returns the parsed value
17//!   along the number of characters processed; an error is returned if the
18//!   string doesn't start with a decimal number or if it is empty. This
19//!   function is most useful as a building block when constructing more complex
20//!   parsers, or when parsing streams of data.
21//!
22//! ## Examples
23//!
24//! ```rust
25//! // Parse the entire string as a decimal number.
26//! let s = "1.23e-02";
27//! let x: f32 = fast_float2::parse(s).unwrap();
28//! assert_eq!(x, 0.0123);
29//!
30//! // Parse as many characters as possible as a decimal number.
31//! let s = "1.23e-02foo";
32//! let (x, n) = fast_float2::parse_partial::<f32, _>(s).unwrap();
33//! assert_eq!(x, 0.0123);
34//! assert_eq!(n, 8);
35//! assert_eq!(&s[n..], "foo");
36//! ```
37
38#![cfg_attr(not(feature = "std"), no_std)]
39#![allow(unused_unsafe)]
40#![warn(unsafe_op_in_unsafe_fn)]
41#![warn(clippy::all, clippy::pedantic, clippy::nursery, clippy::cargo)]
42#![deny(
43    clippy::doc_markdown,
44    clippy::unnecessary_safety_comment,
45    clippy::semicolon_if_nothing_returned,
46    clippy::unwrap_used,
47    clippy::as_underscore,
48    clippy::doc_markdown
49)]
50#![allow(
51    clippy::cast_possible_truncation,
52    clippy::cast_possible_wrap,
53    clippy::cast_sign_loss,
54    clippy::cast_lossless,
55    clippy::cast_precision_loss,
56    clippy::missing_const_for_fn,
57    clippy::use_self,
58    clippy::module_name_repetitions,
59    clippy::cargo_common_metadata,
60    clippy::struct_field_names
61)]
62
63use core::fmt::{self, Display};
64
65mod binary;
66mod common;
67mod decimal;
68mod float;
69mod number;
70mod parse;
71mod simple;
72mod table;
73
74/// Opaque error type for fast-float parsing functions.
75#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
76pub struct Error;
77
78impl Display for Error {
79    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
80        write!(f, "error while parsing a float")
81    }
82}
83
84#[cfg(feature = "std")]
85impl std::error::Error for Error {
86    fn description(&self) -> &'static str {
87        "error while parsing a float"
88    }
89}
90
91/// Result type alias for fast-float parsing functions.
92pub type Result<T> = core::result::Result<T, Error>;
93
94/// Trait for numerical float types that can be parsed from string.
95pub trait FastFloat: float::Float {
96    /// Parse a decimal number from string into float (full).
97    ///
98    /// # Errors
99    ///
100    /// Will return an error either if the string is not a valid decimal number.
101    /// or if any characters are left remaining unparsed.
102    #[inline]
103    fn parse_float<S: AsRef<[u8]>>(s: S) -> Result<Self> {
104        let s = s.as_ref();
105        match Self::parse_float_partial(s) {
106            Ok((v, n)) if n == s.len() => Ok(v),
107            _ => Err(Error),
108        }
109    }
110
111    /// Parse a decimal number from string into float (partial).
112    ///
113    /// This method parses as many characters as possible and returns the
114    /// resulting number along with the number of digits processed (in case
115    /// of success, this number is always positive).
116    ///
117    /// # Errors
118    ///
119    /// Will return an error either if the string doesn't start with a valid
120    /// decimal number – that is, if no zero digits were processed.
121    #[inline]
122    fn parse_float_partial<S: AsRef<[u8]>>(s: S) -> Result<(Self, usize)> {
123        parse::parse_float(s.as_ref()).ok_or(Error)
124    }
125}
126
127impl FastFloat for f32 {
128}
129impl FastFloat for f64 {
130}
131
132/// Parse a decimal number from string into float (full).
133///
134/// # Errors
135///
136/// Will return an error either if the string is not a valid decimal number
137/// or if any characters are left remaining unparsed.
138#[inline]
139pub fn parse<T: FastFloat, S: AsRef<[u8]>>(s: S) -> Result<T> {
140    T::parse_float(s)
141}
142
143/// Parse a decimal number from string into float (partial).
144///
145/// This function parses as many characters as possible and returns the
146/// resulting number along with the number of digits processed (in case of
147/// success, this number is always positive).
148///
149/// # Errors
150///
151/// Will return an error either if the string doesn't start with a valid decimal
152/// number – that is, if no zero digits were processed.
153#[inline]
154pub fn parse_partial<T: FastFloat, S: AsRef<[u8]>>(s: S) -> Result<(T, usize)> {
155    T::parse_float_partial(s)
156}
fast_float2/lib.rs

fast_float2/
lib.rs
