Struct size::Size

pub struct Size { /* private fields */ }

Size is the core type exposed by this crate and allows the developer to express a file size (or the general concept of a “size”) as a strongly-typed, convertible type that can be used for textual formatting (“pretty printing”) and mathematical operations.

A size can be created in terms of any supported unit and an associated numeric value of any type.

use size::Size;

// Identical sizes expressed in different units with different primitive types:
assert_eq!(Size::from_kibibytes(2_u8), Size::from_kilobytes(2.048_f64));

Implementations

impl Size

pub const fn from_bytes(bytes: i64) -> Self

Initialize a Size from the provided value, in bytes. This is a constant function and may be used in a const context.

Unlike the other “from” functions (e.g. from_kilobytes()), it is not generic because a) trait methods (required to use a generic type) may not be declared as const, and b) it’s always safe to use as i64 on whatever type you’re actually passing into from_bytes() without any (additional) loss of precision as compared to passing in an arbitrary numeric type, since there is no math required to calculate the equivalent size in bytes.

To further illustrate this point, let’s look at this hypothetical initialization of a Size from a floating-point literal: let s = Size::from_kib(2.5); - when the conversion from “2.5 KiB” to “bytes” happens internally, the result is equivalent to (2.5 * 1024.0) as i64 and yields the correct result of 2560 bytes. But if from_kib weren’t generic and you needed to use as i64 (i.e. Size::from_kib(2.5 as i64)), the calculated size in bytes would start from an already-truncated 2_i64 and yield an incorrect answer of 2048 bytes ((2.5 as i64) * 1024). However, with from_bytes(), there can be no loss of precision (or, pedantically, even truncation) when as i64 is used since the file size, expressed in bytes, must always be a whole number; this means it is safe to perform the integer conversion/rounding at the call site itself and Size::from_bytes(float_val as i64) would necessarily always yield the same result as a hypothetically generic/type-agnostic Size::from_bytes::<f64>(float_val).

pub fn from_kilobytes<T: AsIntermediate>(value: T) -> Self

Express a size in kilobytes. Actual size is 10^3 * the value.

pub fn from_megabytes<T: AsIntermediate>(value: T) -> Self

Express a size in megabytes. Actual size is 10^6 * the value.

pub fn from_gigabytes<T: AsIntermediate>(value: T) -> Self

Express a size in gigabytes. Actual size is 10^9 * the value.

pub fn from_terabytes<T: AsIntermediate>(value: T) -> Self

Express a size in terabytes. Actual size is 10^12 * the value.

pub fn from_petabytes<T: AsIntermediate>(value: T) -> Self

Express a size in petabytes. Actual size is 10^15 * the value.

pub fn from_exabytes<T: AsIntermediate>(value: T) -> Self

Express a size in exabytes. Actual size is 10^18 * the value.

pub fn from_kb<T: AsIntermediate>(value: T) -> Self

Express a size in kilobytes, as a shortcut for using Size::from_kilobytes().

pub fn from_mb<T: AsIntermediate>(value: T) -> Self

Express a size in megabytes, as a shortcut for using Size::from_megabytes().

pub fn from_gb<T: AsIntermediate>(value: T) -> Self

Express a size in gigabytes, as a shortcut for using Size::from_gigabytes().

pub fn from_tb<T: AsIntermediate>(value: T) -> Self

Express a size in terabytes, as a shortcut for using Size::from_terabytes().

pub fn from_pb<T: AsIntermediate>(value: T) -> Self

Express a size in petabytes, as a shortcut for using Size::from_petabytes().

pub fn from_eb<T: AsIntermediate>(value: T) -> Self

Express a size in exabytes, as a shortcut for using Size::from_exabytes().

pub fn from_kibibytes<T: AsIntermediate>(value: T) -> Self

Express a size in kibibytes. Actual size is 2^10 * the value.

pub fn from_mebibytes<T: AsIntermediate>(value: T) -> Self

Express a size in mebibytes. Actual size is 2^20 * the value.

pub fn from_gibibytes<T: AsIntermediate>(value: T) -> Self

Express a size in gibibytes. Actual size is 2^30 * the value.

pub fn from_tebibytes<T: AsIntermediate>(value: T) -> Self

Express a size in tebibytes. Actual size is 2^40 * the value.

pub fn from_pebibytes<T: AsIntermediate>(value: T) -> Self

Express a size in pebibytes. Actual size is 2^50 * the value.

pub fn from_exbibytes<T: AsIntermediate>(value: T) -> Self

Express a size in exbibytes. Actual size is 2^60 * the value.

pub fn from_kib<T: AsIntermediate>(value: T) -> Self

Express a size in kibibytes, as a shortcut for using Size::from_kibibytes().

pub fn from_mib<T: AsIntermediate>(value: T) -> Self

Express a size in mebibytes, as a shortcut for using Size::from_mebibytes().

pub fn from_gib<T: AsIntermediate>(value: T) -> Self

