malachite_base/num/conversion/string/
mod.rs

1// Copyright © 2026 Mikhail Hogrefe
2//
3// This file is part of Malachite.
4//
5// Malachite is free software: you can redistribute it and/or modify it under the terms of the GNU
6// Lesser General Public License (LGPL) as published by the Free Software Foundation; either version
7// 3 of the License, or (at your option) any later version. See <https://www.gnu.org/licenses/>.
8
9/// [`FromSciString`](super::traits::FromSciString), a trait for converting strings, possibly using
10/// scientific notation, to numbers.
11///
12/// # from_sci_string
13/// ```
14/// use malachite_base::num::conversion::traits::FromSciString;
15///
16/// assert_eq!(u8::from_sci_string("123"), Some(123));
17/// assert_eq!(u8::from_sci_string("123.5"), Some(124));
18/// assert_eq!(u8::from_sci_string("256"), None);
19/// assert_eq!(u64::from_sci_string("1.23e10"), Some(12300000000));
20/// ```
21///
22/// # from_sci_string_with_options
23/// ```
24/// use malachite_base::num::conversion::string::options::FromSciStringOptions;
25/// use malachite_base::num::conversion::traits::FromSciString;
26/// use malachite_base::rounding_modes::RoundingMode::*;
27///
28/// let mut options = FromSciStringOptions::default();
29/// assert_eq!(
30///     u8::from_sci_string_with_options("123.5", options),
31///     Some(124)
32/// );
33///
34/// options.set_rounding_mode(Floor);
35/// assert_eq!(
36///     u8::from_sci_string_with_options("123.5", options),
37///     Some(123)
38/// );
39///
40/// options = FromSciStringOptions::default();
41/// options.set_base(16);
42/// assert_eq!(u8::from_sci_string_with_options("ff", options), Some(255));
43/// ```
44pub mod from_sci_string;
45/// [`FromStringBase`](super::traits::FromStringBase), a trait for converting strings in a specified
46/// base to numbers.
47pub mod from_string;
48/// [`ToLatex`](crate::strings::latex::ToLatex) implementations for primitive integers and primitive
49/// floats, converting them to LaTeX math-mode fragments.
50///
51/// # fmt_latex
52/// ```
53/// use malachite_base::strings::latex::ToLatex;
54///
55/// assert_eq!(0u8.to_latex_string(), "0");
56/// assert_eq!(123u32.to_latex_string(), "123");
57/// assert_eq!((-45i16).to_latex_string(), "-45");
58/// assert_eq!(i64::MIN.to_latex_string(), "-9223372036854775808");
59/// ```
60///
61/// | value      | fragment               | renders as             |
62/// |------------|------------------------|------------------------|
63/// | `0u8`      | `0`                    | $0$                    |
64/// | `123u32`   | `123`                  | $123$                  |
65/// | `-45i16`   | `-45`                  | $-45$                  |
66/// | `i64::MIN` | `-9223372036854775808` | $-9223372036854775808$ |
67///
68/// ```
69/// use malachite_base::num::basic::floats::PrimitiveFloat;
70/// use malachite_base::num::basic::traits::NegativeInfinity;
71/// use malachite_base::strings::latex::ToLatex;
72///
73/// assert_eq!(f64::NAN.to_latex_string(), r"\text{NaN}");
74/// assert_eq!(f64::INFINITY.to_latex_string(), r"\infty");
75/// assert_eq!(f64::NEGATIVE_INFINITY.to_latex_string(), r"-\infty");
76/// assert_eq!(0.0f64.to_latex_string(), "0.0");
77/// assert_eq!((-0.0f64).to_latex_string(), "-0.0");
78///
79/// assert_eq!(1.0f64.to_latex_string(), "1.0");
80/// assert_eq!(0.00123f64.to_latex_string(), "0.00123");
81/// assert_eq!(1.0e16f64.to_latex_string(), r"1.0 \times 10^{16}");
82/// assert_eq!(
83///     f32::MIN_POSITIVE_SUBNORMAL.to_latex_string(),
84///     r"1.0 \times 10^{-45}"
85/// );
86/// ```
87///
88/// | value                         | fragment              | renders as            |
89/// |-------------------------------|-----------------------|-----------------------|
90/// | `f64::NAN`                    | `\text{NaN}`          | $\text{NaN}$          |
91/// | `f64::INFINITY`               | `\infty`              | $\infty$              |
92/// | `f64::NEGATIVE_INFINITY`      | `-\infty`             | $-\infty$             |
93/// | `0.0`                         | `0.0`                 | $0.0$                 |
94/// | `-0.0`                        | `-0.0`                | $-0.0$                |
95/// | `1.0`                         | `1.0`                 | $1.0$                 |
96/// | `0.00123`                     | `0.00123`             | $0.00123$             |
97/// | `1.0e16`                      | `1.0 \times 10^{16}`  | $1.0 \times 10^{16}$  |
98/// | `f32::MIN_POSITIVE_SUBNORMAL` | `1.0 \times 10^{-45}` | $1.0 \times 10^{-45}$ |
99pub mod latex;
100/// [`ToSciOptions`](options::ToSciOptions) and
101/// [`FromSciSringOptions`](options::FromSciStringOptions), `struct`s for specifying parameters when
102/// using the [`FromSciString`](super::traits::FromSciString) and [`ToSci`](super::traits::ToSci)
103/// traits.
104pub mod options;
105/// [`ToSci`](super::traits::ToSci), a trait for converting a number to string, possibly using
106/// scientific notation.
107///
108/// # to_sci
109/// ```
110/// use malachite_base::num::conversion::traits::ToSci;
111///
112/// // If the value can fit in a `u32`, the result is the same as with `to_string`
113/// assert_eq!(123u8.to_sci().to_string(), "123");
114///
115/// assert_eq!(u128::MAX.to_sci().to_string(), "3.402823669209385e38");
116/// assert_eq!(i128::MIN.to_sci().to_string(), "-1.701411834604692e38");
117/// ```
118///
119/// # to_sci_with_options
120/// ```
121/// use malachite_base::num::conversion::string::options::ToSciOptions;
122/// use malachite_base::num::conversion::traits::ToSci;
123/// use malachite_base::rounding_modes::RoundingMode::*;
124///
125/// let mut options = ToSciOptions::default();
126/// assert_eq!(123456u32.to_sci_with_options(options).to_string(), "123456");
127///
128/// options.set_precision(3);
129/// assert_eq!(123456u32.to_sci_with_options(options).to_string(), "1.23e5");
130///
131/// options.set_rounding_mode(Ceiling);
132/// assert_eq!(123456u32.to_sci_with_options(options).to_string(), "1.24e5");
133///
134/// options.set_e_uppercase();
135/// assert_eq!(123456u32.to_sci_with_options(options).to_string(), "1.24E5");
136///
137/// options.set_force_exponent_plus_sign(true);
138/// assert_eq!(
139///     123456u32.to_sci_with_options(options).to_string(),
140///     "1.24E+5"
141/// );
142///
143/// options = ToSciOptions::default();
144/// options.set_base(36);
145/// assert_eq!(123456u32.to_sci_with_options(options).to_string(), "2n9c");
146///
147/// options.set_uppercase();
148/// assert_eq!(123456u32.to_sci_with_options(options).to_string(), "2N9C");
149///
150/// options.set_base(2);
151/// options.set_precision(10);
152/// assert_eq!(
153///     123456u32.to_sci_with_options(options).to_string(),
154///     "1.1110001e16"
155/// );
156///
157/// options.set_include_trailing_zeros(true);
158/// assert_eq!(
159///     123456u32.to_sci_with_options(options).to_string(),
160///     "1.111000100e16"
161/// );
162/// ```
163///
164/// # fmt_sci_valid
165/// ```
166/// use malachite_base::num::conversion::string::options::ToSciOptions;
167/// use malachite_base::num::conversion::traits::ToSci;
168/// use malachite_base::rounding_modes::RoundingMode::*;
169///
170/// let mut options = ToSciOptions::default();
171/// assert!(123u8.fmt_sci_valid(options));
172/// assert!(u128::MAX.fmt_sci_valid(options));
173/// options.set_rounding_mode(Exact);
174/// assert!(!u128::MAX.fmt_sci_valid(options)); // u128::MAX has more than 16 significant digits
175/// options.set_precision(50);
176/// assert!(u128::MAX.fmt_sci_valid(options));
177/// ```
178pub mod to_sci;
179/// The [`BaseFmtWrapper`](to_string::BaseFmtWrapper) struct and
180/// [`ToStringBase`](super::traits::ToStringBase) trait, used for converting numbers to strings.
181///
182/// # Display::fmt for BaseFmtWrapper
183/// ```
184/// use malachite_base::num::conversion::string::to_string::BaseFmtWrapper;
185///
186/// let x = BaseFmtWrapper::new(1000000000u32, 36);
187/// assert_eq!(format!("{}", x), "gjdgxs");
188/// assert_eq!(format!("{:#}", x), "GJDGXS");
189/// assert_eq!(format!("{:010}", x), "0000gjdgxs");
190/// assert_eq!(format!("{:#010}", x), "0000GJDGXS");
191///
192/// let x = BaseFmtWrapper::new(-1000000000i32, 36);
193/// assert_eq!(format!("{}", x), "-gjdgxs");
194/// assert_eq!(format!("{:#}", x), "-GJDGXS");
195/// assert_eq!(format!("{:010}", x), "-000gjdgxs");
196/// assert_eq!(format!("{:#010}", x), "-000GJDGXS");
197/// ```
198///
199/// # Debug::fmt for BaseFmtWrapper
200/// ```
201/// use malachite_base::num::conversion::string::to_string::BaseFmtWrapper;
202///
203/// let x = BaseFmtWrapper::new(1000000000u32, 36);
204/// assert_eq!(format!("{:?}", x), "gjdgxs");
205/// assert_eq!(format!("{:#?}", x), "GJDGXS");
206/// assert_eq!(format!("{:010?}", x), "0000gjdgxs");
207/// assert_eq!(format!("{:#010?}", x), "0000GJDGXS");
208///
209/// let x = BaseFmtWrapper::new(-1000000000i32, 36);
210/// assert_eq!(format!("{:?}", x), "-gjdgxs");
211/// assert_eq!(format!("{:#?}", x), "-GJDGXS");
212/// assert_eq!(format!("{:010?}", x), "-000gjdgxs");
213/// assert_eq!(format!("{:#010?}", x), "-000GJDGXS");
214/// ```
215///
216/// # to_string_base
217/// ```
218/// use malachite_base::num::conversion::traits::ToStringBase;
219///
220/// assert_eq!(1000u16.to_string_base(2), "1111101000");
221/// assert_eq!(1000u16.to_string_base(10), "1000");
222/// assert_eq!(1000u16.to_string_base(36), "rs");
223///
224/// assert_eq!(1000i16.to_string_base(2), "1111101000");
225/// assert_eq!(1000i16.to_string_base(10), "1000");
226/// assert_eq!(1000i16.to_string_base(36), "rs");
227///
228/// assert_eq!((-1000i16).to_string_base(2), "-1111101000");
229/// assert_eq!((-1000i16).to_string_base(10), "-1000");
230/// assert_eq!((-1000i16).to_string_base(36), "-rs");
231/// assert_eq!((-1000i16).to_string_base(62), "-G8");
232/// ```
233///
234/// # to_string_base_upper
235/// ```
236/// use malachite_base::num::conversion::traits::ToStringBase;
237///
238/// assert_eq!(1000u16.to_string_base_upper(2), "1111101000");
239/// assert_eq!(1000u16.to_string_base_upper(10), "1000");
240/// assert_eq!(1000u16.to_string_base_upper(36), "RS");
241///
242/// assert_eq!(1000i16.to_string_base_upper(2), "1111101000");
243/// assert_eq!(1000i16.to_string_base_upper(10), "1000");
244/// assert_eq!(1000i16.to_string_base_upper(36), "RS");
245///
246/// assert_eq!((-1000i16).to_string_base_upper(2), "-1111101000");
247/// assert_eq!((-1000i16).to_string_base_upper(10), "-1000");
248/// assert_eq!((-1000i16).to_string_base_upper(36), "-RS");
249/// ```
250pub mod to_string;
251/// [`ToTypst`](crate::strings::typst::ToTypst) implementations for primitive integers and primitive
252/// floats, converting them to Typst math-mode fragments.
253///
254/// # fmt_typst
255/// ```
256/// use malachite_base::strings::typst::ToTypst;
257///
258/// assert_eq!(0u8.to_typst_string(), "0");
259/// assert_eq!(123u32.to_typst_string(), "123");
260/// assert_eq!((-45i16).to_typst_string(), "-45");
261/// assert_eq!(i64::MIN.to_typst_string(), "-9223372036854775808");
262/// ```
263///
264/// | value      | fragment               |
265/// |------------|------------------------|
266/// | `0u8`      | `0`                    |
267/// | `123u32`   | `123`                  |
268/// | `-45i16`   | `-45`                  |
269/// | `i64::MIN` | `-9223372036854775808` |
270///
271/// ```
272/// use malachite_base::num::basic::floats::PrimitiveFloat;
273/// use malachite_base::num::basic::traits::NegativeInfinity;
274/// use malachite_base::strings::typst::ToTypst;
275///
276/// assert_eq!(f64::NAN.to_typst_string(), r#""NaN""#);
277/// assert_eq!(f64::INFINITY.to_typst_string(), "infinity");
278/// assert_eq!(f64::NEGATIVE_INFINITY.to_typst_string(), "-infinity");
279/// assert_eq!(0.0f64.to_typst_string(), "0.0");
280/// assert_eq!((-0.0f64).to_typst_string(), "-0.0");
281///
282/// assert_eq!(1.0f64.to_typst_string(), "1.0");
283/// assert_eq!(0.00123f64.to_typst_string(), "0.00123");
284/// assert_eq!(1.0e16f64.to_typst_string(), "1.0 times 10^(16)");
285/// assert_eq!(
286///     f32::MIN_POSITIVE_SUBNORMAL.to_typst_string(),
287///     "1.0 times 10^(-45)"
288/// );
289/// ```
290///
291/// | value                         | fragment             |
292/// |-------------------------------|----------------------|
293/// | `f64::NAN`                    | `"NaN"`              |
294/// | `f64::INFINITY`               | `infinity`           |
295/// | `f64::NEGATIVE_INFINITY`      | `-infinity`          |
296/// | `0.0`                         | `0.0`                |
297/// | `-0.0`                        | `-0.0`               |
298/// | `1.0`                         | `1.0`                |
299/// | `0.00123`                     | `0.00123`            |
300/// | `1.0e16`                      | `1.0 times 10^(16)`  |
301/// | `f32::MIN_POSITIVE_SUBNORMAL` | `1.0 times 10^(-45)` |
302pub mod typst;
malachite_base/num/conversion/string/mod.rs

malachite_base/num/conversion/string/
mod.rs
