Struct rocket::http::uri::fmt::Formatter

source ·
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_value(), 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§

source§

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

source

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

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

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

impl Formatter<'_, Query>

source

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§

source§

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

source§

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

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

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

Writes a char into this writer, returning whether the write succeeded. Read more
1.0.0 · source§

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

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§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

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

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

fn in_current_span(self) -> Instrumented<Self>

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

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T> IntoCollection<T> for T

source§

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

Converts self into a collection.
source§

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

source§

impl<T> Paint for Twhere T: ?Sized,

source§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
source§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to Color::Primary.

Example
println!("{}", value.primary());
source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to Color::Fixed.

Example
println!("{}", value.fixed(color));
source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to Color::Rgb.

Example
println!("{}", value.rgb(r, g, b));
source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to Color::Black.

Example
println!("{}", value.black());
source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to Color::Red.

Example
println!("{}", value.red());
source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to Color::Green.

Example
println!("{}", value.green());
source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::Yellow.

Example
println!("{}", value.yellow());
source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::Blue.

Example
println!("{}", value.blue());
source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::Magenta.

Example
println!("{}", value.magenta());
source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::Cyan.

Example
println!("{}", value.cyan());
source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to Color::White.

Example
println!("{}", value.white());
source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlack.

Example
println!("{}", value.bright_black());
source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightRed.

Example
println!("{}", value.bright_red());
source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightGreen.

Example
println!("{}", value.bright_green());
source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightYellow.

Example
println!("{}", value.bright_yellow());
source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlue.

Example
println!("{}", value.bright_blue());
source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightMagenta.

Example
println!("{}", value.bright_magenta());
source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightCyan.

Example
println!("{}", value.bright_cyan());
source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightWhite.

Example
println!("{}", value.bright_white());
source§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
source§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to Color::Primary.

Example
println!("{}", value.on_primary());
source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to Color::Fixed.

Example
println!("{}", value.on_fixed(color));
source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to Color::Rgb.

Example
println!("{}", value.on_rgb(r, g, b));
source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::Black.

Example
println!("{}", value.on_black());
source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::Red.

Example
println!("{}", value.on_red());
source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::Green.

Example
println!("{}", value.on_green());
source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::Yellow.

Example
println!("{}", value.on_yellow());
source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::Blue.

Example
println!("{}", value.on_blue());
source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::Magenta.

Example
println!("{}", value.on_magenta());
source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::Cyan.

Example
println!("{}", value.on_cyan());
source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::White.

Example
println!("{}", value.on_white());
source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlack.

Example
println!("{}", value.on_bright_black());
source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightRed.

Example
println!("{}", value.on_bright_red());
source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightGreen.

Example
println!("{}", value.on_bright_green());
source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightYellow.

Example
println!("{}", value.on_bright_yellow());
source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlue.

Example
println!("{}", value.on_bright_blue());
source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightMagenta.

Example
println!("{}", value.on_bright_magenta());
source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightCyan.

Example
println!("{}", value.on_bright_cyan());
source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightWhite.

Example
println!("{}", value.on_bright_white());
source§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling Attribute value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
source§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Bold.

Example
println!("{}", value.bold());
source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Dim.

Example
println!("{}", value.dim());
source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Italic.

Example
println!("{}", value.italic());
source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Underline.

Example
println!("{}", value.underline());

Returns self with the attr() set to Attribute::Blink.

Example
println!("{}", value.blink());

Returns self with the attr() set to Attribute::RapidBlink.

Example
println!("{}", value.rapid_blink());
source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Invert.

Example
println!("{}", value.invert());
source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Conceal.

Example
println!("{}", value.conceal());
source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Strike.

Example
println!("{}", value.strike());
source§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi Quirk value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
source§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Mask.

Example
println!("{}", value.mask());
source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Wrap.

Example
println!("{}", value.wrap());
source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Linger.

Example
println!("{}", value.linger());
source§

fn clear(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Clear.

Example
println!("{}", value.clear());
source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Bright.

Example
println!("{}", value.bright());
source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::OnBright.

Example
println!("{}", value.on_bright());
source§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the Condition value applies. Replaces any previous condition.

See the crate level docs for more details.

Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
source§

fn new(self) -> Painted<Self>where Self: Sized,

Create a new Painted with a default Style. Read more
source§

fn paint<S>(&self, style: S) -> Painted<&Self>where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
source§

impl<T> Same<T> for T

§

type Output = T

Should always be Self
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

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

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

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

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where S: Into<Dispatch>,

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

fn with_current_subscriber(self) -> WithDispatch<Self>

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