Express a size in gibibytes, as a shortcut for using Size::from_gibibytes().

pub fn from_tib<T: AsIntermediate>(value: T) -> Self

Express a size in tebibytes, as a shortcut for using Size::from_tebibytes().

pub fn from_pib<T: AsIntermediate>(value: T) -> Self

Express a size in pebibytes, as a shortcut for using Size::from_pebibytes().

pub fn from_eib<T: AsIntermediate>(value: T) -> Self

Express a size in exbibytes, as a shortcut for using Size::from_exbibytes().

impl Size

pub const fn bytes(&self) -> i64

Returns the effective size in bytes of the type, useful for obtaining a plain/scalar representation of the full size represented by a Size object. This always returns an i64 regardless of the underlying type originally used, to avoid (or at least mitigate) issues with integer overflow (e.g. when trying to retrieve Size::from_tb(16_i32).bytes()).

Example:

use size::Size;
assert_eq!(Size::from_mib(4_u8).bytes(), 4_194_304 as i64);

pub fn to_string(&self, base: Base, style: Style) -> String

Returns a textual representation of the Size for display purposes, giving control over the returned representation’s base (see Base::Base2 and Base::Base10) and the style used to express the determined unit (see Style).

Trait Implementations

impl Add<&'_ Size> for &Size

type Output = Size

The resulting type after applying the + operator.

fn add(self, other: &Size) -> Self::Output

Performs the + operation.

impl Add<&'_ Size> for Size

type Output = Size

The resulting type after applying the + operator.

fn add(self, other: &Size) -> Self::Output

Performs the + operation.

impl Add<Size> for &Size

type Output = Size

The resulting type after applying the + operator.

fn add(self, other: Size) -> Self::Output

Performs the + operation.

impl Add<Size> for Size

type Output = Size

The resulting type after applying the + operator.

fn add(self, other: Size) -> Self::Output

Performs the + operation.

impl Clone for Size

fn clone(&self) -> Size

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Size

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

Formats the value using the given formatter.

impl Display for Size

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

Formats the value using the given formatter.

impl<T> Div<T> for &Size where
    T: AsIntermediate, 

type Output = Size

The resulting type after applying the / operator.

fn div(self, other: T) -> Self::Output

Performs the / operation.

impl<T> Div<T> for Size where
    T: AsIntermediate, 

type Output = Size

The resulting type after applying the / operator.

fn div(self, other: T) -> Self::Output

Performs the / operation.

impl Mul<&'_ Size> for i64

Defined to allow multiplying an untyped integral literal by a Size, because multiplication should be commutative.

type Output = Size

The resulting type after applying the * operator.

fn mul(self, other: &Size) -> Self::Output

Performs the * operation.

impl Mul<&'_ Size> for f64

Defined to allow multiplying an untyped floating scalar by a Size, because multiplication should be commutative.

type Output = Size

The resulting type after applying the * operator.

fn mul(self, other: &Size) -> Self::Output

Performs the * operation.

impl Mul<Size> for i64

Defined to allow multiplying an untyped integral literal by a Size, because multiplication should be commutative.

type Output = Size

The resulting type after applying the * operator.

fn mul(self, other: Size) -> Self::Output

Performs the * operation.

impl Mul<Size> for f64

Defined to allow multiplying an untyped floating scalar by a Size, because multiplication should be commutative.

type Output = Size

The resulting type after applying the * operator.

fn mul(self, other: Size) -> Self::Output

Performs the * operation.

impl<T> Mul<T> for Size where
    T: AsIntermediate, 

type Output = Size

The resulting type after applying the * operator.

fn mul(self, other: T) -> Self::Output

Performs the * operation.

impl<T> Mul<T> for &Size where
    T: AsIntermediate, 

type Output = Size

The resulting type after applying the * operator.

fn mul(self, other: T) -> Self::Output

Performs the * operation.

impl PartialEq<&'_ Size> for Size

fn eq(&self, other: &&Size) -> 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 PartialEq<Size> for Size

fn eq(&self, other: &Size) -> 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 PartialOrd<&'_ Size> for Size

fn partial_cmp(&self, other: &&Size) -> 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 PartialOrd<Size> for Size

fn partial_cmp(&self, other: &Size) -> 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 Sub<&'_ Size> for &Size

type Output = Size

The resulting type after applying the - operator.

fn sub(self, other: &Size) -> Self::Output

Performs the - operation.

impl Sub<&'_ Size> for Size

type Output = Size

The resulting type after applying the - operator.

fn sub(self, other: &Size) -> Self::Output

Performs the - operation.

impl Sub<Size> for &Size

type Output = Size

The resulting type after applying the - operator.

fn sub(self, other: Size) -> Self::Output

Performs the - operation.

impl Sub<Size> for Size

type Output = Size

The resulting type after applying the - operator.

fn sub(self, other: Size) -> Self::Output

Performs the - operation.

impl Copy for Size