dashu_ratio/lib.rs
1// Copyright (c) 2022 Jacob Zhong
2//
3// Licensed under either of
4//
5// * Apache License, Version 2.0
6// (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
7// * MIT license
8// (LICENSE-MIT or https://opensource.org/licenses/MIT)
9//
10// at your option.
11//
12// Unless you explicitly state otherwise, any contribution intentionally submitted
13// for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
14// dual licensed as above, without any additional terms or conditions.
15
16//! A big rational library with good performance.
17//!
18//! The library implements efficient arithmetic and conversion functions in pure Rust.
19//!
20//! The two main rational types are [RBig] and [Relaxed]. Both of them represent the
21//! rational number as a pair of integers (numerator and denominator) and their APIs
22//! are mostly the same. However only with [RBig], the numerator and denominator are
23//! reduced so that they don't have common divisors other than one. Therefore, [Relaxed]
24//! sometimes can be much faster if you don't care about a reduced representation of
25//! the rational number. However, benchmarking is always recommended before choosing
26//! which representation to use.
27//!
28//! To construct big rationals from literals, please use the [`dashu-macro`](https://docs.rs/dashu-macros/latest/dashu_macros/)
29//! crate for your convenience.
30//!
31//! # Examples
32//!
33//! ```
34//! # use dashu_base::ParseError;
35//! use dashu_int::{IBig, UBig};
36//! use dashu_ratio::{RBig, Relaxed};
37//!
38//! let a = RBig::from_parts((-12).into(), 34u8.into());
39//! let b = RBig::from_str_radix("-azz/ep", 36).unwrap();
40//! let c = RBig::try_from(3.1415926f32).unwrap(); // c = 6588397 / 2097152 (lossless)
41//! let c2 = RBig::simplest_from_f32(3.1415926).unwrap(); // c2 = 51808 / 16491
42//! assert_eq!(c2.numerator(), &IBig::from(51808));
43//!
44//! assert_eq!(c.to_string(), "6588397/2097152");
45//! let d = RBig::simplest_from_f32(22./7.).unwrap();
46//! assert_eq!(d.to_string(), "22/7"); // round trip to the original literal
47//!
48//! // for Relaxed, only the common divisor 2 is removed
49//! let e: Relaxed = "-3228/1224".parse()?; // d = -807 / 306
50//! assert_eq!(e.numerator(), &IBig::from(-807));
51//! let f: RBig = e.clone().canonicalize(); // e = -269 / 102
52//! assert_eq!(f.numerator(), &IBig::from(-269));
53//! # Ok::<(), ParseError>(())
54//! ```
55
56#![cfg_attr(not(feature = "std"), no_std)]
57
58mod add;
59mod cmp;
60mod convert;
61mod div;
62mod error;
63mod fmt;
64mod helper_macros;
65mod mul;
66pub mod ops;
67mod parse;
68mod rbig;
69mod repr;
70mod round;
71mod sign;
72mod simplify;
73mod third_party;
74
75// All the public items from third_party will be exposed
76#[allow(unused_imports)]
77pub use third_party::*;
78
79pub use rbig::{RBig, Relaxed};
80
81#[doc(hidden)]
82pub use dashu_int::Word; // for macros