Struct Formatter

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

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_value(), the nested names are joined by a ., written out followed by a =, followed by the value.

Usage

Usage is fairly straightforward:

• For every named value you wish to emit, call write_named_value().
• For every unnamed value you wish to emit, call write_value().
• To write a string directly, call write_raw().

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,

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

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

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

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

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

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