malachite_nz/integer/conversion/
mod.rs

1// Copyright © 2025 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/// An implementation of the [`From`] trait for converting a [`bool`] to an
10/// [`Integer`](crate::integer::Integer).
11pub mod from_bool;
12/// Functions for converting a [`Natural`](crate::natural::Natural) to an
13/// [`Integer`](crate::integer::Integer), and an implementation of the [`From`] trait.
14pub mod from_natural;
15/// Implementations of traits for converting a primitive float to an
16/// [`Integer`](crate::integer::Integer).
17///
18/// The traits are [`TryFrom`],
19/// [`ConvertibleFrom`](malachite_base::num::conversion::traits::ConvertibleFrom), and
20/// [`RoundingFrom`](malachite_base::num::conversion::traits::RoundingFrom).
21///
22/// # rounding_from
23/// ```
24/// use malachite_base::num::conversion::traits::RoundingFrom;
25/// use malachite_base::rounding_modes::RoundingMode::*;
26/// use malachite_base::strings::ToDebugString;
27/// use malachite_nz::integer::Integer;
28///
29/// assert_eq!(
30///     Integer::rounding_from(0.0, Exact).to_debug_string(),
31///     "(0, Equal)"
32/// );
33/// assert_eq!(
34///     Integer::rounding_from(-0.0, Exact).to_debug_string(),
35///     "(0, Equal)"
36/// );
37/// assert_eq!(
38///     Integer::rounding_from(123.0, Exact).to_debug_string(),
39///     "(123, Equal)"
40/// );
41/// assert_eq!(
42///     Integer::rounding_from(1.0e9, Exact).to_debug_string(),
43///     "(1000000000, Equal)"
44/// );
45/// assert_eq!(
46///     Integer::rounding_from(1.0e9, Exact).to_debug_string(),
47///     "(1000000000, Equal)"
48/// );
49/// assert_eq!(
50///     Integer::rounding_from(4294967295.0, Exact).to_debug_string(),
51///     "(4294967295, Equal)"
52/// );
53/// assert_eq!(
54///     Integer::rounding_from(4294967296.0, Exact).to_debug_string(),
55///     "(4294967296, Equal)"
56/// );
57/// assert_eq!(
58///     Integer::rounding_from(1.0e100, Exact).to_debug_string(),
59///     "(1000000000000000015902891109759918046836080856394528138978132755774783877217038106081346\
60///     9985856815104, Equal)"
61/// );
62/// assert_eq!(
63///     Integer::rounding_from(123.1, Floor).to_debug_string(),
64///     "(123, Less)"
65/// );
66/// assert_eq!(
67///     Integer::rounding_from(123.1, Ceiling).to_debug_string(),
68///     "(124, Greater)"
69/// );
70/// assert_eq!(
71///     Integer::rounding_from(123.1, Nearest).to_debug_string(),
72///     "(123, Less)"
73/// );
74/// assert_eq!(
75///     Integer::rounding_from(123.9, Floor).to_debug_string(),
76///     "(123, Less)"
77/// );
78/// assert_eq!(
79///     Integer::rounding_from(123.9, Ceiling).to_debug_string(),
80///     "(124, Greater)"
81/// );
82/// assert_eq!(
83///     Integer::rounding_from(123.9, Nearest).to_debug_string(),
84///     "(124, Greater)"
85/// );
86/// assert_eq!(
87///     Integer::rounding_from(123.5, Nearest).to_debug_string(),
88///     "(124, Greater)"
89/// );
90/// assert_eq!(
91///     Integer::rounding_from(124.5, Nearest).to_debug_string(),
92///     "(124, Less)"
93/// );
94/// assert_eq!(
95///     Integer::rounding_from(-0.99, Ceiling).to_debug_string(),
96///     "(0, Greater)"
97/// );
98/// assert_eq!(
99///     Integer::rounding_from(-0.499, Nearest).to_debug_string(),
100///     "(0, Greater)"
101/// );
102/// assert_eq!(
103///     Integer::rounding_from(-0.5, Nearest).to_debug_string(),
104///     "(0, Greater)"
105/// );
106/// ```
107///
108/// # try_from
109/// ```
110/// use malachite_base::num::basic::traits::NegativeInfinity;
111/// use malachite_base::strings::ToDebugString;
112/// use malachite_nz::integer::Integer;
113///
114/// assert_eq!(
115///     Integer::try_from(f64::NAN).to_debug_string(),
116///     "Err(FloatInfiniteOrNan)"
117/// );
118/// assert_eq!(
119///     Integer::try_from(f64::INFINITY).to_debug_string(),
120///     "Err(FloatInfiniteOrNan)"
121/// );
122/// assert_eq!(
123///     Integer::try_from(f64::NEGATIVE_INFINITY).to_debug_string(),
124///     "Err(FloatInfiniteOrNan)"
125/// );
126/// assert_eq!(Integer::try_from(0.0).to_debug_string(), "Ok(0)");
127/// assert_eq!(Integer::try_from(-0.0).to_debug_string(), "Ok(0)");
128/// assert_eq!(Integer::try_from(123.0).to_debug_string(), "Ok(123)");
129/// assert_eq!(Integer::try_from(-123.0).to_debug_string(), "Ok(-123)");
130/// assert_eq!(Integer::try_from(1.0e9).to_debug_string(), "Ok(1000000000)");
131/// assert_eq!(
132///     Integer::try_from(4294967295.0).to_debug_string(),
133///     "Ok(4294967295)"
134/// );
135/// assert_eq!(
136///     Integer::try_from(4294967296.0).to_debug_string(),
137///     "Ok(4294967296)"
138/// );
139/// assert_eq!(
140///     Integer::try_from(1.0e100).to_debug_string(),
141///     "Ok(10000000000000000159028911097599180468360808563945281389781327557747838772170381060813\
142///     469985856815104)"
143/// );
144/// assert_eq!(
145///     Integer::try_from(123.1).to_debug_string(),
146///     "Err(FloatNonIntegerOrOutOfRange)"
147/// );
148/// assert_eq!(
149///     Integer::try_from(123.9).to_debug_string(),
150///     "Err(FloatNonIntegerOrOutOfRange)"
151/// );
152/// assert_eq!(
153///     Integer::try_from(123.5).to_debug_string(),
154///     "Err(FloatNonIntegerOrOutOfRange)"
155/// );
156/// assert_eq!(
157///     Integer::try_from(124.5).to_debug_string(),
158///     "Err(FloatNonIntegerOrOutOfRange)"
159/// );
160/// assert_eq!(
161///     Integer::try_from(-0.499).to_debug_string(),
162///     "Err(FloatNonIntegerOrOutOfRange)"
163/// );
164/// assert_eq!(
165///     Integer::try_from(-0.5).to_debug_string(),
166///     "Err(FloatNonIntegerOrOutOfRange)"
167/// );
168/// ```
169///
170/// # convertible_from
171/// ```
172/// use malachite_base::num::basic::traits::NegativeInfinity;
173/// use malachite_base::num::conversion::traits::ConvertibleFrom;
174/// use malachite_nz::integer::Integer;
175///
176/// assert_eq!(Integer::convertible_from(f64::NAN), false);
177/// assert_eq!(Integer::convertible_from(f64::INFINITY), false);
178/// assert_eq!(Integer::convertible_from(f64::NEGATIVE_INFINITY), false);
179/// assert_eq!(Integer::convertible_from(0.0), true);
180/// assert_eq!(Integer::convertible_from(-0.0), true);
181/// assert_eq!(Integer::convertible_from(123.0), true);
182/// assert_eq!(Integer::convertible_from(-123.0), true);
183/// assert_eq!(Integer::convertible_from(1.0e9), true);
184/// assert_eq!(Integer::convertible_from(4294967295.0), true);
185/// assert_eq!(Integer::convertible_from(4294967296.0), true);
186/// assert_eq!(Integer::convertible_from(1.0e100), true);
187/// assert_eq!(Integer::convertible_from(123.1), false);
188/// assert_eq!(Integer::convertible_from(123.9), false);
189/// assert_eq!(Integer::convertible_from(123.5), false);
190/// assert_eq!(Integer::convertible_from(124.5), false);
191/// assert_eq!(Integer::convertible_from(-0.499), false);
192/// assert_eq!(Integer::convertible_from(-0.5), false);
193/// ```
194pub mod from_primitive_float;
195/// Implementations of traits for converting a primitive integer to an
196/// [`Integer`](crate::integer::Integer).
197///
198/// The traits are [`From`], [`TryFrom`],
199/// [`ConvertibleFrom`](malachite_base::num::conversion::traits::ConvertibleFrom), and
200/// [`SaturatingFrom`](malachite_base::num::conversion::traits::SaturatingFrom).
201///
202/// # from
203/// ```
204/// use malachite_nz::integer::Integer;
205///
206/// assert_eq!(Integer::from(123u32).to_string(), "123");
207/// assert_eq!(Integer::from(-123i32).to_string(), "-123");
208/// ```
209pub mod from_primitive_int;
210/// Functions for constructing an [`Integer`](crate::integer::Integer) from two's complement
211/// [`Limb`](crate#limbs)s.
212pub mod from_twos_complement_limbs;
213/// An implementation of [`IsInteger`](malachite_base::num::conversion::traits::IsInteger), a trait
214/// for determining whether a number is an integer.
215///
216/// An [`Integer`](crate::integer::Integer) is always an integer.
217pub mod is_integer;
218/// Implementations of traits for converting an [`Integer`](crate::integer::Integer) to a
219/// [`Natural`](crate::natural::Natural).
220///
221/// The traits are [`TryFrom`],
222/// [`ConvertibleFrom`](malachite_base::num::conversion::traits::ConvertibleFrom), and
223/// [`SaturatingFrom`](malachite_base::num::conversion::traits::SaturatingFrom).
224pub mod natural_from_integer;
225/// Implementations of traits for converting an [`Integer`](crate::integer::Integer) to a primitive
226/// float.
227///
228/// The traits are [`TryFrom`]
229/// [`ConvertibleFrom`](malachite_base::num::conversion::traits::ConvertibleFrom), and
230/// [`RoundingFrom`](malachite_base::num::conversion::traits::RoundingFrom).
231///
232/// # rounding_from
233/// ```
234/// use core::cmp::Ordering::*;
235/// use core::str::FromStr;
236/// use malachite_base::num::conversion::traits::RoundingFrom;
237/// use malachite_base::rounding_modes::RoundingMode::*;
238/// use malachite_nz::integer::Integer;
239///
240/// assert_eq!(
241///     f32::rounding_from(&Integer::from_str("123").unwrap(), Exact),
242///     (123.0, Equal)
243/// );
244/// assert_eq!(
245///     f32::rounding_from(&Integer::from_str("1000000001").unwrap(), Floor),
246///     (1.0e9, Less)
247/// );
248/// assert_eq!(
249///     f32::rounding_from(&Integer::from_str("1000000001").unwrap(), Ceiling),
250///     (1.00000006e9, Greater)
251/// );
252/// assert_eq!(
253///     f32::rounding_from(&Integer::from_str("-1000000001").unwrap(), Floor),
254///     (-1.00000006e9, Less)
255/// );
256/// assert_eq!(
257///     f32::rounding_from(&Integer::from_str("-1000000001").unwrap(), Ceiling),
258///     (-1.0e9, Greater)
259/// );
260/// assert_eq!(
261///     f32::rounding_from(
262///         &Integer::from_str("10000000000000000000000000000000000000000000000000000").unwrap(),
263///         Nearest
264///     ),
265///     (3.4028235e38, Less)
266/// );
267/// ```
268///
269/// # try_from
270/// ```
271/// use core::str::FromStr;
272/// use malachite_nz::integer::conversion::primitive_float_from_integer::*;
273/// use malachite_nz::integer::Integer;
274///
275/// assert_eq!(f32::try_from(&Integer::from_str("123").unwrap()), Ok(123.0));
276/// assert_eq!(
277///     f32::try_from(&Integer::from_str("-1000000000").unwrap()),
278///     Ok(-1.0e9)
279/// );
280/// assert_eq!(
281///     f32::try_from(&Integer::from_str("1000000001").unwrap()),
282///     Err(PrimitiveFloatFromIntegerError)
283/// );
284/// assert_eq!(
285///     f32::try_from(
286///         &Integer::from_str("-10000000000000000000000000000000000000000000000000000").unwrap()
287///     ),
288///     Err(PrimitiveFloatFromIntegerError)
289/// );
290/// ```
291///
292/// # convertible_from
293/// ```
294/// use core::str::FromStr;
295/// use malachite_base::num::conversion::traits::ConvertibleFrom;
296/// use malachite_nz::integer::Integer;
297///
298/// assert_eq!(
299///     f32::convertible_from(&Integer::from_str("123").unwrap()),
300///     true
301/// );
302/// assert_eq!(
303///     f32::convertible_from(&Integer::from_str("-1000000000").unwrap()),
304///     true
305/// );
306/// assert_eq!(
307///     f32::convertible_from(&Integer::from_str("1000000001").unwrap()),
308///     false
309/// );
310/// assert_eq!(
311///     f32::convertible_from(
312///         &Integer::from_str("-10000000000000000000000000000000000000000000000000000").unwrap()
313///     ),
314///     false
315/// );
316/// ```
317pub mod primitive_float_from_integer;
318/// Implementations of traits for converting an [`Integer`](crate::integer::Integer) to a primitive
319/// integer.
320///
321/// The traits are [`TryFrom`],
322/// [`ConvertibleFrom`](malachite_base::num::conversion::traits::ConvertibleFrom),
323/// [`OverflowingFrom`](malachite_base::num::conversion::traits::OverflowingFrom),
324/// [`SaturatingFrom`](malachite_base::num::conversion::traits::SaturatingFrom), and
325/// [`WrappingFrom`](malachite_base::num::conversion::traits::WrappingFrom).
326///
327/// # try_from
328/// ```
329/// use malachite_base::num::arithmetic::traits::Pow;
330/// use malachite_nz::integer::conversion::primitive_int_from_integer::{
331///     SignedFromIntegerError, UnsignedFromIntegerError,
332/// };
333/// use malachite_nz::integer::Integer;
334///
335/// assert_eq!(u32::try_from(&Integer::from(123)), Ok(123));
336/// assert_eq!(
337///     u32::try_from(&Integer::from(-123)),
338///     Err(UnsignedFromIntegerError)
339/// );
340/// assert_eq!(
341///     u32::try_from(&Integer::from(10u32).pow(12)),
342///     Err(UnsignedFromIntegerError)
343/// );
344/// assert_eq!(
345///     u32::try_from(&-Integer::from(10u32).pow(12)),
346///     Err(UnsignedFromIntegerError)
347/// );
348///
349/// assert_eq!(i32::try_from(&Integer::from(123)), Ok(123));
350/// assert_eq!(i32::try_from(&Integer::from(-123)), Ok(-123));
351/// assert_eq!(
352///     i32::try_from(&Integer::from(10u32).pow(12)),
353///     Err(SignedFromIntegerError)
354/// );
355/// assert_eq!(
356///     i32::try_from(&-Integer::from(10u32).pow(12)),
357///     Err(SignedFromIntegerError)
358/// );
359/// ```
360///
361/// # wrapping_from
362/// ```
363/// use malachite_base::num::arithmetic::traits::Pow;
364/// use malachite_base::num::conversion::traits::WrappingFrom;
365/// use malachite_nz::integer::Integer;
366///
367/// assert_eq!(u32::wrapping_from(&Integer::from(123)), 123);
368/// assert_eq!(u32::wrapping_from(&Integer::from(-123)), 4294967173);
369/// assert_eq!(
370///     u32::wrapping_from(&Integer::from(10u32).pow(12)),
371///     3567587328
372/// );
373/// assert_eq!(
374///     u32::wrapping_from(&-Integer::from(10u32).pow(12)),
375///     727379968
376/// );
377///
378/// assert_eq!(i32::wrapping_from(&Integer::from(123)), 123);
379/// assert_eq!(i32::wrapping_from(&Integer::from(-123)), -123);
380/// assert_eq!(
381///     i32::wrapping_from(&Integer::from(10u32).pow(12)),
382///     -727379968
383/// );
384/// assert_eq!(
385///     i32::wrapping_from(&-Integer::from(10u32).pow(12)),
386///     727379968
387/// );
388/// ```
389///
390/// # saturating_from
391/// ```
392/// use malachite_base::num::arithmetic::traits::Pow;
393/// use malachite_base::num::conversion::traits::SaturatingFrom;
394/// use malachite_nz::integer::Integer;
395///
396/// assert_eq!(u32::saturating_from(&Integer::from(123)), 123);
397/// assert_eq!(u32::saturating_from(&Integer::from(-123)), 0);
398/// assert_eq!(
399///     u32::saturating_from(&Integer::from(10u32).pow(12)),
400///     u32::MAX
401/// );
402/// assert_eq!(u32::saturating_from(&-Integer::from(10u32).pow(12)), 0);
403///
404/// assert_eq!(i32::saturating_from(&Integer::from(123)), 123);
405/// assert_eq!(i32::saturating_from(&Integer::from(-123)), -123);
406/// assert_eq!(
407///     i32::saturating_from(&Integer::from(10u32).pow(12)),
408///     2147483647
409/// );
410/// assert_eq!(
411///     i32::saturating_from(&-Integer::from(10u32).pow(12)),
412///     -2147483648
413/// );
414/// ```
415///
416/// # overflowing_from
417/// ```
418/// use malachite_base::num::arithmetic::traits::Pow;
419/// use malachite_base::num::conversion::traits::OverflowingFrom;
420/// use malachite_nz::integer::Integer;
421///
422/// assert_eq!(u32::overflowing_from(&Integer::from(123)), (123, false));
423/// assert_eq!(
424///     u32::overflowing_from(&Integer::from(-123)),
425///     (4294967173, true)
426/// );
427/// assert_eq!(
428///     u32::overflowing_from(&Integer::from(10u32).pow(12)),
429///     (3567587328, true)
430/// );
431/// assert_eq!(
432///     u32::overflowing_from(&-Integer::from(10u32).pow(12)),
433///     (727379968, true)
434/// );
435///
436/// assert_eq!(i32::overflowing_from(&Integer::from(123)), (123, false));
437/// assert_eq!(i32::overflowing_from(&Integer::from(-123)), (-123, false));
438/// assert_eq!(
439///     i32::overflowing_from(&Integer::from(10u32).pow(12)),
440///     (-727379968, true)
441/// );
442/// assert_eq!(
443///     i32::overflowing_from(&-Integer::from(10u32).pow(12)),
444///     (727379968, true)
445/// );
446/// ```
447///
448/// # convertible_from
449/// ```
450/// use malachite_base::num::arithmetic::traits::Pow;
451/// use malachite_base::num::conversion::traits::ConvertibleFrom;
452/// use malachite_nz::integer::Integer;
453///
454/// assert_eq!(u32::convertible_from(&Integer::from(123)), true);
455/// assert_eq!(u32::convertible_from(&Integer::from(-123)), false);
456/// assert_eq!(u32::convertible_from(&Integer::from(10u32).pow(12)), false);
457/// assert_eq!(u32::convertible_from(&-Integer::from(10u32).pow(12)), false);
458///
459/// assert_eq!(i32::convertible_from(&Integer::from(123)), true);
460/// assert_eq!(i32::convertible_from(&Integer::from(-123)), true);
461/// assert_eq!(i32::convertible_from(&Integer::from(10u32).pow(12)), false);
462/// assert_eq!(i32::convertible_from(&-Integer::from(10u32).pow(12)), false);
463/// ```
464pub mod primitive_int_from_integer;
465/// Implementations of traits for conversions between Python integers and
466/// [`Integer`](crate::integer::Integer)s using [pyo3](https://pyo3.rs/).
467pub mod pyo3;
468/// Implementations of traits for serialization and deserialization using
469/// [serde](https://serde.rs/).
470pub mod serde;
471/// Implementations of traits for converting [`Integer`](crate::integer::Integer)s to and from
472/// [`String`]s.
473pub mod string;
474/// Functions for extracting two's complement [`Limb`](crate#limbs)s from an
475/// [`Integer`](crate::integer::Integer).
476pub mod to_twos_complement_limbs;
malachite_nz/integer/conversion/mod.rs

malachite_nz/integer/conversion/
mod.rs
