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

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

A struct used to format strings for UriDisplay.

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

Like UriDisplay, the UriPart 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:

Additionally, for Formatter<Query>:

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::{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 &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::{UriDisplay, Formatter, UriPart, Path, Query};

pub struct Complex(u8, u8);

impl<P: UriPart> 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 &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 &UriDisplay<Query>);
assert_eq!(uri_string, "number=42+47");

Methods

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

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::{Formatter, UriDisplay, UriPart, Path};

struct Foo;

impl<P: UriPart> 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 &UriDisplay<Path>);
assert_eq!(uri_string, "foo");

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::{Formatter, UriDisplay, UriPart, Path, Query};

struct Foo(usize);

impl<P: UriPart> 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 &UriDisplay<Path>);
assert_eq!(uri_string, "123");

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

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::{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 &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 &UriDisplay<Path>);
assert_eq!(uri_string, "araw/format");

impl<'i> Formatter<'i, 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::{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 &UriDisplay<Query>);
assert_eq!(uri_string, "name=123");

Trait Implementations

impl<'i, P> Write for Formatter<'i, P> where
    P: UriPart

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

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

Auto Trait Implementations

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

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

Blanket Implementations

impl<T> From for T
[src]

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

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

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

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

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

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

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

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

impl<T> Typeable for T where
    T: Any

Get the TypeId of this object.

impl<T> IntoCollection for T

impl<T, I> AsResult for T where
    I: Input,