dashu_int/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// This crate is a for of the `ibig` crate. The original LICENSE is included in the
17// [NOTICE.md](../NOTICE.md)
18
19//! A big integer library with good performance.
20//!
21//! The library implements efficient large integer arithmetic in pure Rust.
22//!
23//! The two main integer types are [UBig] (for unsigned integers) and [IBig] (for signed integers).
24//!
25//! Modular arithmetic is supported by the module [modular]. Some utilities for fast division is provided in the module [fast_div].
26//!
27//! To construct big integers from literals, please use the [`dashu-macro`](https://docs.rs/dashu-macros/latest/dashu_macros/)
28//! crate for your convenience.
29//!
30//! # Examples
31//!
32//! ```
33//! # use dashu_base::ParseError;
34//! use dashu_int::{IBig, fast_div::ConstDivisor, UBig};
35//!
36//! let a = UBig::from(12345678u32);
37//! let b = IBig::from(-0x10ff);
38//! let c = IBig::from_str_radix("-azz", 36).unwrap();
39//! let d: UBig = "15033211231241234523452345345787".parse()?;
40//! let e = 2 * &b - 1;
41//! let f = a * b.pow(10);
42//!
43//! assert_eq!(e, IBig::from(-0x21ff));
44//! assert_eq!(c.to_string(), "-14255");
45//! assert_eq!(
46//! f.in_radix(16).to_string(),
47//! "1589bda8effbfc495d8d73c83d8b27f94954e"
48//! );
49//! assert_eq!(
50//! format!("hello {:#x}", d % 0xabcd_1234_1341_3245_1345u128),
51//! "hello 0x1a7e7c487267d2658a93"
52//! );
53//!
54//! let ring = ConstDivisor::new(UBig::from(10000u32));
55//! let x = ring.reduce(12345);
56//! let y = ring.reduce(55443);
57//! assert_eq!(format!("{}", x - y), "6902 (mod 10000)");
58//! # Ok::<(), ParseError>(())
59//! ```
60//!
61//! # Optional dependencies
62//!
63//! * `std` (*default*): for `std::error::Error` and some internal usages of `std` functions.
64//! * `num-traits` (*default*): support traits from crate `num-traits`.
65//! * `num-integer` (*default*): support traits from crate `num-integer`.
66//! * `num-order` (*default*): support traits from crate `num-order`.
67//! * `rand` (*default*): support random number generation based on crate `rand`.
68//! * `serde`: support serialization and deserialization based on crate `serde`.
69//! * `zeroize`: support traits from crate `zeroize`
70
71#![cfg_attr(not(feature = "std"), no_std)]
72#![deny(missing_docs)]
73#![deny(clippy::dbg_macro)]
74#![deny(clippy::undocumented_unsafe_blocks)]
75#![deny(clippy::let_underscore_must_use)]
76// NOTE: clippy::allow_attributes_without_reason is intentionally not enabled. Satisfying it
77// requires a `reason = "..."` on every #[allow(..)] (or an #[expect(..)]), both of which were
78// stabilized in Rust 1.81 — but the crate MSRV is 1.68. Revisit once the MSRV reaches >= 1.81.
79
80extern crate alloc;
81
82pub use crate::{ibig::IBig, ubig::UBig};
83pub use dashu_base::Sign;
84
85/// The primitive integer type used to construct the big integers, guaranteed to be
86/// a rust built-in unsigned integer type.
87///
88/// The big integers is interally represented as an array of [Word]s, so convert
89/// integers from and into [Word]s are efficient.
90///
91/// The size of a [Word] is usually the same as [usize], but it's not guaranteed.
92/// It's dependent on the target architecture.
93pub type Word = arch::word::Word;
94
95/// The primitive integer type that has exactly double the size of [Word].
96pub type DoubleWord = arch::word::DoubleWord;
97
98mod add;
99mod add_ops;
100mod arch;
101mod bits;
102mod buffer;
103mod cmp;
104mod convert;
105mod div;
106mod div_const;
107mod div_ops;
108mod error;
109pub mod fmt;
110mod gcd;
111mod gcd_ops;
112mod helper_macros;
113mod ibig;
114mod iter;
115mod log;
116mod math;
117mod memory;
118pub mod modular;
119pub mod monty;
120mod mul;
121mod mul_ops;
122pub mod ops;
123mod parse;
124mod pow;
125mod primitive;
126mod radix;
127mod remove;
128mod repr;
129mod root;
130mod root_ops;
131mod shift;
132mod shift_ops;
133mod sign;
134mod sqr;
135mod third_party;
136mod ubig;
137
138// All the public items from third_party will be exposed
139#[allow(unused_imports)]
140pub use third_party::*;
141
142// Re-export types for fast division
143/// Prepared divisor types for fast division
144pub mod fast_div {
145 pub use super::div_const::ConstDivisor;
146}