Trait rocket::http::uri::FromUriParam [−]
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
toString
String
to&str
T
toForm<T>
The following conversions are implemented only in Path
:
&str
to&Path
&str
toPathBuf
PathBuf
to&Path
T
toOption<T>
T
toResult<T, E>
The following conversions are implemented only in [Query
]:
Option<T>
toResult<T, E>
(for anyE
)Result<T, E>
toOption<T>
(for anyE
)
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.
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.
Implementations on Foreign Types
impl<'x, P> FromUriParam<P, &'x mut Ipv6Addr> for Ipv6Addr where
P: UriPart,
P: UriPart,
type Target = &'x mut Ipv6Addr
pub fn from_uri_param(param: &'x mut Ipv6Addr) -> &'x mut Ipv6Addr
impl<'x, P> FromUriParam<P, &'x i16> for i16 where
P: UriPart,
P: UriPart,
type Target = &'x i16
pub fn from_uri_param(param: &'x i16) -> &'x i16
impl<P> FromUriParam<P, u16> for u16 where
P: UriPart,
P: UriPart,
type Target = u16
pub fn from_uri_param(param: u16) -> u16
impl<'x, P> FromUriParam<P, &'x isize> for isize where
P: UriPart,
P: UriPart,
type Target = &'x isize
pub fn from_uri_param(param: &'x isize) -> &'x isize
impl<'x, P> FromUriParam<P, &'x u64> for u64 where
P: UriPart,
P: UriPart,
type Target = &'x u64
pub fn from_uri_param(param: &'x u64) -> &'x u64
impl<A, E, T> FromUriParam<Path, A> for Result<T, E> where
T: FromUriParam<Path, A>,
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
param: A
) -> <Result<T, E> as FromUriParam<Path, A>>::Target
impl<P> FromUriParam<P, bool> for bool where
P: UriPart,
P: UriPart,
type Target = bool
pub fn from_uri_param(param: bool) -> bool
impl<A, T> FromUriParam<Path, A> for Option<T> where
T: FromUriParam<Path, A>,
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<'a> FromUriParam<Path, &'a Path> for PathBuf
type Target = &'a Path
pub fn from_uri_param(param: &'a Path) -> &'a Path
impl<'x, P> FromUriParam<P, &'x mut f32> for f32 where
P: UriPart,
P: UriPart,
type Target = &'x mut f32
pub fn from_uri_param(param: &'x mut f32) -> &'x mut f32
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 mut i32> for i32 where
P: UriPart,
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<'x, P> FromUriParam<P, &'x mut i8> for i8 where
P: UriPart,
P: UriPart,
type Target = &'x mut i8
pub fn from_uri_param(param: &'x mut i8) -> &'x mut i8
impl<P> FromUriParam<P, u32> for u32 where
P: UriPart,
P: UriPart,
type Target = u32
pub fn from_uri_param(param: u32) -> u32
impl<'x, P> FromUriParam<P, &'x mut u16> for u16 where
P: UriPart,
P: UriPart,
type Target = &'x mut u16
pub fn from_uri_param(param: &'x mut u16) -> &'x mut u16
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<'x, P> FromUriParam<P, &'x i64> for i64 where
P: UriPart,
P: UriPart,
type Target = &'x i64
pub fn from_uri_param(param: &'x i64) -> &'x i64
impl<'x, P> FromUriParam<P, &'x Ipv6Addr> for Ipv6Addr where
P: UriPart,
P: UriPart,
type Target = &'x Ipv6Addr
pub fn from_uri_param(param: &'x Ipv6Addr) -> &'x Ipv6Addr
impl<'x, P> FromUriParam<P, &'x f32> for f32 where
P: UriPart,
P: UriPart,
type Target = &'x f32
pub fn from_uri_param(param: &'x f32) -> &'x f32
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<P> FromUriParam<P, IpAddr> for IpAddr where
P: UriPart,
P: UriPart,
type Target = IpAddr
pub fn from_uri_param(param: IpAddr) -> IpAddr
impl<'x, P> FromUriParam<P, &'x i8> for i8 where
P: UriPart,
P: UriPart,
type Target = &'x i8
pub fn from_uri_param(param: &'x i8) -> &'x i8
impl<'x, P> FromUriParam<P, &'x u32> for u32 where
P: UriPart,
P: UriPart,
type Target = &'x u32
pub fn from_uri_param(param: &'x u32) -> &'x u32
impl<'x, P> FromUriParam<P, &'x f64> for f64 where
P: UriPart,
P: UriPart,
type Target = &'x f64
pub fn from_uri_param(param: &'x f64) -> &'x f64
impl<A, E, T> FromUriParam<Query, Option<A>> for Result<T, E> where
T: FromUriParam<Query, A>,
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
param: Option<A>
) -> <Result<T, E> as FromUriParam<Query, Option<A>>>::Target
impl<'x, P> FromUriParam<P, &'x mut String> for String where
P: UriPart,
P: UriPart,
type Target = &'x mut String
pub fn from_uri_param(param: &'x mut String) -> &'x mut String
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,
P: UriPart,
impl<'x, P> FromUriParam<P, &'x mut i64> for i64 where
P: UriPart,
P: UriPart,
type Target = &'x mut i64
pub fn from_uri_param(param: &'x mut i64) -> &'x mut i64
impl<'x, 'a, P> FromUriParam<P, &'x &'a str> for &'a str where
P: UriPart,
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 mut u8> for u8 where
P: UriPart,
P: UriPart,
type Target = &'x mut u8
pub fn from_uri_param(param: &'x mut u8) -> &'x mut u8
impl<P> FromUriParam<P, u128> for u128 where
P: UriPart,
P: UriPart,
type Target = u128
pub fn from_uri_param(param: u128) -> u128
impl<'x, P> FromUriParam<P, &'x IpAddr> for IpAddr where
P: UriPart,
P: UriPart,
type Target = &'x IpAddr
pub fn from_uri_param(param: &'x IpAddr) -> &'x IpAddr
impl<'x, P> FromUriParam<P, &'x mut bool> for bool where
P: UriPart,
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 u16> for u16 where
P: UriPart,
P: UriPart,
type Target = &'x u16
pub fn from_uri_param(param: &'x u16) -> &'x u16
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 u8> for u8 where
P: UriPart,
P: UriPart,
type Target = &'x u8
pub fn from_uri_param(param: &'x u8) -> &'x u8
impl<P> FromUriParam<P, String> for String where
P: UriPart,
P: UriPart,
type Target = String
pub fn from_uri_param(param: String) -> String
impl<'x, P> FromUriParam<P, &'x mut u32> for u32 where
P: UriPart,
P: UriPart,
type Target = &'x mut u32
pub fn from_uri_param(param: &'x mut u32) -> &'x mut u32
impl<'x, P> FromUriParam<P, &'x mut u64> for u64 where
P: UriPart,
P: UriPart,
type Target = &'x mut u64
pub fn from_uri_param(param: &'x mut u64) -> &'x mut u64
impl<'a> FromUriParam<Path, PathBuf> for &'a Path
type Target = PathBuf
pub fn from_uri_param(param: PathBuf) -> PathBuf
impl<P> FromUriParam<P, i128> for i128 where
P: UriPart,
P: UriPart,
type Target = i128
pub fn from_uri_param(param: i128) -> i128
impl<P> FromUriParam<P, i8> for i8 where
P: UriPart,
P: UriPart,
type Target = i8
pub fn from_uri_param(param: i8) -> i8
impl<'x, P> FromUriParam<P, &'x mut IpAddr> for IpAddr where
P: UriPart,
P: UriPart,
type Target = &'x mut IpAddr
pub fn from_uri_param(param: &'x mut IpAddr) -> &'x mut IpAddr
impl<'a, P> FromUriParam<P, &'a str> for &'a str where
P: UriPart,
P: UriPart,
type Target = &'a str
pub fn from_uri_param(param: &'a str) -> &'a str
impl<'x, P> FromUriParam<P, &'x usize> for usize where
P: UriPart,
P: UriPart,
type Target = &'x usize
pub fn from_uri_param(param: &'x usize) -> &'x usize
impl<P> FromUriParam<P, i32> for i32 where
P: UriPart,
P: UriPart,
type Target = i32
pub fn from_uri_param(param: i32) -> i32
impl<'x, 'a, P> FromUriParam<P, &'x &'a str> for String where
P: UriPart,
P: UriPart,
type Target = &'x &'a str
pub fn from_uri_param(param: &'x &'a str) -> &'x &'a str
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<'a, P> FromUriParam<P, &'a str> for String where
P: UriPart,
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 PathBuf
type Target = &'x &'a Path
pub fn from_uri_param(param: &'x &'a Path) -> &'x &'a Path
impl<'x, 'a, P> FromUriParam<P, &'x mut &'a str> for String where
P: UriPart,
P: UriPart,
type Target = &'x mut &'a str
pub fn from_uri_param(param: &'x mut &'a str) -> &'x mut &'a str
impl<P> FromUriParam<P, usize> for usize where
P: UriPart,
P: UriPart,
type Target = usize
pub fn from_uri_param(param: usize) -> usize
impl<'x, 'a, P> FromUriParam<P, &'x String> for &'a str where
P: UriPart,
P: UriPart,
type Target = &'x String
pub fn from_uri_param(param: &'x String) -> &'x String
impl<P> FromUriParam<P, i64> for i64 where
P: UriPart,
P: UriPart,
type Target = i64
pub fn from_uri_param(param: i64) -> i64
impl<'x, P> FromUriParam<P, &'x u128> for u128 where
P: UriPart,
P: UriPart,
type Target = &'x u128
pub fn from_uri_param(param: &'x u128) -> &'x u128
impl<P> FromUriParam<P, isize> for isize where
P: UriPart,
P: UriPart,
type Target = isize
pub fn from_uri_param(param: isize) -> isize
impl<A, T> FromUriParam<Query, Option<A>> for Option<T> where
T: FromUriParam<Query, A>,
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
param: Option<A>
) -> <Option<T> as FromUriParam<Query, Option<A>>>::Target
impl<P> FromUriParam<P, u64> for u64 where
P: UriPart,
P: UriPart,
type Target = u64
pub fn from_uri_param(param: u64) -> u64
impl<'x> FromUriParam<Path, &'x PathBuf> for PathBuf
type Target = &'x PathBuf
pub fn from_uri_param(param: &'x PathBuf) -> &'x PathBuf
impl<'x, P> FromUriParam<P, &'x bool> for bool where
P: UriPart,
P: UriPart,
type Target = &'x bool
pub fn from_uri_param(param: &'x bool) -> &'x bool
impl<'x, P> FromUriParam<P, &'x String> for String where
P: UriPart,
P: UriPart,
type Target = &'x String
pub fn from_uri_param(param: &'x String) -> &'x String
impl<'x, P> FromUriParam<P, &'x mut isize> for isize where
P: UriPart,
P: UriPart,
type Target = &'x mut isize
pub fn from_uri_param(param: &'x mut isize) -> &'x mut isize
impl<A, E, T> FromUriParam<Query, Result<A, E>> for Option<T> where
T: FromUriParam<Query, A>,
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
param: Result<A, E>
) -> <Option<T> as FromUriParam<Query, Result<A, E>>>::Target
impl<P> FromUriParam<P, u8> for u8 where
P: UriPart,
P: UriPart,
type Target = u8
pub fn from_uri_param(param: u8) -> u8
impl<'x, 'a, P> FromUriParam<P, &'x mut String> for &'a str where
P: UriPart,
P: UriPart,
type Target = &'x mut String
pub fn from_uri_param(param: &'x mut String) -> &'x mut String
impl<P> FromUriParam<P, i16> for i16 where
P: UriPart,
P: UriPart,
type Target = i16
pub fn from_uri_param(param: i16) -> i16
impl<'x, P> FromUriParam<P, &'x i32> for i32 where
P: UriPart,
P: UriPart,
type Target = &'x i32
pub fn from_uri_param(param: &'x i32) -> &'x i32
impl<'x, 'a, P> FromUriParam<P, &'x mut Cow<'a, str>> for Cow<'a, str> where
P: UriPart,
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 u128> for u128 where
P: UriPart,
P: UriPart,
type Target = &'x mut u128
pub fn from_uri_param(param: &'x mut u128) -> &'x mut u128
impl<P> FromUriParam<P, f64> for f64 where
P: UriPart,
P: UriPart,
type Target = f64
pub fn from_uri_param(param: f64) -> f64
impl<'a, P> FromUriParam<P, String> for &'a str where
P: UriPart,
P: UriPart,
type Target = String
pub fn from_uri_param(param: String) -> String
impl<P> FromUriParam<P, Ipv4Addr> for Ipv4Addr where
P: UriPart,
P: UriPart,
type Target = Ipv4Addr
pub fn from_uri_param(param: Ipv4Addr) -> Ipv4Addr
impl<'x, 'a, P> FromUriParam<P, &'x mut &'a str> for &'a str where
P: UriPart,
P: UriPart,
type Target = &'x mut &'a str
pub fn from_uri_param(param: &'x mut &'a str) -> &'x mut &'a str
impl<P> FromUriParam<P, Ipv6Addr> for Ipv6Addr where
P: UriPart,
P: UriPart,
type Target = Ipv6Addr
pub fn from_uri_param(param: Ipv6Addr) -> Ipv6Addr
impl<P> FromUriParam<P, f32> for f32 where
P: UriPart,
P: UriPart,
type Target = f32
pub fn from_uri_param(param: f32) -> f32
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 Result<T, E> where
T: FromUriParam<Query, A>,
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
param: Result<A, E>
) -> <Result<T, E> as FromUriParam<Query, Result<A, E>>>::Target
impl<'x, P> FromUriParam<P, &'x mut f64> for f64 where
P: UriPart,
P: UriPart,
type Target = &'x mut f64
pub fn from_uri_param(param: &'x mut f64) -> &'x mut f64
impl<'x, P> FromUriParam<P, &'x i128> for i128 where
P: UriPart,
P: UriPart,
type Target = &'x i128
pub fn from_uri_param(param: &'x i128) -> &'x i128
impl<'x, P> FromUriParam<P, &'x Ipv4Addr> for Ipv4Addr where
P: UriPart,
P: UriPart,
type Target = &'x Ipv4Addr
pub fn from_uri_param(param: &'x Ipv4Addr) -> &'x Ipv4Addr
impl FromUriParam<Path, PathBuf> for PathBuf
type Target = PathBuf
pub fn from_uri_param(param: PathBuf) -> PathBuf
impl<'x, P> FromUriParam<P, &'x mut i16> for i16 where
P: UriPart,
P: UriPart,
type Target = &'x mut i16
pub fn from_uri_param(param: &'x mut i16) -> &'x mut i16
impl<'x, P> FromUriParam<P, &'x mut Ipv4Addr> for Ipv4Addr where
P: UriPart,
P: UriPart,
type Target = &'x mut Ipv4Addr
pub fn from_uri_param(param: &'x mut Ipv4Addr) -> &'x mut Ipv4Addr
impl<'x, 'a, P> FromUriParam<P, &'x Cow<'a, str>> for Cow<'a, str> where
P: UriPart,
P: UriPart,
impl<'x, P> FromUriParam<P, &'x mut i128> for i128 where
P: UriPart,
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 mut usize> for usize where
P: UriPart,
P: UriPart,