lexical_util/
options.rs

1//! Shared traits for the options API.
2//!
3//! The following constants have the following signifiers:
4//!
5//! - `${X}_LITERAL`: Applies to all literal values for that language (for
6//!   example, [`RUST_LITERAL`]).
7//! - `${X}_STRING`: Applies to all string values for that language (for
8//!   example, [`ERLANG_STRING`]).
9//! - `${X}`: Applies to all values for that language (for example, [`KAWA`]).
10//! - `${X}_(NAN|INF|INFINITY)`: Applies to only a single special value (for
11//!   example, [`PHP_LITERAL_NAN`], [`PHP_LITERAL_INF`], and
12//!   [`PHP_LITERAL_INFINITY`]).
13//!
14//! If it's not defined, all values are the default. The default options
15//! are:
16//! - NaN: (`*_NAN`): `NaN`
17//! - Short infinity: (`*_INF`): `Inf` (including `+Inf` and `-Inf`)
18//! - Long infinity: (`*_INFINITY`): `Infinity` (including `+Infinity` and
19//!   `-Infinity`)
20
21#[cfg(any(feature = "write-floats", feature = "write-integers"))]
22use crate::constants::FormattedSize;
23
24// TRAITS
25// ------
26
27#[doc(hidden)]
28#[macro_export]
29macro_rules! write_options_doc {
30    () => {
31        "
32Get an upper bound on the required buffer size.
33
34<div class=\"warning\">
35
36This method is soft-deprecated and meant for internal use.
37You should always use [`buffer_size_const`] so you can get
38the required buffer size at compile time to determine the
39buffer size required.
40
41</div>
42
43[`buffer_size_const`]: Self::buffer_size_const
44
45This is used when custom formatting options, such as significant
46digits specifiers or custom exponent breaks, are used, which
47can lead to more or less significant digits being written than
48expected. If using the default formatting options, then this will
49always be [`FORMATTED_SIZE`][FormattedSize::FORMATTED_SIZE] or
50[`FORMATTED_SIZE_DECIMAL`][FormattedSize::FORMATTED_SIZE_DECIMAL],
51depending on the radix.
52"
53    };
54}
55
56/// Shared trait for all writer options.
57#[cfg(any(feature = "write-floats", feature = "write-integers"))]
58pub trait WriteOptions: Default {
59    /// Determine if the options are valid.
60    fn is_valid(&self) -> bool;
61
62    /// Get an upper bound on the required buffer size.
63    ///
64    /// <div class="warning">
65    ///
66    /// This method is soft-deprecated and meant for internal use.
67    /// You should always use `buffer_size_const` for either [`integer`] or
68    /// [`float`] writer so you can get the required buffer size at compile time
69    /// to determine the buffer size required.
70    ///
71    /// </div>
72    ///
73    /// [`integer`]: https://docs.rs/lexical-write-integer/latest/lexical_write_integer/struct.Options.html#method.buffer_size_const
74    /// [`float`]: https://docs.rs/lexical-write-float/latest/lexical_write_float/struct.Options.html#method.buffer_size_const
75    ///
76    /// This is used when custom formatting options, such as significant
77    /// digits specifiers or custom exponent breaks, are used, which
78    /// can lead to more or less significant digits being written than
79    /// expected. If using the default formatting options, then this will
80    /// always be [`FORMATTED_SIZE`][FormattedSize::FORMATTED_SIZE] or
81    /// [`FORMATTED_SIZE_DECIMAL`][FormattedSize::FORMATTED_SIZE_DECIMAL],
82    /// depending on the radix.
83    ///
84    /// Using `buffer_size_const` lets you create static arrays at compile time,
85    /// rather than dynamically-allocate memory or know the value ahead of time.
86    #[deprecated = "Use `buffer_size_const` instead. Will be removed in 2.0."]
87    fn buffer_size<T: FormattedSize, const FORMAT: u128>(&self) -> usize;
88}
89
90/// Shared trait for all parser options.
91#[cfg(any(feature = "parse-floats", feature = "parse-integers"))]
92pub trait ParseOptions: Default {
93    /// Determine if the options are valid.
94    fn is_valid(&self) -> bool;
95}
96
97// PRE-DEFINED CONSTANTS
98// ---------------------
99
100// The following constants have the following signifiers:
101//  ${X}_LITERAL - Applies to all literal values for that language.
102//  ${X}_STRING - Applies to all string values for that language.
103//  ${X} - Applies to all values for that language.
104//  ${X}_(NAN|INF|INFINITY) - Applies to only a single special value.
105//  IF it's not defined, all values are the default.
106
107macro_rules! literal {
108    ($name:ident, $value:ident $(, $doc:literal)?) => {
109        $(#[doc = $doc])?
110        pub const $name: Option<&[u8]> = $value;
111    };
112    ($name:ident, $value:literal $(, $doc:literal)?) => {
113        $(#[doc = $doc])?
114        pub const $name: Option<&[u8]> = Some($value);
115    };
116}
117
118literal!(RUST_LITERAL, None, "A `Rust` literal number (uses default options).");
119// RUST_STRING
120literal!(PYTHON_LITERAL, None, "A `Python` literal number (uses default options).");
121// PYTHON_STRING
122literal!(CXX_LITERAL_NAN, b"NAN", "A `C++` literal NaN (`NAN`).");
123literal!(CXX_LITERAL_INF, b"INFINITY", "A `C++` literal short infinity (`INFINITY`).");
124literal!(CXX_LITERAL_INFINITY, b"INFINITY", "A `C++` literal long infinity (`INFINITY`).");
125// CXX_STRING
126literal!(C_LITERAL_NAN, b"NAN", "A `C` literal NaN (`NAN`).");
127literal!(C_LITERAL_INF, b"INFINITY", "A `C` literal short infinity (`INFINITY`).");
128literal!(C_LITERAL_INFINITY, b"INFINITY", "A `C` literal long infinity (`INFINITY`).");
129// RUBY_LITERAL
130literal!(RUBY_LITERAL_NAN, b"NaN", "A `Ruby` literal NaN (`NaN`).");
131literal!(RUBY_LITERAL_INF, b"Infinity", "A `Ruby` literal short infinity (`Infinity`).");
132literal!(RUBY_STRING_NONE, None, "A `Ruby` string (uses default options).");
133// C_STRING
134literal!(SWIFT_LITERAL, None, "A `Swift` literal number (uses default options).");
135// SWIFT_STRING
136literal!(GO_LITERAL, None, "A `Golang` literal number (uses default options).");
137// GO_STRING
138literal!(HASKELL_LITERAL, None, "A `Haskell` literal number (uses default options).");
139literal!(HASKELL_STRING_INF, b"Infinity", "A `Haskell` string short infinity (`Infinity`).");
140literal!(HASKELL_STRING_INFINITY, b"Infinity", "A `Haskell` string long infinity (`Infinity`).");
141literal!(JAVASCRIPT_INF, b"Infinity", "A `JavaScript` string short infinity (`Infinity`).");
142literal!(JAVASCRIPT_INFINITY, b"Infinity", "A `JavaScript` string long infinity (`Infinity`).");
143literal!(PERL_LITERAL, None, "A `Perl` literal literal (uses default options).");
144// PERL_STRING
145literal!(PHP_LITERAL_NAN, b"NAN", "A `PHP` literal NaN (`NAN`).");
146literal!(PHP_LITERAL_INF, b"INF", "A `PHP` literal short infinity (`INF`).");
147literal!(PHP_LITERAL_INFINITY, b"INF", "A `PHP` literal long infinity (`INF`).");
148// PHP_STRING
149literal!(JAVA_LITERAL, None, "A `Java` literal number (uses default options).");
150literal!(JAVA_STRING_INF, b"Infinity", "A `Java` string short infinity (`Infinity`).");
151literal!(JAVA_STRING_INFINITY, b"Infinity", "A `Java` string long infinity (`Infinity`).");
152literal!(R_LITERAL_INF, b"Inf", "An `R` literal short infinity (`Inf`).");
153literal!(R_LITERAL_INFINITY, b"Inf", "An `R` literal long infinity (`Inf`).");
154// R_STRING
155literal!(KOTLIN_LITERAL, None, "A `Kotlin` literal number (uses default options).");
156literal!(KOTLIN_STRING_INF, b"Infinity", "A `Kotlin` string short infinity (`Infinity`).");
157literal!(KOTLIN_STRING_INFINITY, b"Infinity", "A `Kotlin` string long infinity (`Infinity`).");
158literal!(JULIA_LITERAL_INF, b"Inf", "A `Julia` string short infinity (`Inf`).");
159literal!(JULIA_LITERAL_INFINITY, b"Inf", "A `Julia` string long infinity (`Inf`).");
160// JULIA_STRING
161literal!(CSHARP_LITERAL, None, "A `C#` literal number (uses default options).");
162literal!(CSHARP_STRING_INF, b"Infinity", "A `C#` string short infinity (`Infinity`).");
163literal!(CSHARP_STRING_INFINITY, b"Infinity", "A `C#` string long infinity (`Infinity`).");
164literal!(KAWA, None, "A `Kawa` (Lisp) literal number (uses default options).");
165literal!(GAMBITC, None, "A `Gambit-C` (Lisp) literal number (uses default options).");
166literal!(GUILE, None, "A `Guile` (Lisp) literal number (uses default options).");
167literal!(CLOJURE_LITERAL, None, "A `Clojure` (Lisp) literal number (uses default options).");
168literal!(CLOJURE_STRING_INF, b"Infinity", "A `Clojure` string short infinity (`Infinity`).");
169literal!(CLOJURE_STRING_INFINITY, b"Infinity", "A `Clojure` string long infinity (`Infinity`).");
170literal!(ERLANG_LITERAL_NAN, b"nan", "An `Erlang` literal NaN (`nan`).");
171literal!(ERLANG_STRING, None, "An `Erlang` string number (uses default options).");
172literal!(ELM_LITERAL, None, "An `Elm` literal number (uses default options).");
173literal!(ELM_STRING_NAN, None, "An `Elm` strong NaN (uses default options).");
174literal!(ELM_STRING_INF, b"Infinity", "An `Elm` string short infinity (`Infinity`).");
175literal!(ELM_STRING_INFINITY, b"Infinity", "An `Elm` string long infinity (`Infinity`).");
176literal!(SCALA_LITERAL, None, "A `Scala` literal number (uses default options).");
177literal!(SCALA_STRING_INF, b"Infinity", "A `Scala` string short infinity (`Infinity`).");
178literal!(SCALA_STRING_INFINITY, b"Infinity", "A `Scala` string long infinity (`Infinity`).");
179literal!(ELIXIR, None, "An `Elixir` number (uses default options).");
180literal!(FORTRAN_LITERAL, None, "A `FORTRAN` literal number (uses default options).");
181// FORTRAN_STRING
182literal!(D_LITERAL, None, "A `D-Lang` literal number (uses default options).");
183// D_STRING
184literal!(COFFEESCRIPT_INF, b"Infinity", "A `CoffeeScript` string short infinity (`Infinity`).");
185literal!(COFFEESCRIPT_INFINITY, b"Infinity", "A `CoffeeScript` string long infinity (`Infinity`).");
186literal!(COBOL, None, "A `COBOL` literal number (uses default options).");
187literal!(FSHARP_LITERAL_NAN, b"nan", "An `F#` literal NaN (`nan`).");
188literal!(FSHARP_LITERAL_INF, b"infinity", "An `F#` literal short infinity (`infinity`).");
189literal!(FSHARP_LITERAL_INFINITY, b"infinity", "An `F#` literal long infinity (`infinity`).");
190// FSHARP_STRING
191literal!(VB_LITERAL, None, "A `Visual Basic` literal number (uses default options)");
192literal!(VB_STRING_INF, None, "A `Visual Basic` short string infinity (uses default options)");
193literal!(VB_STRING_INFINITY, None, "A `Visual Basic` long string number (uses default options)");
194literal!(OCAML_LITERAL_NAN, b"nan", "An `OCAML` literal NaN (`nan`).");
195literal!(OCAML_LITERAL_INF, b"infinity", "An `OCAML` literal short infinity (`infinity`).");
196literal!(OCAML_LITERAL_INFINITY, b"infinity", "An `OCAML` literal long infinity (`infinity`).");
197// OCAML_STRING
198literal!(OBJECTIVEC, None, "An `Objective-C` number (uses default options).");
199literal!(REASONML_LITERAL_NAN, b"nan", "A `ReasonML` literal NaN (`nan`).");
200literal!(REASONML_LITERAL_INF, b"infinity", "A `ReasonML` literal short infinity (`infinity`).");
201literal!(
202    REASONML_LITERAL_INFINITY,
203    b"infinity",
204    "A `ReasonML` literal long infinity (`infinity`)."
205);
206// REASONML_STRING
207literal!(MATLAB_LITERAL_INF, b"inf", "A `MATLAB` literal short infinity (`inf`).");
208literal!(MATLAB_LITERAL_INFINITY, b"Inf", "A `MATLAB` literal long infinity (`Inf`).");
209// MATLAB_STRING
210literal!(ZIG_LITERAL, None, "A `Zig` literal number (uses default options).");
211// ZIG_STRING
212literal!(SAGE_LITERAL_INF, b"infinity", "A `SageMath` literal short infinity (`infinity`).");
213literal!(SAGE_LITERAL_INFINITY, b"Infinity", "A `SageMath` literal long infinity (`Infinity`).");
214// SAGE_STRING
215literal!(JSON, None, "A `JSON` number (uses default options).");
216literal!(TOML, None, "A `TOML` number (uses default options).");
217literal!(YAML, None, "A `YAML` number (uses default options).");
218literal!(XML_INF, None, "An `XML` short infinity (uses default options).");
219literal!(XML_INFINITY, None, "An `XML` short infinity (uses default options).");
220literal!(SQLITE, None, "A `SQLite` number (uses default options).");
221literal!(POSTGRESQL, None, "A `PostgreSQL` number (uses default options).");
222literal!(MYSQL, None, "A `MySQL` number (uses default options).");
223literal!(MONGODB_INF, b"Infinity", "A `MongoDB` short infinity (`Infinity`).");
224literal!(MONGODB_INFINITY, b"Infinity", "A `MongoDB` long infinity (`Infinity`).");
lexical_util/options.rs

lexical_util/
options.rs
