`pub struct ByteUnit(_);`

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

source§### impl ByteUnit

### impl ByteUnit

source#### pub const PB: ByteUnit = ByteUnit::Petabyte(1)

#### pub const PB: ByteUnit = ByteUnit::Petabyte(1)

Number of bytes in 1
PB
(`1_000_000_000_000_000`

).

source#### pub const EB: ByteUnit = ByteUnit::Exabyte(1)

#### pub const EB: ByteUnit = ByteUnit::Exabyte(1)

Number of bytes in 1
EB
(`1_000_000_000_000_000_000`

).

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

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

Constructs a `ByteUnit`

representing `n`

kB
.

##### Example

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

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

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

Constructs a `ByteUnit`

representing `n`

KiB
.

##### Example

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

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

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

Constructs a `ByteUnit`

representing `n`

MB
.

##### Example

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

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

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

Constructs a `ByteUnit`

representing `n`

MiB
.

##### Example

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

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

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

Constructs a `ByteUnit`

representing `n`

GB
.

##### Example

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

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

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

Constructs a `ByteUnit`

representing `n`

GiB
.

##### Example

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

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

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

Constructs a `ByteUnit`

representing `n`

TB
.

##### Example

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

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

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

Constructs a `ByteUnit`

representing `n`

TiB
.

##### Example

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

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

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

Constructs a `ByteUnit`

representing `n`

PB
.

##### Example

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

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

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

Constructs a `ByteUnit`

representing `n`

PiB
.

##### Example

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

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

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

Constructs a `ByteUnit`

representing `n`

EB
.

##### Example

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

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

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

Constructs a `ByteUnit`

representing `n`

EiB
.

##### Example

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

source#### pub const fn max_value() -> ByteUnit

#### pub const fn max_value() -> ByteUnit

The maximum value of bytes representable by `ByteUnit`

.

##### Example

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

source#### pub const fn as_u64(self) -> u64

#### 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);
```

source#### pub const fn as_u128(self) -> u128

#### 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);
```

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

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

source§### impl<T> AddAssign<T> for ByteUnitwhere
T: Into<ByteUnit>,

### impl<T> AddAssign<T> for ByteUnitwhere T: Into<ByteUnit>,

source§#### fn add_assign(&mut self, rhs: T)

#### fn add_assign(&mut self, rhs: T)

`+=`

operation. Read moresource§### impl<'de> Deserialize<'de> for ByteUnit

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

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

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

source§### impl Display for ByteUnit

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

source§### impl<T> DivAssign<T> for ByteUnitwhere
T: Into<ByteUnit>,

### impl<T> DivAssign<T> for ByteUnitwhere T: Into<ByteUnit>,

source§#### fn div_assign(&mut self, rhs: T)

#### fn div_assign(&mut self, rhs: T)

`/=`

operation. Read moresource§### impl<T> MulAssign<T> for ByteUnitwhere
T: Into<ByteUnit>,

### impl<T> MulAssign<T> for ByteUnitwhere T: Into<ByteUnit>,

source§#### fn mul_assign(&mut self, rhs: T)

#### fn mul_assign(&mut self, rhs: T)

`*=`

operation. Read moresource§### impl Ord for ByteUnit

### impl Ord for ByteUnit

source§### impl PartialEq<ByteUnit> for i128

### impl PartialEq<ByteUnit> for i128

source§### impl PartialEq<ByteUnit> for i16

### impl PartialEq<ByteUnit> for i16

source§### impl PartialEq<ByteUnit> for i32

### impl PartialEq<ByteUnit> for i32

source§### impl PartialEq<ByteUnit> for i64

### impl PartialEq<ByteUnit> for i64

source§### impl PartialEq<ByteUnit> for i8

### impl PartialEq<ByteUnit> for i8

source§### impl PartialEq<ByteUnit> for isize

### impl PartialEq<ByteUnit> for isize

source§### impl PartialEq<ByteUnit> for u128

### impl PartialEq<ByteUnit> for u128

source§### impl PartialEq<ByteUnit> for u16

### impl PartialEq<ByteUnit> for u16

source§### impl PartialEq<ByteUnit> for u32

### impl PartialEq<ByteUnit> for u32

source§### impl PartialEq<ByteUnit> for u64

### impl PartialEq<ByteUnit> for u64

source§### impl PartialEq<ByteUnit> for u8

### impl PartialEq<ByteUnit> for u8

source§### impl PartialEq<ByteUnit> for usize

