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§
source§impl ByteUnit
impl ByteUnit
sourcepub 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);
sourcepub 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);
sourcepub 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);
sourcepub 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);
sourcepub 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);
sourcepub 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);
sourcepub 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);
sourcepub 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);
sourcepub 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);
sourcepub 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);
sourcepub 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);
sourcepub 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);
sourcepub 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());
sourcepub 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);
sourcepub 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);
sourcepub 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
- the1
-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 ByteUnit
impl<T> AddAssign<T> for 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 ByteUnit
impl<T> DivAssign<T> for ByteUnit
source§fn div_assign(&mut self, rhs: T)
fn div_assign(&mut self, rhs: T)
/=
operation. Read moresource§impl<T> MulAssign<T> for ByteUnit
impl<T> MulAssign<T> for 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 PartialOrd<ByteUnit> for i128
impl PartialOrd<ByteUnit> for i128
source§impl PartialOrd<ByteUnit> for i16
impl PartialOrd<ByteUnit> for i16
source§impl PartialOrd<ByteUnit> for i32
impl PartialOrd<ByteUnit> for i32
source§impl PartialOrd<ByteUnit> for i64
impl PartialOrd<ByteUnit> for i64
source§impl PartialOrd<ByteUnit> for i8
impl PartialOrd<ByteUnit> for i8
source§impl PartialOrd<ByteUnit> for isize
impl PartialOrd<ByteUnit> for isize
source§impl PartialOrd<ByteUnit> for u128
impl PartialOrd<ByteUnit> for u128
source§impl PartialOrd<ByteUnit> for u16
impl PartialOrd<ByteUnit> for u16
source§impl PartialOrd<ByteUnit> for u32
impl PartialOrd<ByteUnit> for u32
source§impl PartialOrd<ByteUnit> for u64
impl PartialOrd<ByteUnit> for u64
source§impl PartialOrd<ByteUnit> for u8
impl PartialOrd<ByteUnit> for u8
source§impl PartialOrd<ByteUnit> for usize
impl PartialOrd<ByteUnit> for usize
source§impl<T> PartialOrd<T> for ByteUnit
impl<T> PartialOrd<T> for ByteUnit
source§impl<T> RemAssign<T> for ByteUnit
impl<T> RemAssign<T> for 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 ByteUnit
impl<T> ShlAssign<T> for ByteUnit
source§fn shl_assign(&mut self, rhs: T)
fn shl_assign(&mut self, rhs: T)
<<=
operation. Read moresource§impl<T> ShrAssign<T> for ByteUnit
impl<T> ShrAssign<T> for ByteUnit
source§fn shr_assign(&mut self, rhs: T)
fn shr_assign(&mut self, rhs: T)
>>=
operation. Read moresource§impl<T> SubAssign<T> for ByteUnit
impl<T> SubAssign<T> for ByteUnit
source§fn sub_assign(&mut self, rhs: T)
fn sub_assign(&mut self, rhs: T)
-=
operation. Read moreimpl Copy for ByteUnit
impl Eq for ByteUnit
Auto Trait Implementations§
impl Freeze for ByteUnit
impl RefUnwindSafe for ByteUnit
impl Send for ByteUnit
impl Sync for ByteUnit
impl Unpin for ByteUnit
impl UnwindSafe for ByteUnit
Blanket Implementations§
source§impl<T> AsAny for Twhere
T: Any,
impl<T> AsAny for Twhere
T: Any,
fn as_any_ref(&self) -> &(dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
source§impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
source§impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<Q, K> Comparable<K> for Q
impl<Q, K> Comparable<K> for Q
source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
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> ⓘ
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moresource§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere
T: ?Sized,
source§fn fg(&self, value: Color) -> Painted<&T>
fn fg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the foreground set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like red()
and
green()
, which have the same functionality but are
pithier.
§Example
Set foreground color to white using fg()
:
use yansi::{Paint, Color};
painted.fg(Color::White);
Set foreground color to white using white()
.
use yansi::Paint;
painted.white();
source§fn bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightBlack
.
§Example
println!("{}", value.bright_black());
source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightGreen
.
§Example
println!("{}", value.bright_green());
source§fn bright_yellow(&self) -> Painted<&T>
fn bright_yellow(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightYellow
.
§Example
println!("{}", value.bright_yellow());
source§fn bright_blue(&self) -> Painted<&T>
fn bright_blue(&self) -> Painted<&T>
source§fn bright_magenta(&self) -> Painted<&T>
fn bright_magenta(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightMagenta
.
§Example
println!("{}", value.bright_magenta());
source§fn bright_cyan(&self) -> Painted<&T>
fn bright_cyan(&self) -> Painted<&T>
source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightWhite
.
§Example
println!("{}", value.bright_white());
source§fn bg(&self, value: Color) -> Painted<&T>
fn bg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the background set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like on_red()
and
on_green()
, which have the same functionality but
are pithier.
§Example
Set background color to red using fg()
:
use yansi::{Paint, Color};
painted.bg(Color::Red);
Set background color to red using on_red()
.
use yansi::Paint;
painted.on_red();
source§fn on_primary(&self) -> Painted<&T>
fn on_primary(&self) -> Painted<&T>
source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
source§fn on_bright_black(&self) -> Painted<&T>
fn on_bright_black(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightBlack
.
§Example
println!("{}", value.on_bright_black());
source§fn on_bright_red(&self) -> Painted<&T>
fn on_bright_red(&self) -> Painted<&T>
source§fn on_bright_green(&self) -> Painted<&T>
fn on_bright_green(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightGreen
.
§Example
println!("{}", value.on_bright_green());
source§fn on_bright_yellow(&self) -> Painted<&T>
fn on_bright_yellow(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightYellow
.
§Example
println!("{}", value.on_bright_yellow());
source§fn on_bright_blue(&self) -> Painted<&T>
fn on_bright_blue(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightBlue
.
§Example
println!("{}", value.on_bright_blue());
source§fn on_bright_magenta(&self) -> Painted<&T>
fn on_bright_magenta(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightMagenta
.
§Example
println!("{}", value.on_bright_magenta());
source§fn on_bright_cyan(&self) -> Painted<&T>
fn on_bright_cyan(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightCyan
.
§Example
println!("{}", value.on_bright_cyan());
source§fn on_bright_white(&self) -> Painted<&T>
fn on_bright_white(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightWhite
.
§Example
println!("{}", value.on_bright_white());
source§fn attr(&self, value: Attribute) -> Painted<&T>
fn attr(&self, value: Attribute) -> Painted<&T>
Enables the styling Attribute
value
.
This method should be used rarely. Instead, prefer to use
attribute-specific builder methods like bold()
and
underline()
, which have the same functionality
but are pithier.
§Example
Make text bold using attr()
:
use yansi::{Paint, Attribute};
painted.attr(Attribute::Bold);
Make text bold using using bold()
.
use yansi::Paint;
painted.bold();
source§fn underline(&self) -> Painted<&T>
fn underline(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::Underline
.
§Example
println!("{}", value.underline());
source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::RapidBlink
.
§Example
println!("{}", value.rapid_blink());
source§fn quirk(&self, value: Quirk) -> Painted<&T>
fn quirk(&self, value: Quirk) -> Painted<&T>
Enables the yansi
Quirk
value
.
This method should be used rarely. Instead, prefer to use quirk-specific
builder methods like mask()
and
wrap()
, which have the same functionality but are
pithier.
§Example
Enable wrapping using .quirk()
:
use yansi::{Paint, Quirk};
painted.quirk(Quirk::Wrap);
Enable wrapping using wrap()
.
use yansi::Paint;
painted.wrap();
source§fn clear(&self) -> Painted<&T>
👎Deprecated since 1.0.1: renamed to resetting()
due to conflicts with Vec::clear()
.
The clear()
method will be removed in a future release.
fn clear(&self) -> Painted<&T>
resetting()
due to conflicts with Vec::clear()
.
The clear()
method will be removed in a future release.source§fn whenever(&self, value: Condition) -> Painted<&T>
fn whenever(&self, value: Condition) -> Painted<&T>
Conditionally enable styling based on whether the Condition
value
applies. Replaces any previous condition.
See the crate level docs for more details.
§Example
Enable styling painted
only when both stdout
and stderr
are TTYs:
use yansi::{Paint, Condition};
painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);