Struct rocket::http::uri::fmt::Formatter[]

pub struct Formatter<'i, P> where
    P: Part
{ /* fields omitted */ }
Expand description

A struct used to format strings for UriDisplay.

Marker Generic: Formatter<Path> vs. Formatter<Query>

Like UriDisplay, the Part parameter P in Formatter<P> must be either Path or Query resulting in either Formatter<Path> or Formatter<Query>. The Path version is used when formatting parameters in the path part of the URI while the Query version is used when formatting parameters in the query part of the URI. The write_named_value() method is only available to UriDisplay<Query>.

Overview

A mutable version of this struct is passed to UriDisplay::fmt(). This struct properly formats series of values for use in URIs. In particular, this struct applies the following transformations:

  • When multiple values are written, they are separated by / for Path types and & for Query types.

Additionally, for Formatter<Query>:

  • When a named value is written with write_named_value(), the name is written out, followed by a =, followed by the value.

  • When nested named values are written, typically by passing a value to write_named_value() whose implementation of UriDisplay also calls write_named_vlaue(), the nested names are joined by a ., written out followed by a =, followed by the value.

Usage

Usage is fairly straightforward:

The write_named_value method automatically prefixes the name to the written value and, along with write_value and write_raw, handles nested calls to write_named_value automatically, prefixing names when necessary. Unlike the other methods, write_raw does not prefix any nested names every time it is called. Instead, it only prefixes the first time it is called, after a call to write_named_value or write_value, or after a call to refresh().

Example

The following example uses all of the write methods in a varied order to display the semantics of Formatter<Query>. Note that UriDisplay should rarely be implemented manually, preferring to use the derive, and that this implementation is purely demonstrative.

use std::fmt;

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

struct Outer {
    value: Inner,
    another: usize,
    extra: usize
}

struct Inner {
    value: usize,
    extra: usize
}

impl UriDisplay<Query> for Outer {
    fn fmt(&self, f: &mut Formatter<Query>) -> fmt::Result {
        f.write_named_value("outer_field", &self.value)?;
        f.write_named_value("another", &self.another)?;
        f.write_raw("out")?;
        f.write_raw("side")?;
        f.write_value(&self.extra)
    }
}

impl UriDisplay<Query> for Inner {
    fn fmt(&self, f: &mut Formatter<Query>) -> fmt::Result {
        f.write_named_value("inner_field", &self.value)?;
        f.write_value(&self.extra)?;
        f.write_raw("inside")
    }
}

let inner = Inner { value: 0, extra: 1 };
let outer = Outer { value: inner, another: 2, extra: 3 };
let uri_string = format!("{}", &outer as &dyn UriDisplay<Query>);
assert_eq!(uri_string, "outer_field.inner_field=0&\
                        outer_field=1&\
                        outer_field=inside&\
                        another=2&\
                        outside&\
                        3");

Note that you can also use the write! macro to write directly to the formatter as long as the std::fmt::Write trait is in scope. Internally, the write! macro calls write_raw(), so care must be taken to ensure that the written string is URI-safe.

use std::fmt::{self, Write};

use rocket::http::uri::fmt::{UriDisplay, Formatter, Part, Path, Query};

pub struct Complex(u8, u8);

impl<P: Part> UriDisplay<P> for Complex {
    fn fmt(&self, f: &mut Formatter<P>) -> fmt::Result {
        write!(f, "{}+{}", self.0, self.1)
    }
}

let uri_string = format!("{}", &Complex(42, 231) as &dyn UriDisplay<Path>);
assert_eq!(uri_string, "42+231");

#[derive(UriDisplayQuery)]
struct Message {
    number: Complex,
}

let message = Message { number: Complex(42, 47) };
let uri_string = format!("{}", &message as &dyn UriDisplay<Query>);
assert_eq!(uri_string, "number=42+47");

Implementations

impl<'i, P> Formatter<'i, P> where
    P: Part

pub fn write_raw<S>(&mut self, string: S) -> Result<(), Error> where
    S: AsRef<str>, 

Writes string to self.

If self is fresh (after a call to other write_ methods or refresh()), prefixes any names and adds separators as necessary.

This method is called by the write! macro.

Example

use std::fmt;

use rocket::http::uri::fmt::{Formatter, UriDisplay, Part, Path};

struct Foo;

impl<P: Part> UriDisplay<P> for Foo {
    fn fmt(&self, f: &mut Formatter<P>) -> fmt::Result {
        f.write_raw("f")?;
        f.write_raw("o")?;
        f.write_raw("o")
    }
}

let foo = Foo;
let uri_string = format!("{}", &foo as &dyn UriDisplay<Path>);
assert_eq!(uri_string, "foo");

pub fn write_value<T>(&mut self, value: T) -> Result<(), Error> where
    T: UriDisplay<P>, 

