Struct rocket::data::ByteUnit

#[repr(transparent)]
pub struct ByteUnit(_);

A unit of bytes with saturating const constructors and arithmetic.

Overview

A ByteUnit represents a unit, a count, a number, of bytes. All operations on a ByteUnit – constructors, arithmetic, conversions – saturate. Overflow, underflow, and divide-by-zero are impossible. See the top-level documentation for more.

ToByteUnit provides human-friendly methods on all integer types for converting into a ByteUnit: 512.megabytes().

Parsing

ByteUnit implements FromStr for parsing byte unit strings into a ByteUnit. The grammar accepted by the parser is:

byte_unit := uint+ ('.' uint+)? WHITESPACE* suffix

uint := '0'..'9'
suffix := case insensitive SI byte unit suffix ('b' to 'eib')
WHITESPACE := the ' ' character

use ubyte::{ByteUnit, ToByteUnit};

let one_gib: ByteUnit = "1GiB".parse().unwrap();
assert_eq!(one_gib, 1.gibibytes());

let quarter_mb: ByteUnit = "256 kB".parse().unwrap();
assert_eq!(quarter_mb, 256.kilobytes());

let half_mb: ByteUnit = "0.5MB".parse().unwrap();
assert_eq!(half_mb, 500.kilobytes());

let half_mib: ByteUnit = "0.500 mib".parse().unwrap();
assert_eq!(half_mib, 512.kibibytes());

let some_mb: ByteUnit = "20.5MB".parse().unwrap();
assert_eq!(some_mb, 20.megabytes() + 500.kilobytes());

(De)serialization

With the serde feaure enabled (disabled by default), ByteUnit implements Deserialize from strings, using the same grammar as the FromStr implementation, defined above, as well as all integer types. The Serialize implementation serializes into a u64.

Example

use ubyte::{ByteUnit, ToByteUnit};

// Construct with unit-valued associated constants, `const` constructors, or
// human-friendly methods from the `ToByteUnit` integer extension trait.
const HALF_GB: ByteUnit = ByteUnit::Megabyte(500);
const HALF_GIB: ByteUnit = ByteUnit::Mebibyte(512);
let half_gb = 500 * ByteUnit::MB;
let half_gib = 512 * ByteUnit::MiB;
let half_gb = 500.megabytes();
let half_gib = 512.mebibytes();

// All arithmetic operations and conversions saturate.
let exbibyte = ByteUnit::Exbibyte(1);
let exbibyte_too_large_a = 1024 * ByteUnit::EiB;
let exbibyte_too_large_b = ByteUnit::Exbibyte(1024);
let exbibyte_too_large_c = 1024.exbibytes();
let div_by_zero = 1024.exbibytes() / 0;
let too_small = 1000.megabytes() - 1.gibibytes();
assert_eq!(exbibyte << 4, ByteUnit::max_value());
assert_eq!(exbibyte << 10, ByteUnit::max_value());
assert_eq!(exbibyte_too_large_a, ByteUnit::max_value());
assert_eq!(exbibyte_too_large_b, ByteUnit::max_value());
assert_eq!(exbibyte_too_large_c, ByteUnit::max_value());
assert_eq!(div_by_zero, ByteUnit::max_value());
assert_eq!(too_small, 0);

Implementations

impl ByteUnit

pub const B: ByteUnit

Number of bytes in 1 B (1).

pub const kB: ByteUnit

Number of bytes in 1 kB (1_000).

pub const KiB: ByteUnit

Number of bytes in 1 KiB (1 << 10).

pub const MB: ByteUnit

Number of bytes in 1 MB (1_000_000).

pub const MiB: ByteUnit

Number of bytes in 1 MiB (1 << 20).

pub const GB: ByteUnit

Number of bytes in 1 GB (1_000_000_000).

pub const GiB: ByteUnit

Number of bytes in 1 GiB (1 << 30).

pub const TB: ByteUnit

Number of bytes in 1 TB (1_000_000_000_000).

pub const TiB: ByteUnit

Number of bytes in 1 TiB (1 << 40).

pub const PB: ByteUnit

Number of bytes in 1 PB (1_000_000_000_000_000).

pub const PiB: ByteUnit

Number of bytes in 1 PiB (1 << 50).

pub const EB: ByteUnit

Number of bytes in 1 EB (1_000_000_000_000_000_000).

pub const EiB: ByteUnit

