1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
#![deny(rust_2018_idioms)]
//! # MatchIt
//!
//! [](https://docs.rs/matchit)
//! [](https://crates.io/crates/matchit)
//! [](https://crates.io/crates/matchit)
//! [](https://github.com/ibraheemdev/matchit/actions)
//!
//! A blazing fast URL router and path matcher.
//!
//! ```rust
//! use matchit::Node;
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let mut matcher = Node::new();
//! matcher.insert("/home", "Welcome!")?;
//! matcher.insert("/users/:id", "A User")?;
//!
//! let matched = matcher.at("/users/978")?;
//! assert_eq!(matched.params.get("id"), Some("978"));
//! assert_eq!(*matched.value, "A User");
//!
//! Ok(())
//! }
//! ```
//!
//! `matchit` relies on a tree structure which makes heavy use of *common prefixes*, effectively a [radix tree](https://en.wikipedia.org/wiki/Radix_tree). This makes lookups extremely fast. [See below for technical details](#how-does-it-work).
//!
//! The tree is optimized for high performance and a small memory footprint. It scales well even with very long paths and a large number of routes. A compressing dynamic trie (radix tree) structure is used for efficient matching.
//!
//! ### Parameters
//!
//! As you can see, `:id` is a *named parameter*. The values are accessible via [`Params`](https://docs.rs/matchit/*/matchit/tree/struct.Params.html), which stores a list of keys and values. You can get the value of a parameter by name, `params.get("id")`, or by iterating through the list.
//!
//! The registered path can contain two types of parameters:
//!
//! ```text
//! Syntax Type
//! :name named parameter
//! *name catch-all parameter
//! ```
//!
//! ### Named Parameters
//!
//! Named parameters are dynamic route segments. They match anything until the next `/` or the path end:
//!
//! ```text
//! Route: /user/:user
//!
//! /user/gordon match: user = "gordon"
//! /user/you match: user = "you"
//! /user/gordon/profile no match
//! /user/ no match
//! ```
//!
//! ### Catch-All parameters
//!
//! The second type are *catch-all* parameters and have the form `*name`. Like the name suggests, they match everything. Therefore they must always be at the **end** of the pattern:
//!
//! ```text
//! Route: /src/*filepath
//!
//! /src/ match: filepath = "/"
//! /src/somefile.html match: filepath = "/somefile.html"
//! /src/subdir/somefile.html match: filepath = "/subdir/somefile.html"
//! ```
//!
//! ### Priority
//!
//! Static and dynamic route segments are allowed to overlap. If they do, static segments will be given higher priority:
//! ```text
//! /:page
//! /posts/:year/:month/:post
//! /posts/:year/:month/index
//! /posts/:year/:month
//! /static/*path
//! /favicon.ico
//! ```
//!
//! The following routes will be matched:
//! ```text
//! /about => /:page
//! /posts/2021/01/rust => /posts/:year/:month/:post
//! /posts/2021/01/index => /posts/:year/:month/index
//! /posts/2021/top => /posts/:year/top
//! /static/foo.png => /static/*path
//! /favicon.ico => /favicon.ico
//! ```
//!
//! ## How does it work?
//!
//! The matcher relies on a tree structure which makes heavy use of *common prefixes*, it is basically a *compact* [*prefix tree*](https://en.wikipedia.org/wiki/Trie) (or [*Radix tree*](https://en.wikipedia.org/wiki/Radix_tree)). Nodes with a common prefix share a parent. Here is a short example what the routing tree for the `GET` request method could look like:
//!
//! ```text
//! Priority Path Handle
//! 9 \ *<1>
//! 3 ├s None
//! 2 |├earch\ *<2>
//! 1 |└upport\ *<3>
//! 2 ├blog\ *<4>
//! 1 | └:post None
//! 1 | └\ *<5>
//! 2 ├about-us\ *<6>
//! 1 | └team\ *<7>
//! 1 └contact\ *<8>
//! ```
//!
//! Every `*<num>` represents the memory address of a handler function (a pointer). If you follow a path trough the tree from the root to the leaf, you get the complete route path, e.g `/blog/:post`, where `:post` is just a placeholder ([*parameter*](#named-parameters)) for an actual post name. Unlike hash-maps, a tree structure also allows us to use dynamic parts like the `:post` parameter, since we actually match against the routing patterns instead of just comparing hashes. This works very efficiently.
//!
//! Because URL paths have a hierarchical structure and make use only of a limited set of characters (byte values), it is very likely that there are a lot of common prefixes. Storing the routes in this structure allows us to easily reduce the routing into a very small number of branches.
//!
//! For even better scalability, the child nodes on each tree level are ordered by priority, where the priority is just the number of handles registered in child nodes. This means that nodes that are part of the most routing paths are always evaluated first, increasing the chance of reaching the correct route on our first try.
//!
//! ```test
//! ├------------
//! ├---------
//! ├-----
//! ├----
//! ├--
//! ├--
//! └-
//! ```
mod error;
mod params;
mod tree;
pub use error::{InsertError, MatchError};
pub use params::{Params, ParamsIter};
pub use tree::{Match, Node};
#[cfg(doctest)]
mod test_readme {
macro_rules! doc_comment {
($x:expr) => {
#[doc = $x]
extern "C" {}
};
}
doc_comment!(include_str!("../README.md"));
}