Struct ByteUnit

pub struct ByteUnit(/* private fields */);

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<T> Add<T> for ByteUnit

where T: Into<ByteUnit>,

type Output = ByteUnit

The resulting type after applying the + operator.

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

Performs the + operation.

impl<T> AddAssign<T> for ByteUnit

where T: Into<ByteUnit>,

fn add_assign(&mut self, rhs: T)

Performs the += operation.

impl Clone for ByteUnit

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

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

Formats the value using the given formatter.

impl Default for ByteUnit

fn default() -> ByteUnit

Returns the “default value” for a type.

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

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

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

Formats the value using the given formatter.

impl<T> Div<T> for ByteUnit

where T: Into<ByteUnit>,

type Output = ByteUnit

The resulting type after applying the / operator.

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

Performs the / operation.

impl<T> DivAssign<T> for ByteUnit

where T: Into<ByteUnit>,

fn div_assign(&mut self, rhs: T)

Performs the /= operation.

impl From<i128> for ByteUnit

fn from(value: i128) -> ByteUnit

Converts to this type from the input type.

impl From<i16> for ByteUnit

fn from(v: i16) -> ByteUnit

Converts to this type from the input type.

impl From<i32> for ByteUnit

fn from(v: i32) -> ByteUnit

Converts to this type from the input type.

impl From<i64> for ByteUnit

fn from(v: i64) -> ByteUnit

Converts to this type from the input type.

impl From<i8> for ByteUnit

fn from(v: i8) -> ByteUnit

Converts to this type from the input type.

impl From<isize> for ByteUnit

fn from(value: isize) -> ByteUnit

Converts to this type from the input type.

impl From<u128> for ByteUnit

fn from(value: u128) -> ByteUnit

Converts to this type from the input type.

impl From<u16> for ByteUnit

fn from(v: u16) -> ByteUnit

Converts to this type from the input type.

impl From<u32> for ByteUnit

fn from(v: u32) -> ByteUnit

Converts to this type from the input type.

impl From<u64> for ByteUnit

fn from(v: u64) -> ByteUnit

Converts to this type from the input type.

impl From<u8> for ByteUnit

fn from(v: u8) -> ByteUnit

Converts to this type from the input type.

impl From<usize> for ByteUnit

fn from(value: usize) -> ByteUnit

Converts to this type from the input type.

impl FromStr for ByteUnit

type Err = Error

The associated error which can be returned from parsing.

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

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Mul<T> for ByteUnit

where T: Into<ByteUnit>,

type Output = ByteUnit

The resulting type after applying the * operator.

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

Performs the * operation.

impl<T> MulAssign<T> for ByteUnit

where T: Into<ByteUnit>,

fn mul_assign(&mut self, rhs: T)

Performs the *= operation.

impl Ord for ByteUnit

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

impl<T> PartialEq<T> for ByteUnit

where T: Into<ByteUnit> + Copy,

fn eq(&self, other: &T) -> 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<T> PartialOrd<T> for ByteUnit

where T: Into<ByteUnit> + Copy,

fn partial_cmp(&self, other: &T) -> 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<T> Rem<T> for ByteUnit

where T: Into<ByteUnit>,

type Output = ByteUnit

The resulting type after applying the % operator.

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

Performs the % operation.

impl<T> RemAssign<T> for ByteUnit

where T: Into<ByteUnit>,

fn rem_assign(&mut self, rhs: T)

Performs the %= operation.

impl Serialize for ByteUnit

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<T> Shl<T> for ByteUnit

where T: Into<ByteUnit>,

type Output = ByteUnit

The resulting type after applying the << operator.

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

Performs the << operation.

impl<T> ShlAssign<T> for ByteUnit

where T: Into<ByteUnit>,

fn shl_assign(&mut self, rhs: T)

Performs the <<= operation.

impl<T> Shr<T> for ByteUnit

where T: Into<ByteUnit>,

type Output = ByteUnit

The resulting type after applying the >> operator.

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

Performs the >> operation.

impl<T> ShrAssign<T> for ByteUnit

where T: Into<ByteUnit>,

fn shr_assign(&mut self, rhs: T)

Performs the >>= operation.

impl<T> Sub<T> for ByteUnit

where T: Into<ByteUnit>,

type Output = ByteUnit

The resulting type after applying the - operator.

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

Performs the - operation.

impl<T> SubAssign<T> for ByteUnit

where T: Into<ByteUnit>,

fn sub_assign(&mut self, rhs: T)

Performs the -= operation.

impl Copy for ByteUnit

impl Eq for ByteUnit