Crate use_combinatorics 

use-combinatorics

Checked combinatorics helpers for explicit counting in `u128`.
Factorials, permutations, and combinations with structured errors instead of wrapping arithmetic.

Surface · When to use it · Installation · Examples · Errors · Scope

use-combinatorics provides overflow-aware counting helpers as focused utility building blocks for common tasks such as factorials, ordered selections, and unordered selections. The crate stays intentionally small: explicit inputs, exact results when they fit in u128, and explicit error values when they do not.

Factorials factorial(n) returns n! with checked u128 arithmetic.

Permutations permutations(n, k) counts ordered selections and rejects k > n.

Combinations combinations(n, k) counts unordered selections and cancels factors before multiply where possible.

What this crate provides

Helper	Meaning	Failure mode
factorial(n)	Counts total orderings of n items	FactorialOverflow(n) when the exact result no longer fits in u128
permutations(n, k)	Counts ordered selections of size k from n	KExceedsN { n, k } or PermutationOverflow { n, k }
combinations(n, k)	Counts unordered selections of size k from n	KExceedsN { n, k } or CombinationOverflow { n, k }

If you need to…	Start here
Count without bringing in geometry APIs	use-combinatorics
Keep overflow explicit instead of saturating or wrapping	Any public helper in this crate
Count actual arrangements or subsets, not just totals	Another crate or your own domain logic
Work past u128 limits with big integers	Another crate or a future extension

When to use it directly

Choose use-combinatorics directly when checked counting is the only math support you need, or when you want the narrowest possible dependency and API surface.

Scenario	Use use-combinatorics directly?	Why
You only need factorials, permutations, or combinations	Yes	The crate is tiny and purpose-built
You want explicit overflow errors in application logic	Yes	All helpers return Result<u128, CombinatoricsError>
You also need geometry types and helpers	Usually no	use-math may be the cleaner integration surface
You need arbitrary-precision combinatorics	No	This crate intentionally stops at checked u128 arithmetic

Installation

[dependencies]
use-combinatorics = "0.0.1"

Quick examples

Basic checked counting

use use_combinatorics::{combinations, factorial, permutations};

assert_eq!(factorial(5)?, 120);
assert_eq!(permutations(5, 3)?, 60);
assert_eq!(combinations(5, 2)?, 10);
assert_eq!(combinations(52, 5)?, 2_598_960);

Invalid input stays explicit

use use_combinatorics::{CombinatoricsError, combinations, permutations};

assert_eq!(
        combinations(3, 4),
        Err(CombinatoricsError::KExceedsN { n: 3, k: 4 })
);
assert_eq!(
        permutations(3, 4),
        Err(CombinatoricsError::KExceedsN { n: 3, k: 4 })
);

Overflow is reported, not hidden

use use_combinatorics::{CombinatoricsError, factorial, combinations};

assert_eq!(factorial(35), Err(CombinatoricsError::FactorialOverflow(35)));
assert_eq!(
        combinations(150, 75),
        Err(CombinatoricsError::CombinationOverflow { n: 150, k: 75 })
);

Error and overflow model

All public helpers return Result<u128, CombinatoricsError> so invalid inputs and arithmetic overflow remain visible to callers.

Concern	Behavior
Invalid selection size	k > n returns KExceedsN { n, k }
Factorial growth	factorial fits through n = 34, then returns FactorialOverflow
Permutation growth	Overflow depends on both n and k, returned as PermutationOverflow
Combination growth	Overflow depends on both n and k, returned as CombinationOverflow

[!NOTE] combinations cancels common factors before multiplying so more exact results fit in u128 without changing the mathematical answer.

Scope

• Small APIs are preferred over broad trait-heavy abstractions.
• Counting helpers stay explicit about invalid inputs and arithmetic overflow.
• Big-integer fallbacks are intentionally out of scope for now.
• Enumerating actual arrangements or subsets is intentionally out of scope.
• Probability distributions and random sampling helpers are intentionally deferred.
• Additional combinatorics utilities can grow incrementally from this base.

Status

use-combinatorics is a concrete pre-1.0 crate in the RustUse docs surface. The API remains intentionally small, and the RustUse-hosted generated rustdocs stay canonical while external crates.io and docs.rs pages remain staged. Small combinatorics helpers for RustUse.

Re-exports

pub use counting::combinations;

pub use counting::factorial;

pub use counting::permutations;

pub use error::CombinatoricsError;

Modules

counting

error

prelude