logo
pub struct Formatter<'i, P> where
    P: Part
{ /* private fields */ }
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

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");

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");

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");

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

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

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

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

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

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

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Converts self into a collection.

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more