Trait rocket::http::uri::FromUriParam

pub trait FromUriParam<P, T> where
    P: UriPart, {
    type Target: UriDisplay<P>;
    pub fn from_uri_param(param: T) -> Self::Target;
}

Conversion trait for parameters used in uri! invocations.

Overview

In addition to implementing UriDisplay, to use a custom type in a uri! expression, the FromUriParam trait must be implemented. The UriDisplay derive automatically generates identity implementations of FromUriParam, so in the majority of cases, as with UriDisplay, this trait is never implemented manually.

In the rare case that UriDisplay is implemented manually, this trait, too, must be implemented explicitly. In the majority of cases, implementation can be automated. Rocket provides impl_from_uri_param_identity to generate the identity implementations automatically. For a type T, these are:

• impl<P: UriPart> FromUriParam<P, T> for T
• impl<'x, P: UriPart> FromUriParam<P, &'x T> for T
• impl<'x, P: UriPart> FromUriParam<P, &'x mut T> for T

See impl_from_uri_param_identity for usage details.

Code Generation

This trait is invoked once per expression passed into a uri! invocation. In particular, for a route URI parameter of type T and a user-supplied expression e of type S, <T as FromUriParam<S>>::from_uri_param(e) is invoked. The returned value of type T::Target is used in place of the user’s value and rendered using its UriDisplay implementation.

This trait allows types that differ from the route URI parameter’s types to be used in their place at no cost. For instance, the following implementation, provided by Rocket, allows an &str to be used in a uri! invocation for route URI parameters declared as String:

impl<'a, P: UriPart> FromUriParam<P, &'a str> for String {
    type Target = &'a str;
}

Because the FromUriParam::Target type is the same as the input type, the conversion is a no-op and free of cost, allowing an &str to be used in place of a String without penalty.

Provided Implementations

The following types have identity implementations:

• String, i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, usize, f32, f64, bool, IpAddr, Ipv4Addr, Ipv6Addr, &str, Cow<str>

The following types have identity implementations only in Path:

• &Path, PathBuf

The following types have identity implementations only in [Query]:

• Option<T>, Result<T, E>

The following conversions are implemented for both paths and queries, allowing a value of the type on the left to be used when a type on the right is expected by a route:

• &str to String
• String to &str
• T to Form<T>

The following conversions are implemented only in Path:

• &str to &Path
• &str to PathBuf
• PathBuf to &Path
• T to Option<T>
• T to Result<T, E>

The following conversions are implemented only in [Query]:

• Option<T> to Result<T, E> (for any E)
• Result<T, E> to Option<T> (for any E)

See Foreign Impls for all provided implementations.

Implementing

This trait should only be implemented when you’d like to allow a type different from the route’s declared type to be used in its place in a uri! invocation. For instance, if the route has a type of T and you’d like to use a type of S in a uri! invocation, you’d implement FromUriParam<P, T> for S where P is Path for conversions valid in the path part of a URI, Uri for conversions valid in the query part of a URI, or P: UriPart when a conversion is valid in either case.

This is typically only warranted for owned-value types with corresponding reference types: String and &str, for instance. In this case, it’s desirable to allow an &str to be used in place of a String.

When implementing FromUriParam, be aware that Rocket will use the UriDisplay implementation of FromUriParam::Target, not of the source type. Incorrect implementations can result in creating unsafe URIs.

Example

The following example implements FromUriParam<Query, (&str, &str)> for a User type. The implementation allows an (&str, &str) type to be used in a uri! invocation where a User type is expected in the query part of the URI.

use std::fmt;

use rocket::http::uri::{Formatter, UriDisplay, FromUriParam, Query};

#[derive(FromForm)]
struct User<'a> {
    name: &'a str,
    nickname: String,
}

impl UriDisplay<Query> for User<'_> {
    fn fmt(&self, f: &mut Formatter<Query>) -> fmt::Result {
        f.write_named_value("name", &self.name)?;
        f.write_named_value("nickname", &self.nickname)
    }
}