Number of bytes in 1 EiB (1 << 60).

pub const fn Byte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n B .

Example

assert_eq!(ByteUnit::Byte(10), 10 * ByteUnit::B);

pub const fn Kilobyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n kB .

Example

assert_eq!(ByteUnit::Kilobyte(10), 10 * ByteUnit::kB);

pub const fn Kibibyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n KiB .

Example

assert_eq!(ByteUnit::Kibibyte(10), 10 * ByteUnit::KiB);

pub const fn Megabyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n MB .

Example

assert_eq!(ByteUnit::Megabyte(10), 10 * ByteUnit::MB);

pub const fn Mebibyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n MiB .

Example

assert_eq!(ByteUnit::Mebibyte(10), 10 * ByteUnit::MiB);

pub const fn Gigabyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n GB .

Example

assert_eq!(ByteUnit::Gigabyte(10), 10 * ByteUnit::GB);

pub const fn Gibibyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n GiB .

Example

assert_eq!(ByteUnit::Gibibyte(10), 10 * ByteUnit::GiB);

pub const fn Terabyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n TB .

Example

assert_eq!(ByteUnit::Terabyte(10), 10 * ByteUnit::TB);

pub const fn Tebibyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n TiB .

Example

assert_eq!(ByteUnit::Tebibyte(10), 10 * ByteUnit::TiB);

pub const fn Petabyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n PB .

Example

assert_eq!(ByteUnit::Petabyte(10), 10 * ByteUnit::PB);

pub const fn Pebibyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n PiB .

Example

assert_eq!(ByteUnit::Pebibyte(10), 10 * ByteUnit::PiB);

pub const fn Exabyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n EB .

Example

assert_eq!(ByteUnit::Exabyte(10), 10 * ByteUnit::EB);

pub const fn Exbibyte(n: u64) -> ByteUnit

Constructs a ByteUnit representing n EiB .

Example

assert_eq!(ByteUnit::Exbibyte(10), 10 * ByteUnit::EiB);

pub const fn max_value() -> ByteUnit

The maximum value of bytes representable by ByteUnit.

Example

assert_eq!(ByteUnit::max_value(), u64::max_value());

pub const fn as_u64(self) -> u64

Returns the value of bytes represented by self as a u64.

Example

let int: u64 = ByteUnit::Gigabyte(4).as_u64();
assert_eq!(int, 4 * ByteUnit::GB);

assert_eq!(ByteUnit::Megabyte(42).as_u64(), 42 * 1_000_000);
assert_eq!(ByteUnit::Exbibyte(7).as_u64(), 7 * 1 << 60);

pub const fn as_u128(self) -> u128

Returns the value of bytes represented by self as a u128.

Example

let int: u128 = ByteUnit::Gigabyte(4).as_u128();
assert_eq!(int, 4 * ByteUnit::GB);

assert_eq!(ByteUnit::Megabyte(42).as_u64(), 42 * 1_000_000);
assert_eq!(ByteUnit::Exbibyte(7).as_u64(), 7 * 1 << 60);

