Struct UriMatchReplaceRule 

pub struct UriMatchReplaceRule { /* private fields */ }

A rule that matches a Uri against a simple wildcard pattern and, if it matches, produces a new Uri using a capture-aware formatter.

Pattern syntax

The pattern is a literal byte string with * wildcards:

• * matches any (possibly empty) sequence of bytes.
• Matching is case-sensitive.
• The pattern is matched against the entire textual Uri (for example "https://a/b\\?c"), not just a path segment.
• Notice in the previous example that ? is escaped as the ? character by itself means a match of any ‘single’ character which is contract to * that matches any “multiple” characters
• Each * produces a 1-based capture $1, $2, … that can be referenced from the formatter.

Examples:

• "http://*" matches any http URI, capturing everything after the scheme and // into $1.
• "https://*/docs/*" captures the host (and optional port) into $1 and the tail after /docs/ into $2.

Formatter syntax

The formatter is a byte template that may contain captures $N with N in 1..=16. Captures are 1-based: $1 inserts the first pattern wildcard, $2 the second, and so on.

• $0 is not accepted, and neither is anything beyond $16.
• Missing captures are inserted as an empty string. For example, if the pattern has one * and the formatter uses $2, nothing is inserted for $2.
• The formatter may contain at most one ? character. If more than one ? is present, construction fails (see Errors).

Examples

Upgrade http to https:

let rule = UriMatchReplaceRule::try_new("http://*", "https://$1").unwrap();

let input = Uri::from_static("http://example.com/x?y=1");
let out = rule.match_replace_uri(Cow::Owned(input)).unwrap();
assert_eq!(out.to_string(), "https://example.com/x?y=1");

// Non-matching scheme
let https_in = Uri::from_static("https://example.com");
assert!(rule.match_replace_uri(Cow::Owned(https_in)).is_err());

Reorder two captures:

let rule = UriMatchReplaceRule::try_new(
    "https://*/docs/*",
    "https://$1/knowledge/$2"
).unwrap();

let input = Uri::from_static("https://a.example.com/docs/rust");
let out = rule.match_replace_uri(Cow::Owned(input)).unwrap();
assert_eq!(out.to_string(), "https://a.example.com/knowledge/rust");

Edge cases and behavior

• Empty matches: each * can match an empty span. This is often useful at path boundaries like "/*/end".
• $0: accepted in the formatter but never inserts anything.
• Missing indices: using $N where N exceeds the number of pattern wildcards inserts nothing, the rest of the formatter is preserved.
• Multiple ? in formatter: invalid. The formatter accepts at most one ?. See Errors.
• Invalid formatter escapes: the formatter does not interpret percent escapes or special encodings. It is a raw byte template plus $N slots.
• Query handling: pattern and formatter treat ? and everything after it as regular bytes. If your formatter includes a ?, ensure you include the query part you want, for example "…?$1" if your pattern captured it.

Errors

try_new can fail when:

• The formatter contains more than one ?.
• A capture token in the formatter is malformed: not a $ followed by 1..=3 digits, or the total potential formatted length would exceed the configured maximum (see UriFormatter).

match_replace_uri never panics; it returns:

• Some(Uri) when the input matches and the formatted bytes parse as a valid Uri.
• None when the input does not match the pattern or the formatted bytes cannot be parsed as a Uri.

Implementations

impl UriMatchReplaceRule

pub fn http_to_https() -> UriMatchReplaceRule

A convenience constructor that creates a rule which upgrades any http://… URI to https://… while preserving everything after the scheme.

Note in case this is the only rule (within its group) that you need you might want to use super::UriMatchReplaceScheme::http_to_https instead as it is more efficient.

Equivalent to:

let rule = UriMatchReplaceRule::try_new("http://*", "https://$1").unwrap();

Examples

let rule = UriMatchReplaceRule::http_to_https();
let out = rule.match_replace_uri(Cow::Owned(Uri::from_static("http://a/b?x=1"))).unwrap();
assert_eq!(out.to_string(), "https://a/b?x=1");

pub fn try_new( ptn: impl TryIntoPattern, fmt: impl TryIntoUriFmt, ) -> Result<UriMatchReplaceRule, OpaqueError>

Attempts to create a new UriMatchReplaceRule.

• ptn is converted to a wildcard pattern where * captures arbitrary byte sequences. Each * becomes $1, $2, … in the formatter.
• fmt is converted to a UriFormatter where $N inserts the N-th pattern capture. $0 inserts nothing.

See the type-level docs (UriMatchReplaceRule) for details on syntax, edge cases, and errors.

pub fn with_include_query_overwrite( self, include_query: bool, ) -> UriMatchReplaceRule

Includes the query parameter in original Uri for this rule, even if pattern or formatter does not request it.

pub fn set_include_query_overwrite( &mut self, include_query: bool, ) -> &mut UriMatchReplaceRule

Includes the query parameter in original Uri for this rule, even if pattern or formatter does not request it.

Trait Implementations

impl Clone for UriMatchReplaceRule

fn clone(&self) -> UriMatchReplaceRule

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for UriMatchReplaceRule

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for UriMatchReplaceRule

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

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl FromIterator<UriMatchReplaceRule> for UriMatchReplaceRuleset

fn from_iter<T>(iter: T) -> UriMatchReplaceRuleset

where T: IntoIterator<Item = UriMatchReplaceRule>,

Creates a value from an iterator.

impl Serialize for UriMatchReplaceRule

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 UriMatchReplace for UriMatchReplaceRule

fn match_replace_uri<'a>( &self, uri: Cow<'a, Uri>, ) -> Result<Cow<'a, Uri>, UriMatchError<'a>>

Tries to match uri against the rule’s pattern and, on success, returns the same Uri or a new reformatted Uri.