Struct pavex::unit::ByteUnit

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

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. Read more
§

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

§

fn add_assign(&mut self, rhs: T)

Performs the += operation. Read more
§

impl Clone for ByteUnit

§

fn clone(&self) -> ByteUnit

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
§

impl Debug for ByteUnit

§

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

Formats the value using the given formatter. Read more
§

impl Default for ByteUnit

§

fn default() -> ByteUnit

Returns the “default value” for a type. Read more
§

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. Read more
§

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. Read more
§

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. Read more
§

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

§

fn div_assign(&mut self, rhs: T)

Performs the /= operation. Read more
§

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. Read more
§

impl Hash for ByteUnit

§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

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

Feeds a slice of this type into the given Hasher. Read more
§

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. Read more
§

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

§

fn mul_assign(&mut self, rhs: T)

Performs the *= operation. Read more
§

impl Ord for ByteUnit

§

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

This method returns an Ordering between self and other. Read more
1.21.0 · source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized + PartialOrd,

Restrict a value to a certain interval. Read more
§

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 ==.
1.0.0 · source§

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. Read more
1.0.0 · source§

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

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

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

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

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

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. Read more
§

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

§

fn rem_assign(&mut self, rhs: T)

Performs the %= operation. Read more
§

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. Read more
§

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. Read more
§

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

§

fn shl_assign(&mut self, rhs: T)

Performs the <<= operation. Read more
§

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. Read more
§

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

§

fn shr_assign(&mut self, rhs: T)

Performs the >>= operation. Read more
§

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. Read more
§

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

§

fn sub_assign(&mut self, rhs: T)

Performs the -= operation. Read more
§

impl Copy for ByteUnit

§

impl Eq for ByteUnit

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
§

impl<Q, K> Comparable<K> for Q
where Q: Ord + ?Sized, K: Borrow<Q> + ?Sized,

§

fn compare(&self, key: &K) -> Ordering

Compare self to key and return their ordering.
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where 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> Same for T

source§

type Output = T

Should always be Self
§

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

§

fn bytes(self) -> ByteUnit

Converts self to a ByteUnit representing self bytes.
§

fn kilobytes(self) -> ByteUnit

Converts self to a ByteUnit representing self kB .
§

fn kibibytes(self) -> ByteUnit

Converts self to a ByteUnit representing self KiB .
§

fn megabytes(self) -> ByteUnit

Converts self to a ByteUnit representing self MB .
§

fn mebibytes(self) -> ByteUnit

Converts self to a ByteUnit representing self MiB .
§

fn gigabytes(self) -> ByteUnit

Converts self to a ByteUnit representing self GB .
§

fn gibibytes(self) -> ByteUnit

Converts self to a ByteUnit representing self GiB .
§

fn terabytes(self) -> ByteUnit

Converts self to a ByteUnit representing self TB .
§

fn tibibytes(self) -> ByteUnit

Converts self to a ByteUnit representing self TiB .
§

fn petabytes(self) -> ByteUnit

Converts self to a ByteUnit representing self PB .
§

fn pebibytes(self) -> ByteUnit

Converts self to a ByteUnit representing self PiB .
§

fn exabytes(self) -> ByteUnit

Converts self to a ByteUnit representing self EB .
§

fn exbibytes(self) -> ByteUnit

Converts self to a ByteUnit representing self EiB .
source§

impl<T> ToOwned for T
where T: Clone,

source§

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 T
where 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 T
where U: Into<T>,

source§

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 T
where U: TryFrom<T>,

source§

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

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,