use-combinatorics

Scaffolded Pre-1.0 checked-counting crate with canonical RustUse-hosted API docs.

use-combinatorics is the RustUse crate for checked counting in u128: factorials, permutations, and combinations with explicit error values instead of wrapping arithmetic.

Purpose

The crate covers focused combinatorics helpers without forcing users through a broader numeric or symbolic dependency surface.

Current scope

factorial(n) for checked factorials
permutations(n, k) for ordered selections
combinations(n, k) for unordered selections
explicit CombinatoricsError values for invalid input and overflow
a narrow API surface that stays useful on its own

Intended role in the set

use-combinatorics sits alongside use-geometry and use-math as a narrower crate track for discrete workflows.

Use it when checked counting is the only math support a project needs. Reach for use-math when the facade crate becomes the clearer integration point.

API docs

RustUse-hosted API docs are live at the stable use-combinatorics API route.

Copyable source

Copy use-combinatorics into your codebase

Copy the full checked-counting crate into your codebase or inspect the individual files behind the current public use-combinatorics surface.

Browse files

Cargo.toml

8 files TOML

Browse crate files

            [package]
name = "use-combinatorics"
description = "Utility-first checked combinatorics helpers for RustUse"
publish = true
authors.workspace = true
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true
rust-version.workspace = true
readme = "README.md"
homepage = "https://github.com/RustUse/use-math"
documentation = "https://docs.rs/use-combinatorics"
keywords = ["math", "combinatorics", "counting", "factorial", "binomial"]
categories = ["mathematics", "algorithms"]

[dev-dependencies]
proptest.workspace = true

[lints]
workspace = true

Surface at a glance

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 }`

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

Examples

Basic checked counting

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

assert_eq!(factorial(5).expect("fits in u128"), 120);
assert_eq!(permutations(5, 3).expect("valid selection"), 60);
assert_eq!(combinations(5, 2).expect("valid selection"), 10);
assert_eq!(combinations(52, 5).expect("valid selection"), 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, combinations, factorial};

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

Error and overflow model

The crate keeps invalid inputs and arithmetic overflow explicit instead of saturating or wrapping.

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`

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

Status

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