Struct PathPattern 

pub struct PathPattern { /* private fields */ }

Available on crate feature net only.

A compiled path pattern.

Construct via PathPattern::new / new_with_opts and test paths with is_match / captures.

Syntax

A pattern is split on / into segments. The only metacharacters are {, } and ?; everything else (*, :, ., +, …) is a literal. Within a segment:

• literal text must equal the (decoded) path segment value;
• {name} captures a non-empty run under name: a whole segment when alone ({id}), or the run bounded by surrounding literals when affixed ({pkg}.json captures the part before .json, v{ver}-rc the part between);
• {} is an anonymous non-empty wildcard run, not captured ({}.txt);
• ? makes the immediately preceding element optional (zero-or-one): a? is an optional a, {}? an optional run, {name}? an optional capture, and a trailing /? an optional trailing slash. A whole segment made only of {name}? or {}? is itself optional, so /foo/{name}?/bar matches /foo/john/bar, /foo//bar, and /foo/bar;
• {*}, as a whole segment, is an anonymous catch-all matching one or more path segments, available ‘/’-joined and decoded via PathCaptures::glob. It may appear in the middle of a pattern;
• {*name}, as a whole segment, is the named catch-all: same 1+ segment match as {*}, but the run is recorded under name (read back, ‘/’-joined and decoded, via PathCaptures::get). So {name} stays within a segment; {*name} spans segments.

An unclosed {, or a brace group whose body isn’t a valid token, is taken literally. {*}/{*name} are catch-alls only as a whole segment.

Trailing slash is explicit: /a matches only /a, /a/ matches only /a/, and /a/? matches both.

use rama_net::uri::{PathPattern, PathRef};

let pat = PathPattern::new("/p2/{vendor}/{pkg}.json");
let caps = pat.captures(PathRef::from_raw_str("/p2/acme/widget.json")).unwrap();
assert_eq!(caps.get("vendor"), Some("acme"));
assert_eq!(caps.get("pkg"), Some("widget"));
assert!(pat.captures(PathRef::from_raw_str("/p2/acme/widget.txt")).is_none());

let assets = PathPattern::new("/assets/{*}");
assert!(assets.is_match(PathRef::from_raw_str("/assets/css/app.css")));
assert!(!assets.is_match(PathRef::from_raw_str("/assets")));

// `{*name}` is the named catch-all (read back via `get`).
let files = PathPattern::new("/files/{*rest}");
let caps = files.captures(PathRef::from_raw_str("/files/a/b/c.txt")).unwrap();
assert_eq!(caps.get("rest"), Some("a/b/c.txt"));

Implementations

impl PathPattern

pub fn new(pattern: impl IntoUriComponent) -> PathPattern

Compile a path pattern. Infallible: anything not a recognized meta token is a literal.

use rama_net::uri::{PathPattern, PathRef};

let pat = PathPattern::new("/backend-api/codex/responses");
assert!(pat.is_match(PathRef::from_raw_str("/backend-api/codex/responses")));
assert!(!pat.is_match(PathRef::from_raw_str("/backend-api/codex")));

pub fn new_with_opts( pattern: impl IntoUriComponent, opts: PathMatchOptions, ) -> PathPattern

new with explicit PathMatchOptions. The matcher honors ignore_ascii_case and percent_decode; partial is irrelevant and ignored.

use rama_net::uri::{PathMatchOptions, PathPattern, PathRef};

let opts = PathMatchOptions {
    ignore_ascii_case: true,
    ..Default::default()
};
let pat = PathPattern::new_with_opts("/api/v2", opts);
assert!(pat.is_match(PathRef::from_raw_str("/API/v2")));

pub fn new_prefix(pattern: impl IntoUriComponent) -> PathPattern

Compile a prefix matcher: the pattern must match a leading run of the path’s segments; any trailing segments and the path’s trailing slash are ignored. So /api matches /api, /api/, and /api/users — but not /apixyz (segments are matched whole).

use rama_net::uri::{PathPattern, PathRef};

let api = PathPattern::new_prefix("/api");
assert!(api.is_match(PathRef::from_raw_str("/api")));
assert!(api.is_match(PathRef::from_raw_str("/api/users/42")));
assert!(!api.is_match(PathRef::from_raw_str("/apixyz")));

pub fn new_prefix_with_opts( pattern: impl IntoUriComponent, opts: PathMatchOptions, ) -> PathPattern

new_prefix with explicit PathMatchOptions.

pub fn segment_kinds(&self) -> impl ExactSizeIterator

The kind of each /-delimited pattern segment, in order — so callers can classify segments (literal vs dynamic vs catch-all) straight from the compiled pattern instead of re-parsing the syntax. A bare-root pattern (/) yields an empty iterator.

use rama_net::uri::{PathPattern, PathPatternSegmentKind as K};

let kinds: Vec<_> = PathPattern::new("/users/{id}/{*rest}").segment_kinds().collect();
assert_eq!(kinds, [K::Literal, K::Dynamic, K::CatchAll]);
// An invalid catch-all body is a literal, exactly as the matcher treats it.
let kinds: Vec<_> = PathPattern::new("/api/{*bad name}").segment_kinds().collect();
assert_eq!(kinds, [K::Literal, K::Literal]);

pub fn segment_specificity(&self) -> impl ExactSizeIterator

Specificity metadata for each /-delimited pattern segment, in order. This is a richer version of segment_kinds for callers that need stable precedence among overlapping dynamic patterns.

use rama_net::uri::{PathPattern, PathPatternSegmentKind as K};

let specs: Vec<_> = PathPattern::new("/files/{name}.json")
    .segment_specificity()
    .collect();
assert_eq!(specs[0].kind, K::Literal);
assert_eq!(specs[1].kind, K::Dynamic);
assert_eq!(specs[1].literal_bytes, 5);
assert_eq!(specs[1].dynamic_parts, 1);

pub fn is_match(&self, path: PathRef<'_>) -> bool

true when path matches. Allocation-free when the pattern has no captures and no catch-all.

use rama_net::uri::{PathPattern, PathRef};

let pat = PathPattern::new("/files/{}.txt");
assert!(pat.is_match(PathRef::from_raw_str("/files/readme.txt")));
assert!(!pat.is_match(PathRef::from_raw_str("/files/readme.md")));

pub fn captures<'p>(&self, path: PathRef<'p>) -> Option<PathCaptures<'_, 'p>>

Match and return captured values, or None when path doesn’t match. Uses inline storage for the common small number of bindings.

use rama_net::uri::{PathPattern, PathRef};

let pat = PathPattern::new("/simple/{name}/?");
let caps = pat.captures(PathRef::from_raw_str("/simple/requests")).unwrap();
assert_eq!(caps.get("name"), Some("requests"));

Trait Implementations

impl Clone for PathPattern

fn clone(&self) -> PathPattern

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PathPattern

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Eq for PathPattern

impl Hash for PathPattern

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for PathPattern

fn eq(&self, other: &PathPattern) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.