Writes the unnamed value value. Any nested names are prefixed as necessary.

Refreshes self before and after the value is written.

Example

use std::fmt;

use rocket::http::uri::fmt::{Formatter, UriDisplay, Part, Path, Query};

struct Foo(usize);

impl<P: Part> UriDisplay<P> for Foo {
    fn fmt(&self, f: &mut Formatter<P>) -> fmt::Result {
        f.write_value(&self.0)
    }
}

let foo = Foo(123);

let uri_string = format!("{}", &foo as &dyn UriDisplay<Path>);
assert_eq!(uri_string, "123");

let uri_string = format!("{}", &foo as &dyn UriDisplay<Query>);
assert_eq!(uri_string, "123");

pub fn refresh(&mut self)

Refreshes the formatter.

After refreshing, write_raw() will prefix any nested names as well as insert a separator.

Example

use std::fmt;

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

struct Foo;

impl UriDisplay<Query> for Foo {
    fn fmt(&self, f: &mut Formatter<Query>) -> fmt::Result {
        f.write_raw("a")?;
        f.write_raw("raw")?;
        f.refresh();
        f.write_raw("format")
    }
}

let uri_string = format!("{}", &Foo as &dyn UriDisplay<Query>);
assert_eq!(uri_string, "araw&format");

impl UriDisplay<Path> for Foo {
    fn fmt(&self, f: &mut Formatter<Path>) -> fmt::Result {
        f.write_raw("a")?;
        f.write_raw("raw")?;
        f.refresh();
        f.write_raw("format")
    }
}

let uri_string = format!("{}", &Foo as &dyn UriDisplay<Path>);
assert_eq!(uri_string, "araw/format");

#[derive(UriDisplayQuery)]
struct Message {
    inner: Foo,
}

let msg = Message { inner: Foo };
let uri_string = format!("{}", &msg as &dyn UriDisplay<Query>);
assert_eq!(uri_string, "inner=araw&inner=format");

impl<'_> Formatter<'_, Query>

pub fn write_named_value<T>(
    &mut self,
    name: &str,
    value: T
) -> Result<(), Error> where
    T: UriDisplay<Query>, 

Writes the named value value by prefixing name followed by = to the value. Any nested names are also prefixed as necessary.

Refreshes self before the name is written and after the value is written.

Example

use std::fmt;

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

struct Foo {
    name: usize
}

// Note: This is identical to what #[derive(UriDisplayQuery)] would
// generate! In practice, _always_ use the derive.
impl UriDisplay<Query> for Foo {
    fn fmt(&self, f: &mut Formatter<Query>) -> fmt::Result {
        f.write_named_value("name", &self.name)
    }
}

let foo = Foo { name: 123 };
let uri_string = format!("{}", &foo as &dyn UriDisplay<Query>);
assert_eq!(uri_string, "name=123");

Trait Implementations

impl<'_, P> Write for Formatter<'_, P> where
    P: Part

pub fn write_str(&mut self, s: &str) -> Result<(), Error>

Writes a string slice into this writer, returning whether the write succeeded. Read more

fn write_char(&mut self, c: char) -> Result<(), Error>1.1.0[src]

Writes a char into this writer, returning whether the write succeeded. Read more

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>1.0.0[src]

Glue for usage of the write! macro with implementors of this trait. Read more

Auto Trait Implementations

impl<'i, P> !RefUnwindSafe for Formatter<'i, P>

impl<'i, P> !Send for Formatter<'i, P>

impl<'i, P> !Sync for Formatter<'i, P>

impl<'i, P> Unpin for Formatter<'i, P> where
    P: Unpin

impl<'i, P> !UnwindSafe for Formatter<'i, P>

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

pub fn type_id(&self) -> TypeId[src]

Gets the TypeId of self. Read more

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

pub fn borrow(&self) -> &T[src]

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

pub fn borrow_mut(&mut self) -> &mut T[src]

Mutably borrows from an owned value. Read more

impl<T> From<T> for T[src]

pub fn from(t: T) -> T[src]

Performs the conversion.

impl<T> Instrument for T[src]

fn instrument(self, span: Span) -> Instrumented<Self>[src]

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

fn in_current_span(self) -> Instrumented<Self>[src]

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

pub fn into(self) -> U[src]

Performs the conversion.

impl<T> IntoCollection<T> for T

pub fn into_collection<A>(self) -> SmallVec<A> where
    A: Array<Item = T>, 

Converts self into a collection.

pub fn mapped<U, F, A>(self, f: F) -> SmallVec<A> where
    F: FnMut(T) -> U,
    A: Array<Item = U>, 

impl<T> Same<T> for T

type Output = T

Should always be Self

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]

Performs the conversion.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>[src]

Performs the conversion.

impl<V, T> VZip<V> for T where
    V: MultiLane<T>, 

pub fn vzip(self) -> V