Struct KeFormat 

pub struct KeFormat<'s, Storage: IKeFormatStorage<'s> + 's = Vec<Segment<'s>>> { /* private fields */ }

Building and parsing Key Expressions

A common issue in REST API is the association of meaning to sections of the URL, and respecting that API in a convenient manner. The same issue arises naturally when designing a KE space, and KeFormat was designed to help you with this, both in constructing and in parsing KEs that fit the formats you’ve defined.

kedefine also allows you to define formats at compile time, allowing a more performant, but more importantly safer and more convenient use of said formats, as the keformat and kewrite macros will be able to tell you if you’re attempting to set fields of the format that do not exist.

The format syntax

KE formats are defined following a syntax that extends the keyexpr syntax. In addition to existing chunk types, KE formmats support “specification” chunks. These chunks must follow the one of the following syntaxes: ${id:pattern}, ${id:pattern#default}, $#{id:pattern}#, or $#{id:pattern#default}#, where:

• id is the chunk identifier: it cannot contain the : character, and is used to name the chunk in accessors.
• pattern must be a valid KE (and therefore cannot contain #) and defines the range of values that the chunk may adopt.
• default (optional) is used as the chunk value when formatting if the builder wasn’t supplied with a value for id.

Formatting

To use a format to build a Key Expression, its formatter must be constructed.

A formatter functions like as an id-value map which can be KeFormatter::build into a OwnedKeyExpr once all specs have a value.

The formatter will notably prevent you from setting values for a spec that isn’t included by its pattern.

Parsing

KeFormat can also be used to parse any keyexpr that intersects with it, using KeFormat::parse.

The parser will then assign subsections of the keyexpr to each spec, and the resulting Parsed result can then be queried for each spec’s assigned value.

Specs are considered greedy and evaluated left-to-right: if your format would allow ambiguous parsings, chunks will be consumed by the leftmost specs first. For example ${a:**}/-/${b:**} parsing hey/-/-/there would assign hey/- to a and there to b, (even though you might have expected a to only consume hey and b to consume the remaining -/there).

A good way to avoid ambiguities when working with formats that contain multiple ** specs is to separate such specs using verbatim chunks (chunks that start with an @), as ** is incapable of consuming these chunks.

Implementations

impl<'s, Storage: IKeFormatStorage<'s> + 's> KeFormat<'s, Storage>

pub fn parse(&'s self, target: &'s keyexpr) -> ZResult<Parsed<'s, Storage>>

Parses target according to self. The returned Parsed object can be used to extract the values of the fields in self from target.

Parsing is greedy and done left-to-right. Please refer to KeFormat’s documentation for more details.

Errors

If target does not intersect with self, an error is returned.

impl<'s> KeFormat<'s, Vec<Segment<'s>>>

pub fn new<S: AsRef<str> + ?Sized>(value: &'s S) -> ZResult<Self>

Construct a new KeFormat, using a vector to store its state-machine and parser results.

pub fn noalloc_new<const N: usize>( value: &'s str, ) -> ZResult<KeFormat<'s, [Segment<'s>; N]>>

Construct a new `KeFormat, using a stack-allocated array to store its state-machine and parser results.

N is simply the number of specifications in value. If this number of specs isn’t known at compile-time, use KeFormat::new instead.

If you know value at compile time, using kedefine instead is advised, as it will provide more features and construct higher performance formats than this constructor.

impl<'s, Storage: IKeFormatStorage<'s> + 's> KeFormat<'s, Storage>

pub fn formatter(&'s self) -> KeFormatter<'s, Storage>

Constructs a new formatter for the format.

Trait Implementations

impl<'s, Storage: Clone + IKeFormatStorage<'s> + 's> Clone for KeFormat<'s, Storage>

fn clone(&self) -> KeFormat<'s, Storage>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'s, Storage: IKeFormatStorage<'s>> Debug for KeFormat<'s, Storage>

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

Formats the value using the given formatter.

impl<'s, Storage: IKeFormatStorage<'s> + 's> Display for KeFormat<'s, Storage>

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

Formats the value using the given formatter.

impl<'s, Storage: Hash + IKeFormatStorage<'s> + 's> Hash for KeFormat<'s, Storage>

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

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<'s, S1: IKeFormatStorage<'s> + 's, S2: IKeFormatStorage<'s> + 's> PartialEq<KeFormat<'s, S2>> for KeFormat<'s, S1>

fn eq(&self, other: &KeFormat<'s, S2>) -> 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.

impl<'s, Storage: IKeFormatStorage<'s> + 's> TryFrom<&KeFormat<'s, Storage>> for OwnedKeyExpr

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from(value: &KeFormat<'s, Storage>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'s, Storage: IKeFormatStorage<'s> + 's> TryFrom<&KeFormat<'s, Storage>> for String

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &KeFormat<'s, Storage>) -> Result<Self, Self::Error>

Performs the conversion.

impl<'s, Storage: IKeFormatStorage<'s> + 's> TryFrom<&'s String> for KeFormat<'s, Storage>

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from(value: &'s String) -> Result<Self, Self::Error>

Performs the conversion.

impl<'s, Storage: IKeFormatStorage<'s> + 's> TryFrom<&'s str> for KeFormat<'s, Storage>

type Error = Box<dyn Error + Sync + Send>

The type returned in the event of a conversion error.

fn try_from(value: &'s str) -> Result<Self, Self::Error>

Performs the conversion.

impl<'s, Storage: Copy + IKeFormatStorage<'s> + 's> Copy for KeFormat<'s, Storage>