[][src]Trait fmtor::FmtOr

pub trait FmtOr<T> {
    fn fmt_or_empty<'t>(&'t self) -> MaybeFormat<'t, T>;
fn fmt_or<'t, U>(&'t self, u: U) -> MaybeFormatOr<'t, T, U>
    where
        U: Display
;
fn fmt_or_else<'t, U, F>(&'t self, f: F) -> MaybeFormatOrElse<'t, T, F>
    where
        U: Display,
        F: Fn() -> U
; }

An extension trait for Option<T>. The methods on this trait are the inteded way to use this crate.

TLDR

The methods on this trait allow a missing Option<T> value to be formatted as if it were a T, however None is replaced by some other value.

Details

The methods on this trait return types which implement all the same format traits as T. They borrow the Option<T> for the duration of the formatting operation.

When the value is None, the formatting is replaced with another, whose type and value are determined by the user. The replacement type, U, need only implement Display. Regardless of the desired format of T, the format of U will always be Display. This makes it simple to replace non-Display formats with the anticipated values.

fn fallable_box_maker() -> Option<Box<()>> { None }

use fmtor::FmtOr;

let maybe_box = fallable_box_maker();
println!("Got a fallable box at {:p}", maybe_box.fmt_or("Null"));

More formatting logic

Here's a real-ish example with surrounding formatting logic. Formatting is applied to log messages so that they include the optional file name and line number when either the file or both are present. Having just a line number by itself wouldn't be all that helpful.

// Be warned: this is a hypothetical code snippet that may not compile on current versions of amethyst.
// The code is not compiled by doctest, and therefore should not be relied upon as working.

use fmtor::FmtOr;

// Generates log messeges like
// [INFO] src\game\states\init.rs:56 - Init starting
amethyst::Logger::from_config_formatter(config, |out, msg, record| {
    out.finish(format_args!(
        "[{level}] {file}{colon}{line}{spacer}{message}",
        level = record.level(),
        file = record.file().unwrap_or(""), // <-- This could be .fmt_or(""), but is not necessary
        colon = if record.file().is_some() { ":" } else { "" },
        line = record.file().and(record.line()).fmt_or(""), // <-- This could not be .unwrap_or("") due to type error
        spacer = if record.file().is_some() { " - " } else { "" },
        message = msg
    ))
})
.start();

Required methods

fn fmt_or_empty<'t>(&'t self) -> MaybeFormat<'t, T>

Format the value, if there is one, or display an empty string instead.

Example

use fmtor::FmtOr;

let foo = Some(0x42);
let bar: Option<u32> = None;

assert_eq!(
    "0x42",
    format!("{:#x}", foo.fmt_or_empty())
);
assert_eq!(
    "",
    format!("{:#x}", bar.fmt_or_empty())
);

fn fmt_or<'t, U>(&'t self, u: U) -> MaybeFormatOr<'t, T, U> where
    U: Display

Format the value, if there is one, or display the given value instead.

The given value must implement Display regardless of which formatting is used on the original value.

Example

use fmtor::FmtOr;

let foo = Some(Box::new(42));
let bar: Option<Box<u32>> = None;

assert_eq!(
    "foo: 42",
    format!("foo: {}", foo.fmt_or("Null"))
);
assert_eq!(
    "bar: Null",
    format!("bar: {}", bar.fmt_or("Null"))
);

fn fmt_or_else<'t, U, F>(&'t self, f: F) -> MaybeFormatOrElse<'t, T, F> where
    U: Display,
    F: Fn() -> U, 

Format the value, if there is one, or run the closure to get a value to display instead.

The returned value must implement Display regardless of which formatting is used on the original value.

The value returned from the closure is not stored after use. Therefore, using a single MaybeFormatOrElse object for multiple formatting operations will run the closure multiple times.

Example

use fmtor::FmtOr;

let foo = Some(42);
let bar: Option<u32> = None;
let missing_msg = "Missing";
let missing_item = "bar";

assert_eq!(
    "42",
    format!("{}", foo.fmt_or_else(||format!("{} {}", missing_msg, missing_item)))
);
assert_eq!(
    "Missing bar",
    format!("{}", bar.fmt_or_else(||format!("{} {}", missing_msg, missing_item)))
);
Loading content...

Implementations on Foreign Types

impl<T> FmtOr<T> for Option<T>[src]

Loading content...

Implementors

Loading content...