impl<'a, 'b> FromUriParam<Query, (&'a str, &'b str)> for User<'a> {
    type Target = User<'a>;

    fn from_uri_param((name, nickname): (&'a str, &'b str)) -> User<'a> {
        User { name: name.into(), nickname: nickname.to_string() }
    }
}

With these implementations, the following typechecks:

#[post("/<name>?<user..>")]
fn some_route(name: &str, user: User<'_>)  { /* .. */ }

let uri = uri!(some_route: name = "hey", user = ("Robert Mike", "Bob"));
assert_eq!(uri.path(), "/hey");
assert_eq!(uri.query().unwrap(), "name=Robert%20Mike&nickname=Bob");

Associated Types

type Target: UriDisplay<P>

The resulting type of this conversion.

Loading content...

Required methods

pub fn from_uri_param(param: T) -> Self::Target

Converts a value of type T into a value of type Self::Target. The resulting value of type Self::Target will be rendered into a URI using its UriDisplay implementation.

Loading content...

Implementations on Foreign Types

impl<'x> FromUriParam<Path, &'x PathBuf> for PathBuf

type Target = &'x PathBuf

pub fn from_uri_param(param: &'x PathBuf) -> &'x PathBuf

impl<P> FromUriParam<P, f32> for f32 where
    P: UriPart, 

type Target = f32

pub fn from_uri_param(param: f32) -> f32

impl<'x, P> FromUriParam<P, &'x mut Ipv6Addr> for Ipv6Addr where
    P: UriPart, 

type Target = &'x mut Ipv6Addr

pub fn from_uri_param(param: &'x mut Ipv6Addr) -> &'x mut Ipv6Addr

impl<'x, 'a, P> FromUriParam<P, &'x mut Cow<'a, str>> for Cow<'a, str> where
    P: UriPart, 

type Target = &'x mut Cow<'a, str>

pub fn from_uri_param(param: &'x mut Cow<'a, str>) -> &'x mut Cow<'a, str>

impl<'x, P> FromUriParam<P, &'x mut i16> for i16 where
    P: UriPart, 

type Target = &'x mut i16

pub fn from_uri_param(param: &'x mut i16) -> &'x mut i16

impl FromUriParam<Path, PathBuf> for PathBuf

type Target = PathBuf

pub fn from_uri_param(param: PathBuf) -> PathBuf

impl<'x, P> FromUriParam<P, &'x i64> for i64 where
    P: UriPart, 

type Target = &'x i64

pub fn from_uri_param(param: &'x i64) -> &'x i64

impl<'x, P> FromUriParam<P, &'x i8> for i8 where
    P: UriPart, 

type Target = &'x i8

pub fn from_uri_param(param: &'x i8) -> &'x i8

impl<'x, P> FromUriParam<P, &'x mut bool> for bool where
    P: UriPart, 

type Target = &'x mut bool

pub fn from_uri_param(param: &'x mut bool) -> &'x mut bool

impl<'x, P> FromUriParam<P, &'x mut i8> for i8 where
    P: UriPart, 

type Target = &'x mut i8

pub fn from_uri_param(param: &'x mut i8) -> &'x mut i8

impl<P> FromUriParam<P, u16> for u16 where
    P: UriPart, 

type Target = u16

pub fn from_uri_param(param: u16) -> u16

impl<'x, 'a> FromUriParam<Path, &'x PathBuf> for &'a Path

type Target = &'x PathBuf

pub fn from_uri_param(param: &'x PathBuf) -> &'x PathBuf

impl<'x, P> FromUriParam<P, &'x f32> for f32 where
    P: UriPart, 

type Target = &'x f32

pub fn from_uri_param(param: &'x f32) -> &'x f32

impl<'x, P> FromUriParam<P, &'x usize> for usize where
    P: UriPart, 

type Target = &'x usize

pub fn from_uri_param(param: &'x usize) -> &'x usize

impl<'x, P> FromUriParam<P, &'x mut i128> for i128 where
    P: UriPart, 

type Target = &'x mut i128

pub fn from_uri_param(param: &'x mut i128) -> &'x mut i128

impl<'x, P> FromUriParam<P, &'x String> for String where
    P: UriPart, 

type Target = &'x String

pub fn from_uri_param(param: &'x String) -> &'x String

impl<P> FromUriParam<P, u32> for u32 where
    P: UriPart, 

type Target = u32

pub fn from_uri_param(param: u32) -> u32

impl<'a> FromUriParam<Path, &'a Path> for PathBuf

type Target = &'a Path

pub fn from_uri_param(param: &'a Path) -> &'a Path

impl<A, T> FromUriParam<Query, Option<A>> for Option<T> where
    T: FromUriParam<Query, A>, 

type Target = Option<<T as FromUriParam<Query, A>>::Target>

pub fn from_uri_param(
    param: Option<A>
) -> <Option<T> as FromUriParam<Query, Option<A>>>::Target

impl<'a> FromUriParam<Path, PathBuf> for &'a Path

type Target = PathBuf

pub fn from_uri_param(param: PathBuf) -> PathBuf

impl<'x, P> FromUriParam<P, &'x i128> for i128 where
    P: UriPart, 

type Target = &'x i128

pub fn from_uri_param(param: &'x i128) -> &'x i128

impl<P> FromUriParam<P, i64> for i64 where
    P: UriPart, 

type Target = i64

pub fn from_uri_param(param: i64) -> i64

impl<'x, P> FromUriParam<P, &'x mut String> for String where
    P: UriPart, 

type Target = &'x mut String

pub fn from_uri_param(param: &'x mut String) -> &'x mut String

impl<'a> FromUriParam<Path, &'a str> for PathBuf

A no cost conversion allowing an &str to be used in place of a PathBuf.

type Target = &'a Path

pub fn from_uri_param(param: &'a str) -> &'a Path

impl<'x, P> FromUriParam<P, &'x bool> for bool where
    P: UriPart, 

type Target = &'x bool

pub fn from_uri_param(param: &'x bool) -> &'x bool

impl<P> FromUriParam<P, Ipv6Addr> for Ipv6Addr where
    P: UriPart, 

type Target = Ipv6Addr

pub fn from_uri_param(param: Ipv6Addr) -> Ipv6Addr

impl<'x, P> FromUriParam<P, &'x mut usize> for usize where
    P: UriPart, 

type Target = &'x mut usize

pub fn from_uri_param(param: &'x mut usize) -> &'x mut usize

impl<'x, 'a, P> FromUriParam<P, &'x String> for &'a str where
    P: UriPart, 

type Target = &'x String

pub fn from_uri_param(param: &'x String) -> &'x String

impl<'x, P> FromUriParam<P, &'x IpAddr> for IpAddr where
    P: UriPart, 

type Target = &'x IpAddr

pub fn from_uri_param(param: &'x IpAddr) -> &'x IpAddr

impl<P> FromUriParam<P, usize> for usize where
    P: UriPart, 

type Target = usize

pub fn from_uri_param(param: usize) -> usize

impl<P> FromUriParam<P, isize> for isize where
    P: UriPart, 

type Target = isize

pub fn from_uri_param(param: isize) -> isize

impl<'x, 'a, P> FromUriParam<P, &'x Cow<'a, str>> for Cow<'a, str> where
    P: UriPart, 

type Target = &'x Cow<'a, str>

pub fn from_uri_param(param: &'x Cow<'a, str>) -> &'x Cow<'a, str>

impl<P> FromUriParam<P, IpAddr> for IpAddr where
    P: UriPart, 

type Target = IpAddr

pub fn from_uri_param(param: IpAddr) -> IpAddr

impl<'x, 'a> FromUriParam<Path, &'x mut &'a Path> for &'a Path

type Target = &'x mut &'a Path

pub fn from_uri_param(param: &'x mut &'a Path) -> &'x mut &'a Path

impl<'x, P> FromUriParam<P, &'x mut u128> for u128 where
    P: UriPart, 

type Target = &'x mut u128

pub fn from_uri_param(param: &'x mut u128) -> &'x mut u128

impl<'x, P> FromUriParam<P, &'x mut u64> for u64 where
    P: UriPart, 

type Target = &'x mut u64

pub fn from_uri_param(param: &'x mut u64) -> &'x mut u64

impl<A, E, T> FromUriParam<Query, Result<A, E>> for Result<T, E> where
    T: FromUriParam<Query, A>, 

type Target = Result<<T as FromUriParam<Query, A>>::Target, E>

pub fn from_uri_param(
    param: Result<A, E>
) -> <Result<T, E> as FromUriParam<Query, Result<A, E>>>::Target

impl<'x, P> FromUriParam<P, &'x Ipv4Addr> for Ipv4Addr where
    P: UriPart, 

type Target = &'x Ipv4Addr

pub fn from_uri_param(param: &'x Ipv4Addr) -> &'x Ipv4Addr

impl<'x, P> FromUriParam<P, &'x u16> for u16 where
    P: UriPart, 

type Target = &'x u16

pub fn from_uri_param(param: &'x u16) -> &'x u16

impl<'x, P> FromUriParam<P, &'x mut f32> for f32 where
    P: UriPart, 

type Target = &'x mut f32

pub fn from_uri_param(param: &'x mut f32) -> &'x mut f32

impl<'x, 'a, P> FromUriParam<P, &'x &'a str> for &'a str where
    P: UriPart, 

type Target = &'x &'a str

pub fn from_uri_param(param: &'x &'a str) -> &'x &'a str

impl<P> FromUriParam<P, i128> for i128 where
    P: UriPart, 

type Target = i128

pub fn from_uri_param(param: i128) -> i128

impl<'a, P> FromUriParam<P, &'a str> for &'a str where
    P: UriPart, 

type Target = &'a str

pub fn from_uri_param(param: &'a str) -> &'a str

impl<'x, 'a> FromUriParam<Path, &'x &'a Path> for &'a Path

type Target = &'x &'a Path

pub fn from_uri_param(param: &'x &'a Path) -> &'x &'a Path

impl<P> FromUriParam<P, i32> for i32 where
    P: UriPart, 

type Target = i32

pub fn from_uri_param(param: i32) -> i32

impl<'x, 'a, P> FromUriParam<P, &'x mut &'a str> for String where
    P: UriPart, 

type Target = &'x mut &'a str

pub fn from_uri_param(param: &'x mut &'a str) -> &'x mut &'a str

impl<'x, P> FromUriParam<P, &'x u32> for u32 where
    P: UriPart, 

type Target = &'x u32

pub fn from_uri_param(param: &'x u32) -> &'x u32

impl<A, E, T> FromUriParam<Query, Option<A>> for Result<T, E> where
    T: FromUriParam<Query, A>, 

type Target = Option<<T as FromUriParam<Query, A>>::Target>

pub fn from_uri_param(
    param: Option<A>
) -> <Result<T, E> as FromUriParam<Query, Option<A>>>::Target

impl<'a, 'b> FromUriParam<Path, &'a &'b str> for PathBuf

A no cost conversion allowing an &&str to be used in place of a PathBuf.

type Target = &'b Path

pub fn from_uri_param(param: &'a &'b str) -> &'b Path

impl<A, E, T> FromUriParam<Query, Result<A, E>> for Option<T> where
    T: FromUriParam<Query, A>, 

type Target = Result<<T as FromUriParam<Query, A>>::Target, E>

pub fn from_uri_param(
    param: Result<A, E>
) -> <Option<T> as FromUriParam<Query, Result<A, E>>>::Target

impl<'x, P> FromUriParam<P, &'x i16> for i16 where
    P: UriPart, 

type Target = &'x i16

pub fn from_uri_param(param: &'x i16) -> &'x i16

impl<A, E, T> FromUriParam<Path, A> for Result<T, E> where
    T: FromUriParam<Path, A>, 

A no cost conversion allowing T to be used in place of an Result<T, E>.

type Target = <T as FromUriParam<Path, A>>::Target

pub fn from_uri_param(
    param: A
) -> <Result<T, E> as FromUriParam<Path, A>>::Target

impl<'x, P> FromUriParam<P, &'x Ipv6Addr> for Ipv6Addr where
    P: UriPart, 

type Target = &'x Ipv6Addr

pub fn from_uri_param(param: &'x Ipv6Addr) -> &'x Ipv6Addr

impl<'x, 'a, P> FromUriParam<P, &'x mut String> for &'a str where
    P: UriPart, 

type Target = &'x mut String

pub fn from_uri_param(param: &'x mut String) -> &'x mut String

impl<P> FromUriParam<P, bool> for bool where
    P: UriPart, 

type Target = bool

pub fn from_uri_param(param: bool) -> bool

impl<P> FromUriParam<P, Ipv4Addr> for Ipv4Addr where
    P: UriPart, 

type Target = Ipv4Addr

pub fn from_uri_param(param: Ipv4Addr) -> Ipv4Addr

impl<'a, P> FromUriParam<P, String> for &'a str where
    P: UriPart, 

type Target = String

pub fn from_uri_param(param: String) -> String

impl<P> FromUriParam<P, u64> for u64 where
    P: UriPart, 

type Target = u64

pub fn from_uri_param(param: u64) -> u64

impl<'x, P> FromUriParam<P, &'x mut i32> for i32 where
    P: UriPart, 

type Target = &'x mut i32

pub fn from_uri_param(param: &'x mut i32) -> &'x mut i32

impl<'a> FromUriParam<Path, &'a Path> for &'a Path

type Target = &'a Path

pub fn from_uri_param(param: &'a Path) -> &'a Path

impl<P> FromUriParam<P, f64> for f64 where
    P: UriPart, 

type Target = f64

pub fn from_uri_param(param: f64) -> f64

impl<'x, P> FromUriParam<P, &'x u8> for u8 where
    P: UriPart, 

type Target = &'x u8

pub fn from_uri_param(param: &'x u8) -> &'x u8

impl<'x> FromUriParam<Path, &'x mut PathBuf> for PathBuf

type Target = &'x mut PathBuf

pub fn from_uri_param(param: &'x mut PathBuf) -> &'x mut PathBuf

impl<'x, P> FromUriParam<P, &'x i32> for i32 where
    P: UriPart, 

type Target = &'x i32

pub fn from_uri_param(param: &'x i32) -> &'x i32

impl<'x, 'a, P> FromUriParam<P, &'x &'a str> for String where
    P: UriPart, 

type Target = &'x &'a str

pub fn from_uri_param(param: &'x &'a str) -> &'x &'a str

impl<'x, P> FromUriParam<P, &'x f64> for f64 where
    P: UriPart, 

type Target = &'x f64

pub fn from_uri_param(param: &'x f64) -> &'x f64

impl<'x, P> FromUriParam<P, &'x mut IpAddr> for IpAddr where
    P: UriPart, 

type Target = &'x mut IpAddr

pub fn from_uri_param(param: &'x mut IpAddr) -> &'x mut IpAddr

impl<'x, P> FromUriParam<P, &'x mut u16> for u16 where
    P: UriPart, 

type Target = &'x mut u16

pub fn from_uri_param(param: &'x mut u16) -> &'x mut u16

impl<'x, P> FromUriParam<P, &'x isize> for isize where
    P: UriPart, 

type Target = &'x isize

pub fn from_uri_param(param: &'x isize) -> &'x isize

impl<'x, 'a> FromUriParam<Path, &'x &'a Path> for PathBuf

type Target = &'x &'a Path

pub fn from_uri_param(param: &'x &'a Path) -> &'x &'a Path

impl<'x, P> FromUriParam<P, &'x mut isize> for isize where
    P: UriPart, 

type Target = &'x mut isize

pub fn from_uri_param(param: &'x mut isize) -> &'x mut isize

impl<'x, P> FromUriParam<P, &'x mut f64> for f64 where
    P: UriPart, 

type Target = &'x mut f64

pub fn from_uri_param(param: &'x mut f64) -> &'x mut f64

impl<P> FromUriParam<P, i8> for i8 where
    P: UriPart, 

type Target = i8

pub fn from_uri_param(param: i8) -> i8

impl<P> FromUriParam<P, u128> for u128 where
    P: UriPart, 

type Target = u128

pub fn from_uri_param(param: u128) -> u128

impl<'x, P> FromUriParam<P, &'x mut u32> for u32 where
    P: UriPart, 

type Target = &'x mut u32

pub fn from_uri_param(param: &'x mut u32) -> &'x mut u32

impl<'a, P> FromUriParam<P, &'a str> for String where
    P: UriPart, 

type Target = &'a str

pub fn from_uri_param(param: &'a str) -> &'a str

impl<A, T> FromUriParam<Path, A> for Option<T> where
    T: FromUriParam<Path, A>, 

A no cost conversion allowing any T to be used in place of an Option<T>.

type Target = <T as FromUriParam<Path, A>>::Target

pub fn from_uri_param(param: A) -> <Option<T> as FromUriParam<Path, A>>::Target

impl<'x, 'a, P> FromUriParam<P, &'x mut &'a str> for &'a str where
    P: UriPart, 

type Target = &'x mut &'a str

pub fn from_uri_param(param: &'x mut &'a str) -> &'x mut &'a str

impl<'x, P> FromUriParam<P, &'x mut u8> for u8 where
    P: UriPart, 

type Target = &'x mut u8

pub fn from_uri_param(param: &'x mut u8) -> &'x mut u8

impl<P> FromUriParam<P, u8> for u8 where
    P: UriPart, 

type Target = u8

pub fn from_uri_param(param: u8) -> u8

impl<'x, P> FromUriParam<P, &'x mut i64> for i64 where
    P: UriPart, 

type Target = &'x mut i64

pub fn from_uri_param(param: &'x mut i64) -> &'x mut i64

impl<'x, 'a> FromUriParam<Path, &'x mut &'a Path> for PathBuf

type Target = &'x mut &'a Path

pub fn from_uri_param(param: &'x mut &'a Path) -> &'x mut &'a Path

impl<'x, 'a> FromUriParam<Path, &'x mut PathBuf> for &'a Path

type Target = &'x mut PathBuf

pub fn from_uri_param(param: &'x mut PathBuf) -> &'x mut PathBuf

impl<'a, P> FromUriParam<P, Cow<'a, str>> for Cow<'a, str> where
    P: UriPart, 

type Target = Cow<'a, str>

pub fn from_uri_param(param: Cow<'a, str>) -> Cow<'a, str>

impl<'x, P> FromUriParam<P, &'x u128> for u128 where
    P: UriPart, 

type Target = &'x u128

pub fn from_uri_param(param: &'x u128) -> &'x u128

impl<'x, P> FromUriParam<P, &'x u64> for u64 where
    P: UriPart, 

type Target = &'x u64

pub fn from_uri_param(param: &'x u64) -> &'x u64

impl<P> FromUriParam<P, i16> for i16 where
    P: UriPart, 

type Target = i16

pub fn from_uri_param(param: i16) -> i16

impl<P> FromUriParam<P, String> for String where
    P: UriPart, 

type Target = String

pub fn from_uri_param(param: String) -> String

impl<'x, P> FromUriParam<P, &'x mut Ipv4Addr> for Ipv4Addr where
    P: UriPart, 

type Target = &'x mut Ipv4Addr

pub fn from_uri_param(param: &'x mut Ipv4Addr) -> &'x mut Ipv4Addr

Loading content...

Implementors

impl<'f, A, T: FromUriParam<Query, A> + FromForm<'f>> FromUriParam<Query, A> for Lenient<T>

type Target = T::Target

fn from_uri_param(param: A) -> Self::Target

impl<'f, A, T: FromUriParam<Query, A> + FromForm<'f>> FromUriParam<Query, A> for Strict<T>

type Target = T::Target

fn from_uri_param(param: A) -> Self::Target

Loading content...