rusty_perm/
lib.rs

1//! Rusty permutation that supports `no-std` and compile-time checked size.
2//!
3//! ## Cargo features
4//!
5//! To import this crate to your project,
6//!
7//! ```toml
8//! [dependencies]
9//! rusty-perm = "0.2"
10//! ```
11//!
12//! It has the following cargo features.
13//! - **std** (default): enable the standard library.
14//! - **rand** (default): enable random sampling of permutation.
15//!
16//! To restrict the crate to `no_std`, you can disable the default features.
17//!
18//! ```toml
19//! [dependencies]
20//! rusty-perm = { version = "0.2", default-features = false }
21//! ```
22//!
23//! ## Import this crate
24//!
25//! To import members from this crate,
26//! ```rust
27//! use rusty_perm::{prelude::*, PermD, PermS};
28//! ```
29//!
30//! Both `PermD` and `PermS` represent permutations, except that
31//! `PermS` has an embedded compile-time size in type signature. The static size
32//! prevents from applying permutation on arrays of wrong sizes in compile-time, and saves
33//! some runtime overheads.
34//!
35//! ## Identity
36//! The identity permutation can be constructed with static or dynamic size.
37//!
38//! ```rust
39//! use rusty_perm::{PermD, PermS};
40//! let perm1 = PermS::<10>::identity();
41//! let perm2 = PermD::identity(10);
42//! ```
43//!
44//! ## Build by sorting slices and arrays
45//!
46//! It can extracts the permutation by sorting an array.
47//!
48//! ```rust
49//! use rusty_perm::{prelude::*, PermS};
50//!
51//! // `perm` is an operator that maps [9, 6, -1, 4] to [-1, 4, 6, 9].
52//! let perm = PermS::from_sort(&[9, 6, -1, 4]);
53//!
54//! // Apply same permutation on another array
55//! let mut array = [1, 2, 3, 4];
56//! perm.apply(&mut array);
57//! assert_eq!(array, [3, 4, 2, 1]);
58//! ```
59//!
60//! You can sort with custom comparing or key function by
61//! [from_sort_by](crate::PermFromSorting::from_sort_by),
62//! [from_sort_by_key](crate::PermFromSorting::from_sort_by_key) and
63//! [from_sort_by_cached_key](crate::PermFromSorting::from_sort_by_cached_key).
64//!
65//! ```rust
66//! use rusty_perm::{prelude::*, PermS};
67//!
68//! // `perm` is an operator that maps [9, 6, -1, 4] to [9, 6, 4, -1].
69//! let perm = PermS::from_sort_by_key(&[9, 6, -1, 4], |val| -val);
70//!
71//! // Apply same permutation on another array
72//! let mut array = [1, 2, 3, 4];
73//! perm.apply(&mut array);
74//! assert_eq!(array, [1, 2, 4, 3]);
75//! ```
76//!
77//! ## Build by indices
78//! The permutation can be constructed by demonstrating the sorted indices.
79//!
80//! ```rust
81//! use rusty_perm::{prelude::*, PermD};
82//! let perm = PermD::from_indices([2, 0, 1]).unwrap();
83//!
84//! let mut array = [-9, -5, 3];
85//! perm.apply(&mut array);
86//! assert_eq!(array, [3, -9, -5]);
87//! ```
88//!
89//! ## Inverse and composition
90//! The example demonstrates the inverse and composition of permutations.
91//!
92//! ```rust
93//! use rusty_perm::{prelude::*, PermD, PermS};
94//!
95//! // Construct the permutation, its inverse and compose them
96//! let perm = PermS::from_indices([2, 0, 1]).unwrap();
97//! let inverse = perm.inverse();
98//! let composition = &inverse * &perm;
99//!
100//! // Check that composition with its inverse is identity
101//! assert_eq!(PermD::identity(3), composition);
102//! ```
103
104#![cfg_attr(not(feature = "std"), no_std)]
105
106/// Re-export of common traits.
107pub mod prelude {
108    pub use super::{
109        apply::PermApply, from_indices::PermFromIndices, from_sorting::PermFromSorting,
110        perm_trait::Permutation, product::PermProduct,
111    };
112}
113
114mod apply;
115mod common;
116mod from_indices;
117mod from_sorting;
118mod perm_trait;
119mod perm_type;
120mod product;
121mod rand;
122pub mod size;
123
124pub use apply::*;
125pub use from_indices::*;
126pub use from_sorting::*;
127pub use perm_trait::*;
128pub use perm_type::*;
129pub use product::*;
rusty_perm/lib.rs

rusty_perm/
lib.rs
