Struct usher::router::Router

pub struct Router<T> { /* fields omitted */ }

Routing structure providing routing for generic types.

A Router is constructed from a set of Parser values, which are used to construct the shape of the structure internally. During construction of a Router, these parsers are used to turn path segments into Matcher types which are used in routing to calculate the traversal of the tree.

The order of the provided Parser values is important as it defines the order they're checked against a path segment. If a parser matching any segment is placed first, it will always match and short circuit before checking any other provided parsers. Always put the "strictest" parsers first in the vector.

Methods

impl<T> Router<T>

pub fn new(parsers: Vec<Box<dyn Parser>>) -> Self

Creates a new Router, using the provided matchers.

pub fn insert(&mut self, path: &str, t: T)

Inserts a route/handler pair for the provided path and method.

Internally this is pretty similar to update, except that it guarantees that the provided value t is stored as the leaf value. If the leaf already contains a value, it will be overwritten. If this is not desired, you can likely implement the insertion easily via update instead.

pub fn lookup<'a>(&'a self, path: &str) -> Option<(&T, Captures<'a>)>

Attempts to route a path to a leaf value.

This function will also capture any parameters involved in routing, into a Vec which is returned inside the containing Option. Each capture consists of a name and bounds of a value, to help identify the matched parameter. Whilst this is easily determined as the vector is ordered, it's helpful for those who wish to turn captures into a map-like structure afterward.

Index bounds are used over path references to avoid lifetime requirements on the path itself, which can cause problems when working in certain contexts. At some point in future, Usher will provide APIs to turn these index captures into friendlier containers - but as this is the lowest cost for a default, it makes sense for now.

If a route does not require any parameters, this vector is still returned but is empty. This isn't a big deal; a Vec will only allocate memory when you first push something into it in most cases, so the performance hit is minimal.

pub fn update<F>(&mut self, path: &str, f: F) where
    F: FnOnce(Option<T>) -> T, 

Updates a leaf node inside a Router.

If the node does not currently exist, it will be built out and populated with the result of the update function (which can be used to generate a value for first insertion).