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

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§

source§

impl<M: Multiple> SpecificSize<M>

source

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

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.

source

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

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

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§

source§

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

§

type Err = ParsingError

The associated error which can be returned from parsing.
source§

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

Parses a string s to return a value of this type. Read more
source§

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

source§

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

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

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

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

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

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

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

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

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

source§

impl<M> Eq for SpecificSize<M>where M: Multiple + Copy,

Auto Trait Implementations§

§

impl<M> RefUnwindSafe for SpecificSize<M>where M: RefUnwindSafe,

§

impl<M> Send for SpecificSize<M>where M: Send,

§

impl<M> Sync for SpecificSize<M>where M: Sync,

§

impl<M> Unpin for SpecificSize<M>where M: Unpin,

§

impl<M> UnwindSafe for SpecificSize<M>where M: UnwindSafe,

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, 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> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for Twhere T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
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.