Struct human_size::SpecificSize

pub struct SpecificSize<M = Any> { /* fields omitted */ }

SpecificSize represents a size in bytes with a multiple.

SpecificSize can be created using the new function, or parsed from a string using the FromStr trait.

use human_size::{SpecificSize, Size, Byte, Any};

let size1 = SpecificSize::new(1000, Byte).unwrap();
assert_eq!(size1.to_string(), "1000 B");

// `Size` is a type alias for `SpecificSize<Any>`.
let size2: Size = "1 kB".parse().unwrap();
assert_eq!(size2.to_string(), "1 kB");

// Even though the multiples are different we can still compare them.
assert_eq!(size1, size2);

Creating a SpecificSize with a specific Multiple, e.g. Kilobyte, only uses 8 bytes. Using the generic mulitple, i.e. Any, it can represent all multiples but requires an extra 8 bytes for a total of 16 bytes.

use std::mem;

use human_size::{SpecificSize, Size, Byte, Any};

assert_eq!(mem::size_of::<SpecificSize<Byte>>(), 8);
assert_eq!(mem::size_of::<Size>(), 16);

Notes

When comparing sizes with one another it is to possible compare different multiples, see the first example above. However due to a lack of precision in floating point numbers equality ignores a difference less then 0.00000001, after applying the multiple. See the PartialEq implementation (via [src] to the right) for details.

The same is true for converting to and from multiples, here again the lack of precision of floating points can be cause of bugs.

Methods

impl<M: Multiple> SpecificSize<M>

pub fn new<V>(     value: V,     multiple: M ) -> Result<SpecificSize<M>, InvalidValueError> where     V: Into<f64>,

Create a new SpecificSize with the given value and multiple. If the value is not normal this will return an error, however zero is allowed. If the value is normal the result can be safely unwraped.

use std::f64;
use human_size::{SpecificSize, Kilobyte, InvalidValueError};

let size = SpecificSize::new(100, Kilobyte).unwrap();
assert_eq!(size.to_string(), "100 kB");

let res = SpecificSize::new(f64::NAN, Kilobyte);
assert_eq!(res, Err(InvalidValueError)); // NAN is not a valid number.

pub fn into<M2>(self) -> SpecificSize<M2> where     M2: Multiple,

Conversion between sizes with different multiples.

This allows a size with one multiple to be converted into a size with another multiple.

use human_size::{SpecificSize, Byte, Kilobyte};

let size = SpecificSize::new(1, Kilobyte).unwrap();
let size2: SpecificSize<Byte> = size.into();

assert_eq!(size, size2);
assert_eq!(size.to_string(), "1 kB");
assert_eq!(size2.to_string(), "1000 B");

Notes

Normally this would be done by implementing the From or Into trait. However currently this is not possible due to the blanket implementation in the standard library. Maybe once specialisation is available this can be resolved.

pub fn value(self) -> f64

Returns the size in current the multiple.

use human_size::{SpecificSize, Kilobyte};

let size = SpecificSize::new(1, Kilobyte).unwrap();

assert_eq!(size.value(), 1.0);

pub fn multiple(self) -> M

Returns the multiple.

use human_size::{SpecificSize, Any, Kilobyte};

let size1 = SpecificSize::new(1, Kilobyte).unwrap();
let size2 = SpecificSize::new(1, Any::Kilobyte).unwrap();

assert_eq!(size1.multiple(), Kilobyte);
assert_eq!(size2.multiple(), Any::Kilobyte);

Trait Implementations

impl<M: Copy> Copy for SpecificSize<M>

impl<M: Clone> Clone for SpecificSize<M>

fn clone(&self) -> SpecificSize<M>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<M: Debug> Debug for SpecificSize<M>

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

Formats the value using the given formatter.

impl<M: Multiple> FromStr for SpecificSize<M>

type Err = ParsingError

The associated error which can be returned from parsing.

fn from_str(input: &str) -> Result<SpecificSize<M>, Self::Err>

Parses a string s to return a value of this type.

impl<LM, RM> PartialEq<SpecificSize<RM>> for SpecificSize<LM> where     LM: Multiple + Copy,     RM: Multiple + Copy,

fn eq(&self, other: &SpecificSize<RM>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<LM, RM> PartialOrd<SpecificSize<RM>> for SpecificSize<LM> where     LM: Multiple + Copy,     RM: Multiple + Copy,

fn partial_cmp(&self, other: &SpecificSize<RM>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<M: Display> Display for SpecificSize<M>

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

Formats the value using the given formatter.