### impl PartialEq<ByteUnit> for usize

source§### impl PartialOrd<ByteUnit> for i128

### impl PartialOrd<ByteUnit> for i128

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl PartialOrd<ByteUnit> for i16

### impl PartialOrd<ByteUnit> for i16

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl PartialOrd<ByteUnit> for i32

### impl PartialOrd<ByteUnit> for i32

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl PartialOrd<ByteUnit> for i64

### impl PartialOrd<ByteUnit> for i64

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl PartialOrd<ByteUnit> for i8

### impl PartialOrd<ByteUnit> for i8

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl PartialOrd<ByteUnit> for isize

### impl PartialOrd<ByteUnit> for isize

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl PartialOrd<ByteUnit> for u128

### impl PartialOrd<ByteUnit> for u128

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl PartialOrd<ByteUnit> for u16

### impl PartialOrd<ByteUnit> for u16

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl PartialOrd<ByteUnit> for u32

### impl PartialOrd<ByteUnit> for u32

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl PartialOrd<ByteUnit> for u64

### impl PartialOrd<ByteUnit> for u64

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl PartialOrd<ByteUnit> for u8

### impl PartialOrd<ByteUnit> for u8

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl PartialOrd<ByteUnit> for usize

### impl PartialOrd<ByteUnit> for usize

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl<T> PartialOrd<T> for ByteUnitwhere
T: Into<ByteUnit> + Copy,

### impl<T> PartialOrd<T> for ByteUnitwhere T: Into<ByteUnit> + Copy,

1.0.0 · source§#### fn le(&self, other: &Rhs) -> bool

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

`self`

and `other`

) and is used by the `<=`

operator. Read moresource§### impl<T> RemAssign<T> for ByteUnitwhere
T: Into<ByteUnit>,

### impl<T> RemAssign<T> for ByteUnitwhere T: Into<ByteUnit>,

source§#### fn rem_assign(&mut self, rhs: T)

#### fn rem_assign(&mut self, rhs: T)

`%=`

operation. Read moresource§### impl Serialize for ByteUnit

### impl Serialize for ByteUnit

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

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

source§### impl<T> ShlAssign<T> for ByteUnitwhere
T: Into<ByteUnit>,

### impl<T> ShlAssign<T> for ByteUnitwhere T: Into<ByteUnit>,

source§#### fn shl_assign(&mut self, rhs: T)

#### fn shl_assign(&mut self, rhs: T)

`<<=`

operation. Read moresource§### impl<T> ShrAssign<T> for ByteUnitwhere
T: Into<ByteUnit>,

### impl<T> ShrAssign<T> for ByteUnitwhere T: Into<ByteUnit>,

source§#### fn shr_assign(&mut self, rhs: T)

#### fn shr_assign(&mut self, rhs: T)

`>>=`

operation. Read moresource§### impl<T> SubAssign<T> for ByteUnitwhere
T: Into<ByteUnit>,

### impl<T> SubAssign<T> for ByteUnitwhere T: Into<ByteUnit>,

source§#### fn sub_assign(&mut self, rhs: T)

#### fn sub_assign(&mut self, rhs: T)

`-=`

operation. Read more### impl Copy for ByteUnit

### impl Eq for ByteUnit

### impl StructuralEq for ByteUnit

## Auto Trait Implementations§

### impl RefUnwindSafe for ByteUnit

### impl Send for ByteUnit

### impl Sync for ByteUnit

### impl Unpin for ByteUnit

### impl UnwindSafe for ByteUnit

## Blanket Implementations§

§### impl<'a, T> AsTaggedExplicit<'a> for Twhere
T: 'a,

### impl<'a, T> AsTaggedExplicit<'a> for Twhere T: 'a,

§### impl<'a, T> AsTaggedImplicit<'a> for Twhere
T: 'a,

### impl<'a, T> AsTaggedImplicit<'a> for Twhere T: 'a,

source§### impl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,

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

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

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

`key`

and return `true`

if they are equal.source§### impl<T> Instrument for T

### impl<T> Instrument for T

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

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

source§#### fn in_current_span(self) -> Instrumented<Self>

#### fn in_current_span(self) -> Instrumented<Self>

§### impl<T> IntoCollection<T> for T

### impl<T> IntoCollection<T> for T

§#### fn into_collection<A>(self) -> SmallVec<A>where
A: Array<Item = T>,

#### fn into_collection<A>(self) -> SmallVec<A>where A: Array<Item = T>,

`self`

into a collection.