pub struct Size { /* private fields */ }
Expand description
Size
is the core type exposed by this crate and allows the developer to express a file size
(or the general concept of a “size”) as a strongly-typed, convertible type that can be used for
textual formatting (“pretty printing”) and mathematical operations.
A size can be created in terms of any supported unit and an associated numeric value of any type.
use size::Size;
// Identical sizes expressed in different units with different primitive types:
assert_eq!(Size::from_kibibytes(2_u8), Size::from_kilobytes(2.048_f64));
Implementations
sourceimpl Size
impl Size
sourcepub fn to_string(&self) -> String
pub fn to_string(&self) -> String
Returns a textual representation of the Size
for display purposes. This is a String
equivalent to what Size
’s std::fmt::Display
would return.
Example:
use size::Size;
let bytes = Size::from_bytes(1550);
let as_text = bytes.to_string();
assert_eq!(as_text.as_str(), "1.51 KiB");
sourcepub fn format(&self) -> FormattableSize<'_>
pub fn format(&self) -> FormattableSize<'_>
Returns a textual representation of the Size
for display purposes, giving control over
the returned representation’s base (see Base::Base2
and Base::Base10
) and the style
used to express the determined unit (see Style
).
Example:
use size::{Base, Size, Style};
let size = Size::from_mib(1.907349);
let text = size.format()
.with_base(Base::Base10)
.with_style(Style::Full)
.to_string();
assert_eq!(text.as_str(), "2.00 Megabytes");
It is not necessary to call .to_string()
if you are passing the formatted size to a
format!()
macro or similar (e.g. println!
and friends), as the result implements
Display
and will resolve to the same text.
sourceimpl Size
impl Size
sourcepub const fn from_const(bytes: i64) -> Self
pub const fn from_const(bytes: i64) -> Self
Initialize a Size
from the provided value, in bytes. This is a constant function and may
be used in a const
context.
Unlike the other “from” functions (e.g. from_kilobytes()
), it is
not generic because
a) trait methods (required to use a generic type) may not be declared as const
, and
b) it’s always safe to use as i64
on whatever type you’re actually passing into
from_bytes()
without any (additional) loss of precision as compared to passing in an
arbitrary numeric type, since there is no math required to calculate the equivalent size in
bytes.
To further illustrate this point, let’s look at this hypothetical initialization of a Size
from a floating-point literal: let s = Size::from_kib(2.5);
- when the conversion from
“2.5 KiB” to “bytes” happens internally, the result is equivalent to (2.5 * 1024.0) as i64
and yields the correct result of 2560 bytes. But if from_kib
weren’t generic and you
needed to use as i64
(i.e. Size::from_kib(2.5 as i64)
), the calculated size in bytes
would start from an already-truncated 2_i64
and yield an incorrect answer of 2048 bytes
((2.5 as i64) * 1024
). However, with from_bytes()
, there can be no loss of precision
(or, pedantically, even truncation) when as i64
is used since the file size, expressed in
bytes, must always be a whole number; this means it is safe to perform the integer
conversion/rounding at the call site itself and Size::from_const(float_val as i64)
would
necessarily always yield the same result as the generic/type-agnostic
Size::from_bytes::<f64>(float_val)
.
sourcepub fn from_bytes<T: AsIntermediate>(value: T) -> Self
pub fn from_bytes<T: AsIntermediate>(value: T) -> Self
Initialize a Size
from the provided value, in bytes.
sourcepub fn from_kilobytes<T: AsIntermediate>(value: T) -> Self
pub fn from_kilobytes<T: AsIntermediate>(value: T) -> Self
Express a size in kilobytes. Actual size is 10^3 * the value.
sourcepub fn from_megabytes<T: AsIntermediate>(value: T) -> Self
pub fn from_megabytes<T: AsIntermediate>(value: T) -> Self
Express a size in megabytes. Actual size is 10^6 * the value.
sourcepub fn from_gigabytes<T: AsIntermediate>(value: T) -> Self
pub fn from_gigabytes<T: AsIntermediate>(value: T) -> Self
Express a size in gigabytes. Actual size is 10^9 * the value.
sourcepub fn from_terabytes<T: AsIntermediate>(value: T) -> Self
pub fn from_terabytes<T: AsIntermediate>(value: T) -> Self
Express a size in terabytes. Actual size is 10^12 * the value.
sourcepub fn from_petabytes<T: AsIntermediate>(value: T) -> Self
pub fn from_petabytes<T: AsIntermediate>(value: T) -> Self
Express a size in petabytes. Actual size is 10^15 * the value.
sourcepub fn from_exabytes<T: AsIntermediate>(value: T) -> Self
pub fn from_exabytes<T: AsIntermediate>(value: T) -> Self
Express a size in exabytes. Actual size is 10^18 * the value.
sourcepub fn from_kb<T: AsIntermediate>(value: T) -> Self
pub fn from_kb<T: AsIntermediate>(value: T) -> Self
Express a size in kilobytes, as a shortcut for using Size::from_kilobytes()
.
sourcepub fn from_mb<T: AsIntermediate>(value: T) -> Self
pub fn from_mb<T: AsIntermediate>(value: T) -> Self
Express a size in megabytes, as a shortcut for using Size::from_megabytes()
.
sourcepub fn from_gb<T: AsIntermediate>(value: T) -> Self
pub fn from_gb<T: AsIntermediate>(value: T) -> Self
Express a size in gigabytes, as a shortcut for using Size::from_gigabytes()
.
sourcepub fn from_tb<T: AsIntermediate>(value: T) -> Self
pub fn from_tb<T: AsIntermediate>(value: T) -> Self
Express a size in terabytes, as a shortcut for using Size::from_terabytes()
.
sourcepub fn from_pb<T: AsIntermediate>(value: T) -> Self
pub fn from_pb<T: AsIntermediate>(value: T) -> Self
Express a size in petabytes, as a shortcut for using Size::from_petabytes()
.
sourcepub fn from_eb<T: AsIntermediate>(value: T) -> Self
pub fn from_eb<T: AsIntermediate>(value: T) -> Self
Express a size in exabytes, as a shortcut for using Size::from_exabytes()
.
sourcepub fn from_kibibytes<T: AsIntermediate>(value: T) -> Self
pub fn from_kibibytes<T: AsIntermediate>(value: T) -> Self
Express a size in kibibytes. Actual size is 2^10 * the value.
sourcepub fn from_mebibytes<T: AsIntermediate>(value: T) -> Self
pub fn from_mebibytes<T: AsIntermediate>(value: T) -> Self
Express a size in mebibytes. Actual size is 2^20 * the value.
sourcepub fn from_gibibytes<T: AsIntermediate>(value: T) -> Self
pub fn from_gibibytes<T: AsIntermediate>(value: T) -> Self
Express a size in gibibytes. Actual size is 2^30 * the value.
sourcepub fn from_tebibytes<T: AsIntermediate>(value: T) -> Self
pub fn from_tebibytes<T: AsIntermediate>(value: T) -> Self
Express a size in tebibytes. Actual size is 2^40 * the value.
sourcepub fn from_pebibytes<T: AsIntermediate>(value: T) -> Self
pub fn from_pebibytes<T: AsIntermediate>(value: T) -> Self
Express a size in pebibytes. Actual size is 2^50 * the value.
sourcepub fn from_exbibytes<T: AsIntermediate>(value: T) -> Self
pub fn from_exbibytes<T: AsIntermediate>(value: T) -> Self
Express a size in exbibytes. Actual size is 2^60 * the value.
sourcepub fn from_kib<T: AsIntermediate>(value: T) -> Self
pub fn from_kib<T: AsIntermediate>(value: T) -> Self
Express a size in kibibytes, as a shortcut for using Size::from_kibibytes()
.
sourcepub fn from_mib<T: AsIntermediate>(value: T) -> Self
pub fn from_mib<T: AsIntermediate>(value: T) -> Self
Express a size in mebibytes, as a shortcut for using Size::from_mebibytes()
.
sourcepub fn from_gib<T: AsIntermediate>(value: T) -> Self
pub fn from_gib<T: AsIntermediate>(value: T) -> Self
Express a size in gibibytes, as a shortcut for using Size::from_gibibytes()
.
sourcepub fn from_tib<T: AsIntermediate>(value: T) -> Self
pub fn from_tib<T: AsIntermediate>(value: T) -> Self
Express a size in tebibytes, as a shortcut for using Size::from_tebibytes()
.
sourcepub fn from_pib<T: AsIntermediate>(value: T) -> Self
pub fn from_pib<T: AsIntermediate>(value: T) -> Self
Express a size in pebibytes, as a shortcut for using Size::from_pebibytes()
.
sourcepub fn from_eib<T: AsIntermediate>(value: T) -> Self
pub fn from_eib<T: AsIntermediate>(value: T) -> Self
Express a size in exbibytes, as a shortcut for using Size::from_exbibytes()
.
sourceimpl Size
impl Size
sourcepub const fn bytes(&self) -> i64
pub const fn bytes(&self) -> i64
Returns the effective size in bytes of the type, useful for obtaining a plain/scalar
representation of the full size represented by a Size
object. This always returns an
i64
regardless of the underlying type originally used, to avoid (or at least mitigate)
issues with integer overflow (e.g. when trying to retrieve Size::from_tb(16_i32).bytes()
).
Example:
use size::Size;
assert_eq!(Size::from_mib(4_u8).bytes(), 4_194_304 as i64);
Trait Implementations
sourceimpl AddAssign<&Size> for Size
impl AddAssign<&Size> for Size
sourcefn add_assign(&mut self, other: &Size)
fn add_assign(&mut self, other: &Size)
+=
operation. Read moresourceimpl AddAssign<Size> for Size
impl AddAssign<Size> for Size
sourcefn add_assign(&mut self, other: Size)
fn add_assign(&mut self, other: Size)
+=
operation. Read moresourceimpl<T> DivAssign<T> for Sizewhere
T: AsIntermediate,
impl<T> DivAssign<T> for Sizewhere
T: AsIntermediate,
sourcefn div_assign(&mut self, other: T)
fn div_assign(&mut self, other: T)
/=
operation. Read moresourceimpl<T> MulAssign<T> for Sizewhere
T: AsIntermediate,
impl<T> MulAssign<T> for Sizewhere
T: AsIntermediate,
sourcefn mul_assign(&mut self, other: T)
fn mul_assign(&mut self, other: T)
*=
operation. Read moresourceimpl PartialOrd<&Size> for Size
impl PartialOrd<&Size> for Size
sourcefn partial_cmp(&self, other: &&Size) -> Option<Ordering>
fn partial_cmp(&self, other: &&Size) -> Option<Ordering>
1.0.0 · sourceconst fn le(&self, other: &Rhs) -> bool
const fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresourceimpl PartialOrd<Size> for Size
impl PartialOrd<Size> for Size
sourcefn partial_cmp(&self, other: &Size) -> Option<Ordering>
fn partial_cmp(&self, other: &Size) -> Option<Ordering>
1.0.0 · sourceconst fn le(&self, other: &Rhs) -> bool
const fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresourceimpl SubAssign<&Size> for Size
impl SubAssign<&Size> for Size
sourcefn sub_assign(&mut self, other: &Size)
fn sub_assign(&mut self, other: &Size)
-=
operation. Read moresourceimpl SubAssign<Size> for Size
impl SubAssign<Size> for Size
sourcefn sub_assign(&mut self, other: Size)
fn sub_assign(&mut self, other: Size)
-=
operation. Read more