Trait rocket_http::uri::fmt::FromUriParam
source · pub trait FromUriParam<P: Part, T> {
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
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: 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§
sourcetype Target: UriDisplay<P>
type Target: UriDisplay<P>
The resulting type of this conversion.
Required Methods§
sourcefn from_uri_param(param: T) -> Self::Target
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§
source§impl<'x, P: Part> FromUriParam<P, &'x NonZeroI128> for NonZeroI128
impl<'x, P: Part> FromUriParam<P, &'x NonZeroI128> for NonZeroI128
type Target = &'x NonZeroI128
fn from_uri_param(param: &'x NonZeroI128) -> &'x NonZeroI128
source§impl<'a, K, V, A, B> FromUriParam<Query, &'a mut BTreeMap<A, B, Global>> for BTreeMap<K, V>where
A: UriDisplay<Query>,
K: FromUriParam<Query, A>,
B: UriDisplay<Query>,
V: FromUriParam<Query, B>,
impl<'a, K, V, A, B> FromUriParam<Query, &'a mut BTreeMap<A, B, Global>> for BTreeMap<K, V>where A: UriDisplay<Query>, K: FromUriParam<Query, A>, B: UriDisplay<Query>, V: FromUriParam<Query, B>,
source§impl<P: Part> FromUriParam<P, NonZeroIsize> for NonZeroIsize
impl<P: Part> FromUriParam<P, NonZeroIsize> for NonZeroIsize
type Target = NonZeroIsize
fn from_uri_param(param: NonZeroIsize) -> NonZeroIsize
source§impl<'a, 'b> FromUriParam<Path, &'a &'b str> for PathBuf
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
.
source§impl<A, E, T: FromUriParam<Path, A>> FromUriParam<Path, A> for Result<T, E>
impl<A, E, T: FromUriParam<Path, A>> FromUriParam<Path, A> for Result<T, E>
A no cost conversion allowing T
to be used in place of an Result<T, E>
.
type Target = <T as FromUriParam<Path, A>>::Target
fn from_uri_param(param: A) -> Self::Target
source§impl<'x, P: Part> FromUriParam<P, &'x NonZeroU16> for NonZeroU16
impl<'x, P: Part> FromUriParam<P, &'x NonZeroU16> for NonZeroU16
type Target = &'x NonZeroU16
fn from_uri_param(param: &'x NonZeroU16) -> &'x NonZeroU16
source§impl<'x, P: Part> FromUriParam<P, &'x mut NonZeroU64> for NonZeroU64
impl<'x, P: Part> FromUriParam<P, &'x mut NonZeroU64> for NonZeroU64
type Target = &'x mut NonZeroU64
fn from_uri_param(param: &'x mut NonZeroU64) -> &'x mut NonZeroU64
source§impl<'x, P: Part> FromUriParam<P, &'x mut PrimitiveDateTime> for PrimitiveDateTime
impl<'x, P: Part> FromUriParam<P, &'x mut PrimitiveDateTime> for PrimitiveDateTime
type Target = &'x mut PrimitiveDateTime
fn from_uri_param(param: &'x mut PrimitiveDateTime) -> &'x mut PrimitiveDateTime
source§impl<'a> FromUriParam<Path, &'a str> 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
.
source§impl<'x, P: Part> FromUriParam<P, &'x SocketAddrV4> for SocketAddrV4
impl<'x, P: Part> FromUriParam<P, &'x SocketAddrV4> for SocketAddrV4
type Target = &'x SocketAddrV4
fn from_uri_param(param: &'x SocketAddrV4) -> &'x SocketAddrV4
source§impl<'x, P: Part> FromUriParam<P, &'x mut NonZeroI16> for NonZeroI16
impl<'x, P: Part> FromUriParam<P, &'x mut NonZeroI16> for NonZeroI16
type Target = &'x mut NonZeroI16
fn from_uri_param(param: &'x mut NonZeroI16) -> &'x mut NonZeroI16
source§impl<P: Part> FromUriParam<P, NonZeroI16> for NonZeroI16
impl<P: Part> FromUriParam<P, NonZeroI16> for NonZeroI16
type Target = NonZeroI16
fn from_uri_param(param: NonZeroI16) -> NonZeroI16
source§impl<K, V, A, B> FromUriParam<Query, BTreeMap<A, B, Global>> for HashMap<K, V>where
A: UriDisplay<Query>,
K: FromUriParam<Query, A>,
B: UriDisplay<Query>,
V: FromUriParam<Query, B>,
impl<K, V, A, B> FromUriParam<Query, BTreeMap<A, B, Global>> for HashMap<K, V>where A: UriDisplay<Query>, K: FromUriParam<Query, A>, B: UriDisplay<Query>, V: FromUriParam<Query, B>,
source§impl<'x, P: Part> FromUriParam<P, &'x NonZeroI64> for NonZeroI64
impl<'x, P: Part> FromUriParam<P, &'x NonZeroI64> for NonZeroI64
type Target = &'x NonZeroI64
fn from_uri_param(param: &'x NonZeroI64) -> &'x NonZeroI64
source§impl<'x, P: Part> FromUriParam<P, &'x mut SocketAddrV4> for SocketAddrV4
impl<'x, P: Part> FromUriParam<P, &'x mut SocketAddrV4> for SocketAddrV4
type Target = &'x mut SocketAddrV4
fn from_uri_param(param: &'x mut SocketAddrV4) -> &'x mut SocketAddrV4
source§impl<'a, K, V, A, B> FromUriParam<Query, &'a mut HashMap<A, B, RandomState>> for HashMap<K, V>where
A: UriDisplay<Query>,
K: FromUriParam<Query, A>,
B: UriDisplay<Query>,
V: FromUriParam<Query, B>,
impl<'a, K, V, A, B> FromUriParam<Query, &'a mut HashMap<A, B, RandomState>> for HashMap<K, V>where A: UriDisplay<Query>, K: FromUriParam<Query, A>, B: UriDisplay<Query>, V: FromUriParam<Query, B>,
type Target = &'a HashMap<A, B, RandomState>
fn from_uri_param(param: &'a mut HashMap<A, B>) -> Self::Target
source§impl<'x, P: Part> FromUriParam<P, &'x mut NonZeroI128> for NonZeroI128
impl<'x, P: Part> FromUriParam<P, &'x mut NonZeroI128> for NonZeroI128
type Target = &'x mut NonZeroI128
fn from_uri_param(param: &'x mut NonZeroI128) -> &'x mut NonZeroI128
source§impl<'x, P: Part> FromUriParam<P, &'x mut SocketAddrV6> for SocketAddrV6
impl<'x, P: Part> FromUriParam<P, &'x mut SocketAddrV6> for SocketAddrV6
type Target = &'x mut SocketAddrV6
fn from_uri_param(param: &'x mut SocketAddrV6) -> &'x mut SocketAddrV6
source§impl<'a, K, V, A, B> FromUriParam<Query, &'a BTreeMap<A, B, Global>> for HashMap<K, V>where
A: UriDisplay<Query>,
K: FromUriParam<Query, A>,
B: UriDisplay<Query>,
V: FromUriParam<Query, B>,
impl<'a, K, V, A, B> FromUriParam<Query, &'a BTreeMap<A, B, Global>> for HashMap<K, V>where A: UriDisplay<Query>, K: FromUriParam<Query, A>, B: UriDisplay<Query>, V: FromUriParam<Query, B>,
source§impl<A, E, T: FromUriParam<Query, A>> FromUriParam<Query, Result<A, E>> for Result<T, E>
impl<A, E, T: FromUriParam<Query, A>> FromUriParam<Query, Result<A, E>> for Result<T, E>
source§impl<A, T: FromUriParam<Path, A>> FromUriParam<Path, A> for Option<T>
impl<A, T: FromUriParam<Path, A>> FromUriParam<Path, A> for Option<T>
A no cost conversion allowing any T
to be used in place of an Option<T>
.