pub fn repr(self) -> (u64, f64, &'static str, ByteUnit)

Returns the components of the minimal unit representation of self.

The “minimal unit representation” is the representation that maximizes the SI-unit while minimizing the whole part of the value. For example, 1024.bytes() is minimally represented by 1KiB, while 1023.bytes() is minimally represented by 1.023kB.

The four components returned, in tuple-order, are:

• whole - the whole part of the minimal representation.
• frac - the fractional part of the minimal representation.
• suffix - the suffix of the minimal representation.
• unit - the 1-unit of the minimal representation.

Succinctly, this is: (whole, frac, suffix, unit). Observe that (whole + frac) * unit reconstructs the original value.

Example

use ubyte::{ByteUnit, ToByteUnit};

let value = 2.mebibytes() + 512.kibibytes();
assert_eq!(value.to_string(), "2.50MiB");

let (whole, frac, suffix, unit) = value.repr();
assert_eq!(whole, 2);
assert_eq!(frac, 0.5);
assert_eq!(suffix, "MiB");
assert_eq!(unit, ByteUnit::MiB);

let reconstructed = (whole as f64 + frac) * unit.as_u64() as f64;
assert_eq!(reconstructed as u64, value);

Trait Implementations

impl Add<ByteUnit> for u64

type Output = ByteUnit

The resulting type after applying the + operator.

pub fn add(self, rhs: ByteUnit) -> <u64 as Add<ByteUnit>>::Output

Performs the + operation.

impl<T> Add<T> for ByteUnit where
    T: Into<ByteUnit>, 

type Output = ByteUnit

The resulting type after applying the + operator.

pub fn add(self, rhs: T) -> <ByteUnit as Add<T>>::Output

Performs the + operation.

impl Clone for ByteUnit

pub fn clone(&self) -> ByteUnit

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ByteUnit

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ByteUnit

pub fn deserialize<D>(
    deserializer: D
) -> Result<ByteUnit, <D as Deserializer<'de>>::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl Display for ByteUnit

Display self as best as possible. For perfectly custom display output, consider using ByteUnit::repr().

Example

use ubyte::{ByteUnit, ToByteUnit};

assert_eq!(323.kilobytes().to_string(), "323kB");
assert_eq!(3.megabytes().to_string(), "3MB");
assert_eq!(3.mebibytes().to_string(), "3MiB");

assert_eq!((3.mebibytes() + 140.kilobytes()).to_string(), "3.13MiB");
assert_eq!((3.mebibytes() + 2.mebibytes()).to_string(), "5MiB");
assert_eq!((7.gigabytes() + 58.mebibytes() + 3.kilobytes()).to_string(), "7.06GB");
assert_eq!((7.gibibytes() + 920.mebibytes()).to_string(), "7.90GiB");
assert_eq!(7231.kilobytes().to_string(), "6.90MiB");

assert_eq!(format!("{:.0}", 7.gibibytes() + 920.mebibytes()), "8GiB");
assert_eq!(format!("{:.1}", 7.gibibytes() + 920.mebibytes()), "7.9GiB");
assert_eq!(format!("{:.2}", 7.gibibytes() + 920.mebibytes()), "7.90GiB");
assert_eq!(format!("{:.3}", 7.gibibytes() + 920.mebibytes()), "7.898GiB");
assert_eq!(format!("{:.4}", 7.gibibytes() + 920.mebibytes()), "7.8984GiB");
assert_eq!(format!("{:.4}", 7231.kilobytes()), "6.8960MiB");
assert_eq!(format!("{:.0}", 7231.kilobytes()), "7MiB");
assert_eq!(format!("{:.2}", 999.kilobytes() + 990.bytes()), "976.55KiB");
assert_eq!(format!("{:.0}", 999.kilobytes() + 990.bytes()), "1MB");

assert_eq!(format!("{:04.2}", 999.kilobytes() + 990.bytes()), "0976.55KiB");
assert_eq!(format!("{:02.0}", 999.kilobytes() + 990.bytes()), "01MB");
assert_eq!(format!("{:04.0}", 999.kilobytes() + 990.bytes()), "0001MB");

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

Formats the value using the given formatter.

impl Div<ByteUnit> for u64

type Output = ByteUnit

The resulting type after applying the / operator.

pub fn div(self, rhs: ByteUnit) -> <u64 as Div<ByteUnit>>::Output

Performs the / operation.

impl<T> Div<T> for ByteUnit where
    T: Into<ByteUnit>, 

type Output = ByteUnit

The resulting type after applying the / operator.

pub fn div(self, rhs: T) -> <ByteUnit as Div<T>>::Output

Performs the / operation.

impl From<ByteUnit> for u64

pub fn from(v: ByteUnit) -> u64

Performs the conversion.

impl From<i128> for ByteUnit

pub fn from(value: i128) -> ByteUnit

Performs the conversion.

impl From<i16> for ByteUnit

pub fn from(v: i16) -> ByteUnit

Performs the conversion.

impl From<i32> for ByteUnit

pub fn from(v: i32) -> ByteUnit

Performs the conversion.

impl From<i64> for ByteUnit

pub fn from(v: i64) -> ByteUnit

Performs the conversion.

impl From<i8> for ByteUnit

pub fn from(v: i8) -> ByteUnit

Performs the conversion.

impl From<isize> for ByteUnit

pub fn from(value: isize) -> ByteUnit

Performs the conversion.

impl From<u128> for ByteUnit

pub fn from(value: u128) -> ByteUnit

Performs the conversion.

impl From<u16> for ByteUnit

pub fn from(v: u16) -> ByteUnit

Performs the conversion.

impl From<u32> for ByteUnit

pub fn from(v: u32) -> ByteUnit

Performs the conversion.

impl From<u64> for ByteUnit

pub fn from(v: u64) -> ByteUnit

Performs the conversion.

impl From<u8> for ByteUnit

pub fn from(v: u8) -> ByteUnit

Performs the conversion.

impl From<usize> for ByteUnit

pub fn from(value: usize) -> ByteUnit

Performs the conversion.

impl FromStr for ByteUnit

type Err = Error

The associated error which can be returned from parsing.

pub fn from_str(s: &str) -> Result<ByteUnit, <ByteUnit as FromStr>::Err>

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

impl Hash for ByteUnit

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl Len<ByteUnit> for TempFile<'_>

fn len(&self) -> ByteUnit

The length of the value.

fn len_into_u64(len: ByteUnit) -> u64

Convert len into u64.

fn zero_len() -> ByteUnit

The zero value for L.

impl Mul<ByteUnit> for u64

type Output = ByteUnit

The resulting type after applying the * operator.

pub fn mul(self, rhs: ByteUnit) -> <u64 as Mul<ByteUnit>>::Output

Performs the * operation.

impl<T> Mul<T> for ByteUnit where
    T: Into<ByteUnit>, 

type Output = ByteUnit

The resulting type after applying the * operator.

pub fn mul(self, rhs: T) -> <ByteUnit as Mul<T>>::Output

Performs the * operation.

impl Ord for ByteUnit

pub fn cmp(&self, other: &ByteUnit) -> Ordering

This method returns an Ordering between self and other.

#[must_use]

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl PartialEq<ByteUnit> for u64

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

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

#[must_use]

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

This method tests for !=.

impl<T> PartialEq<T> for ByteUnit where
    T: Into<ByteUnit> + Copy, 

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

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

#[must_use]

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

This method tests for !=.

impl PartialOrd<ByteUnit> for u64

pub fn partial_cmp(&self, other: &ByteUnit) -> Option<Ordering>

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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<T> PartialOrd<T> for ByteUnit where
    T: Into<ByteUnit> + Copy, 

pub fn partial_cmp(&self, other: &T) -> Option<Ordering>

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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

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

#[must_use]

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 Rem<ByteUnit> for u64

type Output = ByteUnit

The resulting type after applying the % operator.

pub fn rem(self, rhs: ByteUnit) -> <u64 as Rem<ByteUnit>>::Output

Performs the % operation.

impl<T> Rem<T> for ByteUnit where
    T: Into<ByteUnit>, 

type Output = ByteUnit

The resulting type after applying the % operator.

pub fn rem(self, rhs: T) -> <ByteUnit as Rem<T>>::Output

Performs the % operation.

impl Serialize for ByteUnit

pub fn serialize<S>(
    &self,
    serializer: S
) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl Shl<ByteUnit> for u64

type Output = ByteUnit

The resulting type after applying the << operator.

pub fn shl(self, rhs: ByteUnit) -> <u64 as Shl<ByteUnit>>::Output

Performs the << operation.

impl<T> Shl<T> for ByteUnit where
    T: Into<ByteUnit>, 

type Output = ByteUnit

The resulting type after applying the << operator.

pub fn shl(self, rhs: T) -> <ByteUnit as Shl<T>>::Output

Performs the << operation.

impl Shr<ByteUnit> for u64

type Output = ByteUnit

The resulting type after applying the >> operator.

pub fn shr(self, rhs: ByteUnit) -> <u64 as Shr<ByteUnit>>::Output

Performs the >> operation.

impl<T> Shr<T> for ByteUnit where
    T: Into<ByteUnit>, 

type Output = ByteUnit

The resulting type after applying the >> operator.

pub fn shr(self, rhs: T) -> <ByteUnit as Shr<T>>::Output

Performs the >> operation.

impl Sub<ByteUnit> for u64

type Output = ByteUnit

The resulting type after applying the - operator.

pub fn sub(self, rhs: ByteUnit) -> <u64 as Sub<ByteUnit>>::Output

Performs the - operation.

impl<T> Sub<T> for ByteUnit where
    T: Into<ByteUnit>, 

type Output = ByteUnit

The resulting type after applying the - operator.

pub fn sub(self, rhs: T) -> <ByteUnit as Sub<T>>::Output

Performs the - operation.

impl Copy for ByteUnit

impl Eq for ByteUnit

impl StructuralEq for ByteUnit