Struct FilesizeFormatter

pub struct FilesizeFormatter { /* private fields */ }

A configurable formatter for Filesizes.

FilesizeFormatter is a builder struct that you can modify via the following methods:

• unit
• show_unit
• precision
• locale

For more information, see the documentation for each of those methods.

Examples

let filesize = Filesize::from_unit(4, FilesizeUnit::KiB).unwrap();
let formatter = FilesizeFormatter::new();

assert_eq!(formatter.unit(FilesizeUnit::B).format(filesize).to_string(), "4096 B");
assert_eq!(formatter.unit(FilesizeUnit::KiB).format(filesize).to_string(), "4 KiB");
assert_eq!(formatter.precision(2).format(filesize).to_string(), "4.09 kB");
assert_eq!(
    formatter
        .unit(FilesizeUnit::B)
        .locale(Locale::en)
        .format(filesize)
        .to_string(),
    "4,096 B",
);

Implementations

impl FilesizeFormatter

pub fn new() -> Self

Create a new, default FilesizeFormatter.

The default formatter has:

• a unit of FilesizeUnitFormat::Metric.
• a show_unit of true.
• a precision of None.
• a locale of Locale::en_US_POSIX (a very plain format with no thousands separators).

pub fn unit(self, unit: impl Into<FilesizeUnitFormat>) -> Self

Set the FilesizeUnitFormat used by the formatter.

A FilesizeUnit or a FilesizeUnitFormat can be provided to this method. FilesizeUnitFormat::Metric and FilesizeUnitFormat::Binary will use a unit of an appropriate scale for each Filesize, whereas providing a FilesizeUnit will use that unit to format all Filesizes.

Examples

let formatter = FilesizeFormatter::new().precision(1);

let filesize = Filesize::from_unit(4, FilesizeUnit::KiB).unwrap();
assert_eq!(formatter.unit(FilesizeUnit::B).format(filesize).to_string(), "4096 B");
assert_eq!(formatter.unit(FilesizeUnitFormat::Binary).format(filesize).to_string(), "4.0 KiB");

let filesize = Filesize::from_unit(4, FilesizeUnit::MiB).unwrap();
assert_eq!(formatter.unit(FilesizeUnitFormat::Metric).format(filesize).to_string(), "4.1 MB");
assert_eq!(formatter.unit(FilesizeUnitFormat::Binary).format(filesize).to_string(), "4.0 MiB");

pub fn show_unit(self, show_unit: bool) -> Self

Sets whether to show or omit the file size unit in the formatted output.

This setting can be used to disable the unit formatting from FilesizeFormatter and instead provide your own.

Note that the FilesizeUnitFormat provided to unit is still used to format the numeric portion of a Filesize. So, setting show_unit to false is only recommended for FilesizeUnitFormat::Unit, since this will keep the unit the same for all Filesizes. FilesizeUnitFormat::Metric and FilesizeUnitFormat::Binary, on the other hand, will adapt the unit to match the magnitude of each formatted Filesize.

Examples

let filesize = Filesize::from_unit(4, FilesizeUnit::KiB).unwrap();
let formatter = FilesizeFormatter::new().show_unit(false);

assert_eq!(formatter.unit(FilesizeUnit::B).format(filesize).to_string(), "4096");
assert_eq!(format!("{} KB", formatter.unit(FilesizeUnit::KiB).format(filesize)), "4 KB");

pub fn precision(self, precision: impl Into<Option<usize>>) -> Self

Set the number of digits to display after the decimal place.

Note that digits after the decimal place will never be shown if:

• unit is FilesizeUnit::B,
• unit is FilesizeUnitFormat::Metric and the number of bytes is less than FilesizeUnit::KB
• unit is FilesizeUnitFormat::Binary and the number of bytes is less than FilesizeUnit::KiB.

Additionally, the precision specified in the format string (i.e., std::fmt::Formatter::precision) will take precedence if is specified. If the format string precision and the FilesizeFormatter’s precision are both None, then all digits after the decimal place, if any, are shown.

Examples

let filesize = Filesize::from_unit(4, FilesizeUnit::KiB).unwrap();
let formatter = FilesizeFormatter::new();

assert_eq!(formatter.precision(2).format(filesize).to_string(), "4.09 kB");
assert_eq!(formatter.precision(0).format(filesize).to_string(), "4 kB");
assert_eq!(formatter.precision(None).format(filesize).to_string(), "4.096 kB");
assert_eq!(
    formatter
        .precision(None)
        .unit(FilesizeUnit::KiB)
        .format(filesize)
        .to_string(),
    "4 KiB",
);
assert_eq!(
    formatter
        .unit(FilesizeUnit::B)
        .precision(2)
        .format(filesize)
        .to_string(),
    "4096 B",
);
assert_eq!(format!("{:.2}", formatter.precision(0).format(filesize)), "4.09 kB");

pub fn locale(self, locale: Locale) -> Self

Set the Locale to use when formatting the numeric portion of a Filesize.

The Locale determines the decimal place character, minus sign character, digit grouping method, and digit separator character.

Examples

let filesize = Filesize::from_unit(-4, FilesizeUnit::MiB).unwrap();
let formatter = FilesizeFormatter::new().unit(FilesizeUnit::KB).precision(1);

assert_eq!(formatter.format(filesize).to_string(), "-4194.3 kB");
assert_eq!(formatter.locale(Locale::en).format(filesize).to_string(), "-4,194.3 kB");
assert_eq!(formatter.locale(Locale::rm).format(filesize).to_string(), "\u{2212}4’194.3 kB");
let filesize = Filesize::from_unit(-4, FilesizeUnit::GiB).unwrap();
assert_eq!(formatter.locale(Locale::ta).format(filesize).to_string(), "-42,94,967.2 kB");

pub fn format(&self, filesize: Filesize) -> FormattedFilesize

Format a Filesize into a FormattedFilesize which implements fmt::Display.

Examples

let filesize = Filesize::from_unit(4, FilesizeUnit::KB).unwrap();
let formatter = FilesizeFormatter::new();

assert_eq!(format!("{}", formatter.format(filesize)), "4 kB");
assert_eq!(formatter.format(filesize).to_string(), "4 kB");

Trait Implementations

impl Clone for FilesizeFormatter

fn clone(&self) -> FilesizeFormatter

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FilesizeFormatter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for FilesizeFormatter

fn default() -> Self

Returns the “default value” for a type.

impl From<FilesizeConfig> for FilesizeFormatter

fn from(config: FilesizeConfig) -> Self

Converts to this type from the input type.

impl Hash for FilesizeFormatter

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for FilesizeFormatter

fn eq(&self, other: &FilesizeFormatter) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for FilesizeFormatter

impl Eq for FilesizeFormatter

impl StructuralPartialEq for FilesizeFormatter