Skip to content

Commit

Permalink
fix(README): inline documentation to fix inner links to modules
Browse files Browse the repository at this point in the history
  • Loading branch information
@samueltardieu
samueltardieu committed Feb 12, 2024
1 parent fb66d9a commit 279305d
Show file tree
Hide file tree
Showing 3 changed files with 95 additions and 65 deletions.
64 changes: 1 addition & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,41 +4,7 @@
[![Documentation](https://docs.rs/pathfinding/badge.svg)](https://docs.rs/pathfinding)
[![License: Apache-2.0/MIT](https://img.shields.io/crates/l/pathfinding.svg)](#license)

This crate implements several pathfinding, flow, and graph algorithms in [Rust][Rust].

## Algorithms

The algorithms are generic over their arguments.

### Directed graphs

- [A*](directed/astar/index.html): find the shortest path in a weighted graph using an heuristic to guide the process ([⇒ Wikipedia][A*])
- [BFS](directed/bfs): explore nearest successors first, then widen the search ([⇒ Wikipedia][BFS])
- [Brent](directed/cycle_detection/index.html): find a cycle in an infinite sequence ([⇒ Wikipedia][Brent])
- [DFS](directed/dfs/index.html): explore a graph by going as far as possible, then backtrack ([⇒ Wikipedia][DFS])
- [Dijkstra](directed/dijkstra/index.html): find the shortest path in a weighted graph ([⇒ Wikipedia][Dijkstra])
- [Edmonds Karp](directed/edmonds_karp/index.html): find the maximum flow in a weighted graph ([⇒ Wikipedia][Edmonds Karp])
- [Floyd](directed/cycle_detection/index.html): find a cycle in an infinite sequence ([⇒ Wikipedia][Floyd])
- [Fringe](directed/fringe/index.html): find the shortest path in a weighted graph using an heuristic to guide the process ([⇒ Wikipedia][Fringe])
- [IDA*](directed/idastar/index.html): explore longer and longer paths in a weighted graph at the cost of multiple similar examinations ([⇒ Wikipedia][IDA*])
- [IDDFS](directed/iddfs/index.html): explore longer and longer paths in an unweighted graph at the cost of multiple similar examinations ([⇒ Wikipedia][IDDFS])
- [strongly connected components](directed/strongly_connected_components/index.html): find strongly connected components in a directed graph ([⇒ Wikipedia][Strongly connected components])
- [topological sorting](directed/topological_sort/index.html): find an acceptable topological order in a directed graph ([⇒ Wikipedia][Topological sorting])
- [Yen](directed/yen/index.html): find k-shortest paths using Dijkstra ([⇒ Wikipedia][Yen])

### Undirected graphs

- [connected components](undirected/connected_components/index.html): find disjoint connected sets of vertices ([⇒ Wikipedia][Connected components])
- [Kruskal](undirected/kruskal/index.html): find a minimum-spanning-tree ([⇒ Wikipedia][Kruskal])

### Matching

- [Kuhn-Munkres](kuhn_munkres/index.html) (Hungarian algorithm): find the maximum (or minimum) matching in a weighted bipartite graph ([⇒ Wikipedia][Kuhn-Munkres])

### Miscellaneous structures

- A [`Grid`](grid/index.html) type representing a rectangular grid in which vertices can be added or removed, with automatic creation of edges between adjacent vertices.
- A [`Matrix`](matrix/index.html) type to store data of arbitrary types, with neighbour-aware methods.
This crate implements several pathfinding, flow, and graph algorithms in [Rust][Rust]. The algorithms are generic over their arguments. See [the documentation](https://docs.rs/pathfinding) for more information about the various algorithms.

## Using this crate

Expand Down Expand Up @@ -79,16 +45,6 @@ let result = bfs(&Pos(1, 1), |p| p.successors(), |p| *p == GOAL);
assert_eq!(result.expect("no path found").len(), 5);
```

## Note on floating-point types

Several algorithms require that the numerical types used to describe
edge weights implement `Ord`. If you wish to use Rust built-in
floating-point types (such as `f32`) that implement `PartialOrd`
in this context, you can wrap them into compliant types using the
[ordered-float](https://crates.io/crates/ordered-float) crate.

The minimum supported Rust version (MSRV) is Rust 1.70.0.

## License

This code is released under a dual Apache 2.0 / MIT free software license.
Expand Down Expand Up @@ -116,21 +72,3 @@ This repository uses the [conventional commits](https://www.conventionalcommits.

If a pull-request should automatically close an open issue, please
include "Fix #xxx# or "Close #xxx" in the pull-request cover-letter.

[A*]: https://en.wikipedia.org/wiki/A*_search_algorithm
[BFS]: https://en.wikipedia.org/wiki/Breadth-first_search
[Brent]: https://en.wikipedia.org/wiki/Cycle_detection#Brent's_algorithm
[Connected components]: https://en.wikipedia.org/wiki/Connected_component_(graph_theory)
[DFS]: https://en.wikipedia.org/wiki/Depth-first_search
[Dijkstra]: https://en.wikipedia.org/wiki/Dijkstra's_algorithm
[Edmonds Karp]: https://en.wikipedia.org/wiki/Edmonds–Karp_algorithm
[Floyd]: https://en.wikipedia.org/wiki/Cycle_detection#Floyd's_tortoise_and_hare
[Fringe]: https://en.wikipedia.org/wiki/Fringe_search
[Kruskal]: https://en.wikipedia.org/wiki/Kruskal's_algorithm
[IDA*]: https://en.wikipedia.org/wiki/Iterative_deepening_A*
[IDDFS]: https://en.wikipedia.org/wiki/Iterative_deepening_depth-first_search
[Kuhn-Munkres]: https://en.wikipedia.org/wiki/Hungarian_algorithm
[Rust]: https://rust-lang.org/
[Strongly connected components]: https://en.wikipedia.org/wiki/Strongly_connected_component
[Topological sorting]: https://en.wikipedia.org/wiki/Topological_sorting
[Yen]: https://en.wikipedia.org/wiki/Yen's_algorithm
94 changes: 93 additions & 1 deletion src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,97 @@
#![forbid(missing_docs)]
#![doc = include_str!("../README.md")]
//! # pathfinding
//!
//! [![Current Version](https://img.shields.io/crates/v/pathfinding.svg)](https://crates.io/crates/pathfinding)
//! [![Documentation](https://docs.rs/pathfinding/badge.svg)](https://docs.rs/pathfinding)
//! [![License: Apache-2.0/MIT](https://img.shields.io/crates/l/pathfinding.svg)](#license)
//!
//! This crate implements several pathfinding, flow, and graph algorithms in [Rust][Rust].
//!
//! ## Algorithms
//!
//! The algorithms are generic over their arguments.
//!
//! ### Directed graphs
//!
//! - [A*](directed/astar/index.html): find the shortest path in a weighted graph using an heuristic to guide the process ([⇒ Wikipedia][A*])
//! - [BFS](directed/bfs/index.html): explore nearest successors first, then widen the search ([⇒ Wikipedia][BFS])
//! - [Brent](directed/cycle_detection/index.html): find a cycle in an infinite sequence ([⇒ Wikipedia][Brent])
//! - [DFS](directed/dfs/index.html): explore a graph by going as far as possible, then backtrack ([⇒ Wikipedia][DFS])
//! - [Dijkstra](directed/dijkstra/index.html): find the shortest path in a weighted graph ([⇒ Wikipedia][Dijkstra])
//! - [Edmonds Karp](directed/edmonds_karp/index.html): find the maximum flow in a weighted graph ([⇒ Wikipedia][Edmonds Karp])
//! - [Floyd](directed/cycle_detection/index.html): find a cycle in an infinite sequence ([⇒ Wikipedia][Floyd])
//! - [Fringe](directed/fringe/index.html): find the shortest path in a weighted graph using an heuristic to guide the process ([⇒ Wikipedia][Fringe])
//! - [IDA*](directed/idastar/index.html): explore longer and longer paths in a weighted graph at the cost of multiple similar examinations ([⇒ Wikipedia][IDA*])
//! - [IDDFS](directed/iddfs/index.html): explore longer and longer paths in an unweighted graph at the cost of multiple similar examinations ([⇒ Wikipedia][IDDFS])
//! - [strongly connected components](directed/strongly_connected_components/index.html): find strongly connected components in a directed graph ([⇒ Wikipedia][Strongly connected components])
//! - [topological sorting](directed/topological_sort/index.html): find an acceptable topological order in a directed graph ([⇒ Wikipedia][Topological sorting])
//! - [Yen](directed/yen/index.html): find k-shortest paths using Dijkstra ([⇒ Wikipedia][Yen])
//!
//! ### Undirected graphs
//!
//! - [connected components](undirected/connected_components/index.html): find disjoint connected sets of vertices ([⇒ Wikipedia][Connected components])
//! - [Kruskal](undirected/kruskal/index.html): find a minimum-spanning-tree ([⇒ Wikipedia][Kruskal])
//!
//! ### Matching
//!
//! - [Kuhn-Munkres](kuhn_munkres/index.html) (Hungarian algorithm): find the maximum (or minimum) matching in a weighted bipartite graph ([⇒ Wikipedia][Kuhn-Munkres])
//!
//! ### Miscellaneous structures
//!
//! - A [`Grid`](grid/index.html) type representing a rectangular grid in which vertices can be added or removed, with automatic creation of edges between adjacent vertices.
//! - A [`Matrix`](matrix/index.html) type to store data of arbitrary types, with neighbour-aware methods.
//!
//! ## Example
//!
//! We will search the shortest path on a chess board to go from (1, 1) to (4, 6) doing only knight
//! moves.
//!
//! ``` rust
//! use pathfinding::prelude::bfs;
//!
//! #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
//! struct Pos(i32, i32);
//!
//! impl Pos {
//! fn successors(&self) -> Vec<Pos> {
//! let &Pos(x, y) = self;
//! vec![Pos(x+1,y+2), Pos(x+1,y-2), Pos(x-1,y+2), Pos(x-1,y-2),
//! Pos(x+2,y+1), Pos(x+2,y-1), Pos(x-2,y+1), Pos(x-2,y-1)]
//! }
//! }
//!
//! static GOAL: Pos = Pos(4, 6);
//! let result = bfs(&Pos(1, 1), |p| p.successors(), |p| *p == GOAL);
//! assert_eq!(result.expect("no path found").len(), 5);
//! ```
//!
//! ## Note on floating-point types
//!
//! Several algorithms require that the numerical types used to describe
//! edge weights implement `Ord`. If you wish to use Rust built-in
//! floating-point types (such as `f32`) that implement `PartialOrd`
//! in this context, you can wrap them into compliant types using the
//! [ordered-float](https://crates.io/crates/ordered-float) crate.
//!
//! The minimum supported Rust version (MSRV) is Rust 1.70.0.
//!
//! [A*]: https://en.wikipedia.org/wiki/A*_search_algorithm
//! [BFS]: https://en.wikipedia.org/wiki/Breadth-first_search
//! [Brent]: https://en.wikipedia.org/wiki/Cycle_detection#Brent's_algorithm
//! [Connected components]: https://en.wikipedia.org/wiki/Connected_component_(graph_theory)
//! [DFS]: https://en.wikipedia.org/wiki/Depth-first_search
//! [Dijkstra]: https://en.wikipedia.org/wiki/Dijkstra's_algorithm
//! [Edmonds Karp]: https://en.wikipedia.org/wiki/Edmonds–Karp_algorithm
//! [Floyd]: https://en.wikipedia.org/wiki/Cycle_detection#Floyd's_tortoise_and_hare
//! [Fringe]: https://en.wikipedia.org/wiki/Fringe_search
//! [Kruskal]: https://en.wikipedia.org/wiki/Kruskal's_algorithm
//! [IDA*]: https://en.wikipedia.org/wiki/Iterative_deepening_A*
//! [IDDFS]: https://en.wikipedia.org/wiki/Iterative_deepening_depth-first_search
//! [Kuhn-Munkres]: https://en.wikipedia.org/wiki/Hungarian_algorithm
//! [Rust]: https://rust-lang.org/
//! [Strongly connected components]: https://en.wikipedia.org/wiki/Strongly_connected_component
//! [Topological sorting]: https://en.wikipedia.org/wiki/Topological_sorting
//! [Yen]: https://en.wikipedia.org/wiki/Yen's_algorithm

use deprecate_until::deprecate_until;
pub use num_traits;
Expand Down
2 changes: 1 addition & 1 deletion tests/check-msrv-consistency.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
set -e

MSRV=$(awk -F '"' '/^rust-version =/ {print $2}' < Cargo.toml)
if ! grep $MSRV README.md > /dev/null 2>&1; then
if ! grep "Rust $MSRV" src/lib.rs > /dev/null 2>&1; then
echo "MSRV $MSRV not found in README.md"
exit 1
fi

0 comments on commit 279305d

Please sign in to comment.