Struct SpecificSize 

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

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 a cause of bugs.

Implementations

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

pub fn to_bytes(self) -> u64

Returns the size as bytes.

Notes

Be careful of truncation for large file size.

Examples

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

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

assert_eq!(size1.to_bytes(), 1000);
assert_eq!(size2.to_bytes(), 8000);

Trait Implementations

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

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

Returns a duplicate 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: Display> Display 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

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<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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

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

impl<M> Eq for SpecificSize<M>

where M: Multiple + Copy,