Trait rocket::http::uri::FromUriParam

pub trait FromUriParam<P, T>
where P: UriPart,
{ 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 the impl_from_uri_param_identity macro 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 of type S, <T as FromUriParam<S>>::from_uri_param is invoked. The returned value 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. A similar no-op conversion exists for &RawStr:

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

§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, &RawStr, Cow<str>

The following conversions are implemented, 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
  • &str to RawStr
  • String to &str
  • String to RawStr
  • T to Option<T>
  • T to Result<T, E>
  • T to Form<T>

The following types have identity implementations only in Path:

  • &Path, PathBuf

The following conversions are implemented only in Path:

  • &str to &Path
  • &str to PathBuf
  • PathBuf to &Path

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::RawStr;
use rocket::http::uri::{Formatter, UriDisplay, FromUriParam, Query};

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

impl<'a> UriDisplay<Query> for User<'a> {
    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:

use rocket::http::RawStr;
use rocket::request::Form;

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

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

Required Associated Types§

type Target: UriDisplay<P>

The resulting type of this conversion.

Required Methods§

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.

Implementations on Foreign Types§

§

impl FromUriParam<Path, PathBuf> for PathBuf

§

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

§

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

§

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

§

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

§

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

§

type Target = &'a str

§

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

§

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

§

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: UriPart,

§

type Target = Cow<'a, str>

§

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

§

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

§

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 str
where P: UriPart,

§

type Target = &'x &'a str

§

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

§

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

§

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: UriPart,

§

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 str
where P: UriPart,

§

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 str
where P: UriPart,

§

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 &'a str> for String
where P: UriPart,

§

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: UriPart,

§

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 str
where P: UriPart,

§

type Target = &'x mut String

§

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

§

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

§

type Target = &'x IpAddr

§

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

§

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

§

type Target = &'x bool

§

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

§

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

§

type Target = &'x f32

§

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

§

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

§

type Target = &'x f64

§

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

§

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

§

type Target = &'x i8

§

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

§

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

§

type Target = &'x i16

§

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

§

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

§

type Target = &'x i32

§

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

§

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

§

type Target = &'x i64

§

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

§

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

§

type Target = &'x i128

§

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

§

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

§

type Target = &'x isize

§

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

§

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

§

type Target = &'x u8

§

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

§

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

§

type Target = &'x u16

§

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

§

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

§

type Target = &'x u32

§

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

§

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

§

type Target = &'x u64

§

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

§

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

§

type Target = &'x u128

§

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

§

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

§

type Target = &'x usize

§

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

§

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

§

type Target = &'x String

§

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

§

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

§

type Target = &'x Ipv4Addr

§

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

§

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

§

type Target = &'x Ipv6Addr

§

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

§

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

§

type Target = &'x mut IpAddr

§

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

§

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

§

type Target = &'x mut bool

§

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

§

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

§

type Target = &'x mut f32

§

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

§

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

§

type Target = &'x mut f64

§

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

§

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

§

type Target = &'x mut i8

§

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

§

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

§

type Target = &'x mut i16

§

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

§

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

§

type Target = &'x mut i32

§

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

§

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

§

type Target = &'x mut i64

§

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

§

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

§

type Target = &'x mut i128

§

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

§

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

§

type Target = &'x mut isize

§

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

§

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

§

type Target = &'x mut u8

§

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

§

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

§

type Target = &'x mut u16

§

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

§

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

§

type Target = &'x mut u32

§

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

§

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

§

type Target = &'x mut u64

§

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

§

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

§

type Target = &'x mut u128

§

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

§

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

§

type Target = &'x mut usize

§

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

§

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

§

type Target = &'x mut String

§

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

§

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

§

type Target = &'x mut Ipv4Addr

§

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

§

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

§

type Target = &'x mut Ipv6Addr

§

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

§

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

§

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

§

type Target = bool

§

fn from_uri_param(param: bool) -> bool

§

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

§

type Target = f32

§

fn from_uri_param(param: f32) -> f32

§

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

§

type Target = f64

§

fn from_uri_param(param: f64) -> f64

§

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

§

type Target = i8

§

fn from_uri_param(param: i8) -> i8

§

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

§

type Target = i16

§

fn from_uri_param(param: i16) -> i16

§

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

§

type Target = i32

§

fn from_uri_param(param: i32) -> i32

§

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

§

type Target = i64

§

fn from_uri_param(param: i64) -> i64

§

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

§

type Target = i128

§

fn from_uri_param(param: i128) -> i128

§

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

§

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

§

type Target = u8

§

fn from_uri_param(param: u8) -> u8

§

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

§

type Target = u16

§

fn from_uri_param(param: u16) -> u16

§

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

§

type Target = u32

§

fn from_uri_param(param: u32) -> u32

§

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

§

type Target = u64

§

fn from_uri_param(param: u64) -> u64

§

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

§

type Target = u128

§

fn from_uri_param(param: u128) -> u128

§

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

§

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

§

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

§

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

§

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

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

§

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

§

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

§

impl<P, A, T> FromUriParam<P, A> for Option<T>
where P: UriPart, T: FromUriParam<P, A>,

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

§

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

§

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

Implementors§

§

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

§

type Target = &'a str

§

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

§

type Target = &'a RawStr

§

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

source§

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

source§

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

§

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

§

type Target = &'x &'a str

§

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

§

type Target = &'x mut &'a str

§

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

§

type Target = &'x &'a RawStr

§

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

§

type Target = &'x String

§

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

§

type Target = &'x mut &'a RawStr

§

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

§

type Target = &'x mut String