Trait rocket::http::uri::fmt::FromUriParam

source ·

pub trait FromUriParam<P, T>where
    P: Part,{
    type Target: UriDisplay<P>;

    // Required method
    fn from_uri_param(param: T) -> Self::Target;
}

Expand description

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: Part> FromUriParam<P, T> for T
impl<'x, P: Part> FromUriParam<P, &'x T> for T
impl<'x, P: Part> 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: Part> 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: Part 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::fmt::{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");

Required Associated Types§

source

type Target: UriDisplay

The resulting type of this conversion.

Required Methods§

source

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.

Object Safety§

This trait is not object safe.

Trait rocket::http::uri::fmt::FromUriParam

Required Associated Types§

type Target: UriDisplay<P>

Required Methods§

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

Object Safety§

Implementations on Foreign Types§

impl FromUriParam<Path, PathBuf> for PathBuf

type Target = PathBuf

fn from_uri_param(param: PathBuf) -> PathBuf

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

type Target = &'a Path

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

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

type Target = &'a Path

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

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

type Target = &'a Path

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

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

type Target = PathBuf

fn from_uri_param(param: PathBuf) -> PathBuf

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

type Target = &'b Path

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

impl<'a, P> FromUriParam<P, &'a str> for &'a strwhere P: Part,

type Target = &'a str

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

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

type Target = Cow<'a, str>

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

impl<'a, P> FromUriParam<P, String> for &'a strwhere P: Part,

type Target = String

fn from_uri_param(param: String) -> String

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

type Target = &'x PathBuf

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

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

type Target = &'x mut PathBuf

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

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

type Target = &'x &'a Path

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

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

type Target = &'x &'a Path

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

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

type Target = &'x PathBuf

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

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

type Target = &'x mut &'a Path

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

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

type Target = &'x mut &'a Path

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

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

impl<'x, 'a, P> FromUriParam<P, &'x &'a str> for &'a strwhere P: Part,

type Target = &'x &'a str

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

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

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

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

impl<'x, 'a, P> FromUriParam<P, &'x String> for &'a strwhere P: Part,

type Target = &'x String

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

impl<'x, 'a, P> FromUriParam<P, &'x mut &'a str> for &'a strwhere P: Part,

type Target = &'x mut &'a str

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

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

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

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

impl<'x, 'a, P> FromUriParam<P, &'x mut String> for &'a strwhere P: Part,

type Target = &'x mut String

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

impl<'x, P> FromUriParam<P, &'x IpAddr> for IpAddrwhere P: Part,

type Target = &'x IpAddr

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

impl<'x, P> FromUriParam<P, &'x SocketAddr> for SocketAddrwhere P: Part,

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

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

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

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

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

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

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

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

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

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

impl<'x, P> FromUriParam<P, &'x SocketAddr> for SocketAddr
where P: Part,

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

impl<'x, P> FromUriParam<P, &'x SocketAddrV4> for SocketAddrV4
where P: Part,

impl<'x, P> FromUriParam<P, &'x SocketAddrV6> for SocketAddrV6
where P: Part,