Struct Pattern 

pub struct Pattern { /* private fields */ }

A pattern over broadcast paths: literal segments, * for one segment, prefix*suffix for one segment with a known start and end, and at most one ** for any run of segments. Every segment kind matches whole segments, and a pattern is exact: foo matches only foo, and a subtree is foo/**.

Build one with FromStr ("a/*/**".parse()), new from segments, or literal and subtree from a path. Equality and ordering are by text, which is canonical: two patterns match the same paths when they are equal, and only then. Construction moves ** before adjacent * segments.

Implementations

impl Pattern

pub const MAX_SEGMENTS: usize = 32

The most segments a pattern may have, matching the path limit on the wire.

pub const MAX_INTERSECTIONS: usize = 1024

The most patterns one exact intersection may produce.

pub fn new( segments: impl IntoIterator<Item = Segment>, ) -> Result<Pattern, InvalidPattern>

A pattern from its segments, validating the grammar and moving ** before adjacent * segments.

pub fn all() -> Pattern

The pattern matching every path: **.

pub fn literal(path: &str) -> Result<Pattern, InvalidPattern>

The pattern matching exactly path.

The path is normalized like a broadcast path (slashes trimmed and collapsed), so /foo//bar/ is foo/bar. Fails when a segment is * or **, or contains *: those are wildcards, and a path using them cannot be named by a pattern.

pub fn subtree(path: &str) -> Result<Pattern, InvalidPattern>

The pattern matching path and every path beneath it: path/**.

Normalizes and validates path like literal. The empty path yields **.

pub fn as_str(&self) -> &str

The canonical text: segments joined by /, wildcards as * and **.

pub fn segments(&self) -> &[Segment]

The segments, in order.

pub fn head(&self) -> &str

The literal segments before the first wildcard, as a path.

Every matching path starts with it, so it is where a tree walk starts. Empty when the pattern starts with a wildcard; the whole pattern when it has none.

pub fn is_literal(&self) -> bool

Whether the pattern has no wildcards, so it matches exactly one path.

pub fn as_prefix(&self) -> Option<&str>

The covered prefix if this pattern is prefix-shaped: zero or more literals then **.

** covers every path (the empty prefix). foo/** covers foo and everything beneath it. A literal, a *, or a ** that is not last is None.

pub fn has_globstar(&self) -> bool

Whether the pattern has a **, so it matches paths of more than one length.

pub fn matches(&self, path: &str) -> bool

Whether path is in the set this pattern describes.

The path is normalized like a broadcast path: slashes are trimmed and collapsed.

pub fn contains(&self, other: &Pattern) -> bool

Whether every path other matches, this pattern matches too.

This is the authorization check: a grant contains a request when the request cannot name a path outside it. A pattern contains itself.

pub fn overlaps(&self, other: &Pattern) -> bool

Whether some path matches both patterns.

pub fn specificity(&self) -> Specificity

How much of a path this pattern pins down. See Specificity.

pub fn rebase(&self, root: &str) -> Patterns

The patterns that, relative to root, match exactly the paths this pattern matches beneath root.

This is how a grant or an advertisement is presented inside a rooted view. It is a set because ** may consume the root or stop short of it: **/a rebased at a is both the empty pattern (the root itself) and **/a (deeper paths ending in a). Empty when nothing under root matches. The root is normalized like a broadcast path.

pub fn intersect(&self, other: &Pattern) -> Result<Patterns, IntersectionError>

The patterns matching exactly the paths both patterns match.

This is how a claim is clamped to a scope: the covered paths inside the grant, as patterns of their own. It is a set because two partial segments or two ** runs can meet in more than one way: ab* and *b meet at ab*b and at ab, and a/** and **/a meet at a/**/a and at a. Empty when the two do not overlap.

pub fn captures(&self, matched: &Pattern) -> Option<Vec<Pattern>>

What each wildcard of this pattern stands for in matched, a pattern this one contains; None when it does not.

One capture per non-literal segment (*, prefix*suffix, **), in order, the way a regex match exposes its groups: foo/*/chat against foo/alice/chat captures alice, and foo/** against foo/alice/chat captures alice/chat. A capture is a pattern because matched may be one: foo/** against foo/alice/** captures alice/**. When matched has a ** that this pattern’s own segments straddle (**/* against a/**, where the last segment is a or anything after it), the segments it straddles cannot be pinned and capture themselves: ** then *.

pub fn rooted(&self, root: &str) -> Result<Pattern, InvalidPattern>

This pattern placed beneath a literal root: the same paths, named from the root’s parent. The inverse of rebase for a single pattern.

The root is normalized and validated like literal, and the result must fit MAX_SEGMENTS.

Trait Implementations

impl AsRef<str> for Pattern

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Pattern

fn clone(&self) -> Pattern

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Pattern

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

Formats the value using the given formatter.

impl Default for Pattern

fn default() -> Pattern

The empty pattern, which matches only the empty path.

impl<'de> Deserialize<'de> for Pattern

Available on crate feature serde only.

fn deserialize<D>( deserializer: D, ) -> Result<Pattern, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Reads the canonical text, so a persisted pattern is validated on the way in.

impl Display for Pattern

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

Formats the value using the given formatter.

impl Eq for Pattern

impl Extend<Pattern> for Patterns

fn extend<I>(&mut self, iter: I)

where I: IntoIterator<Item = Pattern>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<Pattern> for Patterns

fn from(pattern: Pattern) -> Patterns

Converts to this type from the input type.

impl FromIterator<Pattern> for Patterns

fn from_iter<I>(iter: I) -> Patterns

where I: IntoIterator<Item = Pattern>,

Creates a value from an iterator.

impl FromStr for Pattern

fn from_str(text: &str) -> Result<Pattern, InvalidPattern>

Parse a pattern’s text. Unlike a path, slashes are not normalized: a leading, trailing, or doubled / is an error, so a typo cannot silently widen a grant.

type Err = InvalidPattern

The associated error which can be returned from parsing.

impl Hash for Pattern

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 Ord for Pattern

fn cmp(&self, other: &Pattern) -> Ordering

Ordered by text, so a sorted list of patterns is deterministic.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for Pattern

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for Pattern

fn partial_cmp(&self, other: &Pattern) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Pattern

Available on crate feature serde only.

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Pattern

impl TryFrom<&str> for Pattern

type Error = InvalidPattern

The type returned in the event of a conversion error.

fn try_from(text: &str) -> Result<Pattern, InvalidPattern>

Performs the conversion.

impl TryFrom<String> for Pattern

type Error = InvalidPattern

The type returned in the event of a conversion error.

fn try_from(text: String) -> Result<Pattern, InvalidPattern>

Performs the conversion.