finitelib/lib.rs
1//! `finitelib` is a library for advanced maths over finite groups, fields,
2//! their extensions, multi precision operations and related things.
3//!
4//! At the moment the library supports:
5//! * Finite groups
6//! * Finite fields (prime - `GF(p)`, splitting - `GF(p^m)`, binary - `GF(2^m)`, Montgomery representation)
7//! * Euclidean rings (including modular operations)
8//! * Polynomials
9//! * Multi precision operations over unsigned integers
10//! * Converting
11//! * Formatting
12//! * Basic operations: addition, subtraction, product, division, bitwise operations
13//! * Prime numbers: Fermat test, Miller-Rabin test, Legendre symbol, Tonelli–Shanks algorithm
14//!
15//! ## Usage
16//!
17//! Installation command:
18//!
19//! ```sh
20//! cargo add finitelib
21//! ```
22//!
23//! ## Basic example
24//!
25//! ```rust
26//! use finitelib::prelude::*;
27//! use finitelib::gf::prime::Prime as GF;
28//!
29//! // Define 256-bit unsigned integer type
30//! type U256 = bigi_of_bits!(256);
31//!
32//! // Define an Euclidean ring over U256, that contains the correct basic
33//! // math operations like addition, multiplication, Euclidean extended
34//! // algorithm and so on.
35//! let R256 = bigi_ring_for_bigi!(U256);
36//!
37//! // Define a 256-bit prime number
38//! let p = U256::from_decimal("67096435317933606252190858377894931905843553631817376158639971807689379094463");
39//!
40//! // Define a finite field `GF(p)` with the prime characteristic `p`
41//! let gf = GF::new(R256, p);
42//!
43//! // Define two arbitrary numbers
44//! let a = U256::from(3);
45//! let b = U256::from(2);
46//!
47//! // Perform division a / b inside the field
48//! let c = gf.div(&a, &b).unwrap();
49//!
50//! // Print the result as a decimal string
51//! println!("{:?}", c.to_decimal());
52//!
53//! // Perform multiplication
54//! let d = gf.mul(&c, &b);
55//!
56//! // Since multiplication is opposite to division `d` must be equal to `a`
57//! assert_eq!(d, a);
58//! ```
59
60#![warn(missing_docs)]
61#![feature(test)]
62#![feature(bigint_helper_methods)]
63
64extern crate test;
65
66pub mod utils;
67pub mod signed;
68pub mod group;
69pub mod field;
70pub mod ring;
71pub mod bigi;
72pub mod polynomial;
73pub mod complex;
74pub mod common;
75pub mod gf;
76pub mod prelude;