Struct byte_unit::Byte

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

Available on crate features byte and u128 only.

Representing the size in bytes.

Implementations

impl Byte

Associated functions for generating AdjustedByte.

pub fn get_adjusted_unit(self, unit: Unit) -> AdjustedByte

Adjust the unit and value for this Byte instance.

Examples

use byte_unit::{AdjustedByte, Byte, Unit};

let byte = Byte::parse_str("123KiB", true).unwrap();

let adjusted_byte = byte.get_adjusted_unit(Unit::KB);

assert_eq!("125.952 KB", adjusted_byte.to_string());

use byte_unit::{AdjustedByte, Byte, Unit};

let byte = Byte::parse_str("50.84 MB", true).unwrap();

let adjusted_byte = byte.get_adjusted_unit(Unit::MiB);

assert_eq!("48.48480224609375 MiB", adjusted_byte.to_string());

pub fn get_appropriate_unit(&self, unit_type: UnitType) -> AdjustedByte

Find the appropriate unit and value for this Byte instance.

Examples

use byte_unit::{Byte, UnitType};

let byte = Byte::parse_str("123KiB", true).unwrap();

let adjusted_byte = byte.get_appropriate_unit(UnitType::Decimal);

assert_eq!("125.952 KB", adjusted_byte.to_string());

use byte_unit::{Byte, UnitType};

let byte = Byte::parse_str("50.84 MB", true).unwrap();

let adjusted_byte = byte.get_appropriate_unit(UnitType::Binary);

assert_eq!("48.48480224609375 MiB", adjusted_byte.to_string());

impl Byte

Constant Bytes.

pub const BYTE: Byte = _

One byte.

pub const KILOBYTE: Byte = _

1 KB = 10³ bytes.

pub const MEGABYTE: Byte = _

1 MB = 10⁶ bytes.

pub const GIGABYTE: Byte = _

1 GB = 10⁹ bytes.

pub const TERABYTE: Byte = _

1 TB = 10¹² bytes.

pub const PETABYTE: Byte = _

1 PB = 10¹⁵ bytes.

pub const EXABYTE: Byte = _

1 EB = 10¹⁸ bytes.

pub const ZETTABYTE: Byte = _

1 ZB = 10²¹ bytes.

pub const YOTTABYTE: Byte = _

1 YB = 10²⁴ bytes.

pub const KIBIBYTE: Byte = _

1 KiB = 2¹⁰ bytes.

pub const MEBIBYTE: Byte = _

1 MiB = 2²⁰ bytes.

pub const GIBIBYTE: Byte = _

1 GiB = 2³⁰ bytes.

pub const TEBIBYTE: Byte = _

1 TiB = 2⁴⁰ bytes.

pub const PEBIBYTE: Byte = _

1 PiB = 2⁵⁰ bytes.

pub const EXBIBYTE: Byte = _

1 EiB = 2⁶⁰ bytes.

pub const ZEBIBYTE: Byte = _

1 ZiB = 2⁷⁰ bytes.

pub const YOBIBYTE: Byte = _

1 YiB = 2⁸⁰ bytes.

pub const KILOBIT: Byte = _

1 Kbit = 125 bytes.

pub const MEGABIT: Byte = _

1 Mbit = 125 * 10³ bytes.

pub const GIGABIT: Byte = _

1 Gbit = 125 * 10⁶ bytes.

pub const TERABIT: Byte = _

1 Tbit = 125 * 10⁹ bytes.

pub const PETABIT: Byte = _

1 Pbit = 125 * 10¹² bytes.

pub const EXABIT: Byte = _

1 Ebit = 125 * 10¹⁵ bytes.

pub const ZETTABIT: Byte = _

1 Zbit = 125 * 10¹⁸ bytes.

pub const YOTTABIT: Byte = _

1 Ybit = 125 * 10²¹ bytes.

pub const KIBIBIT: Byte = _

1 Kibit = 2⁷ bytes.

pub const MEBIBIT: Byte = _

1 Mibit = 2¹⁷ bytes.

pub const GIBIBIT: Byte = _

1 Gibit = 2²⁷ bytes.

pub const TEBIBIT: Byte = _

1 Tibit = 2³⁷ bytes.

pub const PEBIBIT: Byte = _

1 Pibit = 2⁴⁷ bytes.

pub const EXBIBIT: Byte = _

1 Eibit = 2⁵⁷ bytes.

pub const ZEBIBIT: Byte = _

1 Zibit = 2⁶⁷ bytes.

pub const YOBIBIT: Byte = _

1 Yibit = 2⁷⁷ bytes.

pub const MIN: Byte = _

0 byte.

pub const MAX: Byte = _

10²⁷ - 1 bytes if the u128 feature is enabled, or 2⁶⁴ - 1 otherwise.

impl Byte

Associated functions for building Byte instances using Decimal.

pub fn from_decimal(size: Decimal) -> Option<Self>

Create a new Byte instance from a size in bytes.

Examples

use byte_unit::Byte;
use rust_decimal::Decimal;

let byte = Byte::from_decimal(Decimal::from(15000000u64)).unwrap(); // 15 MB

Points to Note

• If the input size is too large (the maximum is 10²⁷ - 1 if the u128 feature is enabled, or 2⁶⁴ - 1 otherwise) or not greater than or equal to 0, this function will return None.
• The fractional part will be rounded up.

impl Byte

Associated functions for building Byte instances using Decimal (with Unit).

pub fn from_decimal_with_unit(size: Decimal, unit: Unit) -> Option<Self>

Create a new Byte instance from a size of bytes with a unit.

Examples

use byte_unit::{Byte, Unit};
use rust_decimal::Decimal;

let byte = Byte::from_decimal_with_unit(Decimal::from(15u64), Unit::MB).unwrap(); // 15 MB

Points to Note

• If the calculated byte is too large or not greater than or equal to 0, this function will return None.
• The calculated byte will be rounded up.

impl Byte

Methods for finding an unit using Decimal.

pub fn get_recoverable_unit( self, allow_in_bits: bool, precision: usize ) -> (Decimal, Unit)

Find the appropriate unit and value that can be used to recover back to this Byte precisely.

Examples

use byte_unit::{Byte, Unit};

let byte = Byte::from_u64(3670016);

assert_eq!(
    (3.5f64.try_into().unwrap(), Unit::MiB),
    byte.get_recoverable_unit(false, 3)
);

use byte_unit::{Byte, Unit};

let byte = Byte::from_u64(437500);

assert_eq!(
    (3.5f64.try_into().unwrap(), Unit::Mbit),
    byte.get_recoverable_unit(true, 3)
);

use byte_unit::{Byte, Unit};

let byte = Byte::from_u64(437500);

assert_eq!(
    (437.5f64.try_into().unwrap(), Unit::KB),
    byte.get_recoverable_unit(false, 3)
);

Points to Note

• precision should be smaller or equal to 26 if the u128 feature is enabled, otherwise 19. The typical precision is 3.

impl Byte

Associated functions for parsing strings.

pub fn parse_str<S: AsRef<str>>( s: S, ignore_case: bool ) -> Result<Self, ParseError>

Create a new Byte instance from a string. The string may be "10", "10B", "10M", "10MB", "10MiB", "80b", "80Mb", "80Mbit".

You can ignore the case of “B” (byte), which means b will still be treated as bytes instead of bits.

Examples

let byte = Byte::parse_str("123Kib", true).unwrap(); // 123 * 1024 bytes

let byte = Byte::parse_str("123Kib", false).unwrap(); // 123 * 1024 bits = 123 * 1024 / 8 bytes

impl Byte

Associated functions for building Byte instances.

pub const fn from_u128(size: u128) -> Option<Self>

Create a new Byte instance from a size in bytes.

Examples

let byte = Byte::from_u128(15000000).unwrap(); // 15 MB

Points to Note

• If the input size is too large (the maximum is 10²⁷ - 1 if the u128 feature is enabled, or 2⁶⁴ - 1 otherwise), this function will return None.

pub const unsafe fn from_u128_unsafe(size: u128) -> Self

Create a new Byte instance from a size in bytes.

Examples

let byte = unsafe { Byte::from_u128_unsafe(15000000) }; // 15 MB

Safety

You must ensure the input size is not too large (the maximum is 10²⁷ - 1 if the u128 feature is enabled, or 2⁶⁴ - 1 otherwise) on your own.

pub const fn from_u64(size: u64) -> Self

Create a new Byte instance from a size in bytes.

Examples

let byte = Byte::from_u64(15000000); // 15 MB

pub fn from_f64(size: f64) -> Option<Self>

Create a new Byte instance from a size im bytes.

Examples

let byte = Byte::from_f64(15000000.0).unwrap(); // 15 MB

Points to Note

• If the input size is too large (the maximum is 10²⁷ - 1 if the u128 feature is enabled, or 2⁶⁴ - 1 otherwise) or not greater than or equal to 0, this function will return None.
• The fractional part will be rounded up.

pub fn from_f32(size: f32) -> Option<Self>

Create a new Byte instance from a size in bytes.

Examples

let byte = Byte::from_f32(15000000.0).unwrap(); // 15 MB

Points to Note

• If the input size is too large (the maximum is 10²⁷ - 1 if the u128 feature is enabled, or 2⁶⁴ - 1 otherwise) or not greater than or equal to 0, this function will return None.
• The fractional part will be rounded up.

pub const fn from_i128(size: i128) -> Option<Self>

Create a new Byte instance from a size in bytes.

Examples

let byte = Byte::from_i128(15000000).unwrap(); // 15 MB

Points to Note

• If the input size is too large (the maximum is 10²⁷ - 1 if the u128 feature is enabled, or 2⁶⁴ - 1 otherwise) or negative, this function will return None.

pub const fn from_i64(size: i64) -> Option<Self>

Create a new Byte instance from a size in bytes.

Examples

let byte = Byte::from_i64(15000000).unwrap(); // 15 MB

Points to Note

• If the input size is negative, this function will return None.

impl Byte

Associated functions for building Byte instances (with Unit).

pub const fn from_u128_with_unit(size: u128, unit: Unit) -> Option<Self>

Create a new Byte instance from a size of bytes with a unit.

Examples

use byte_unit::{Byte, Unit};

let byte = Byte::from_u128_with_unit(15, Unit::MB).unwrap(); // 15 MB

Points to Note

• If the calculated byte is too large, this function will return None.
• If the input unit is Bit, the calculated byte will be rounded up.

pub const fn from_u64_with_unit(size: u64, unit: Unit) -> Option<Self>

Create a new Byte instance from a size of bytes with a unit.

Examples

use byte_unit::{Byte, Unit};

let byte = Byte::from_u64_with_unit(15, Unit::MB).unwrap(); // 15 MB

Points to Note

• If the calculated byte is too large, this function will return None.
• If the input unit is Bit, the calculated byte will be rounded up.

pub fn from_f64_with_unit(size: f64, unit: Unit) -> Option<Self>

Create a new Byte instance from a size of bytes with a unit.

Examples

use byte_unit::{Byte, Unit};

let byte = Byte::from_f64_with_unit(15.0, Unit::MB).unwrap(); // 15 MB

Points to Note

• If the calculated byte is too large or not greater than or equal to 0, this function will return None.
• The calculated byte will be rounded up.

pub fn from_f32_with_unit(size: f32, unit: Unit) -> Option<Self>

Create a new Byte instance from a size of bytes with a unit.

Examples

use byte_unit::{Byte, Unit};

let byte = Byte::from_f32_with_unit(15.0, Unit::MB).unwrap(); // 15 MB

Points to Note

• If the calculated byte is too large or not greater than or equal to 0, this function will return None.
• The calculated byte will be rounded up.

pub const fn from_i128_with_unit(size: i128, unit: Unit) -> Option<Self>

Create a new Byte instance from a size of bytes with a unit.

Examples

use byte_unit::{Byte, Unit};

let byte = Byte::from_i128_with_unit(15, Unit::MB).unwrap(); // 15 MB

Points to Note

• If the calculated byte is too large or negative, this function will return None.
• The calculated byte will be rounded up.

pub const fn from_i64_with_unit(size: i64, unit: Unit) -> Option<Self>

Create a new Byte instance from a size of bytes with a unit.

Examples

use byte_unit::{Byte, Unit};

let byte = Byte::from_i64_with_unit(15, Unit::MB).unwrap(); // 15 MB

Points to Note

• If the calculated byte is too large or negative, this function will return None.
• The calculated byte will be rounded up.

impl Byte

Methods for converting a Byte instance into a primitive integer.

pub const fn as_u128(self) -> u128

Retrieve the byte represented by this Byte instance.

Examples

use byte_unit::Byte;

let byte = Byte::parse_str("123Kib", true).unwrap();

let result = byte.as_u128();

assert_eq!(125952, result);

use byte_unit::Byte;

let byte = Byte::parse_str("123Kib", false).unwrap();

let result = byte.as_u128();

assert_eq!(15744, result);

pub const fn as_u64(self) -> u64

Retrieve the byte represented by this Byte instance. When the u128 feature is enabled, if the byte is actually greater than 2⁶⁴ - 1, it will return 2⁶⁴ - 1.

Examples

use byte_unit::Byte;

let byte = Byte::parse_str("1kb", true).unwrap();

let result = byte.as_u64();

assert_eq!(1000, result);

use byte_unit::Byte;

let byte = Byte::parse_str("1zb", true).unwrap();

let result = byte.as_u64();

assert_eq!(u64::MAX, result);

pub const fn as_u64_checked(self) -> Option<u64>

Retrieve the byte represented by this Byte instance.

Examples

use byte_unit::Byte;

let byte = Byte::parse_str("1kb", true).unwrap();

let result = byte.as_u64_checked();

assert_eq!(Some(1000), result);

use byte_unit::Byte;

let byte = Byte::parse_str("1zb", true).unwrap();

let result = byte.as_u64_checked();

assert_eq!(None, result);

impl Byte

Methods for calculation.

pub const fn add(self, rhs: Byte) -> Option<Byte>

Add another Byte instance.

Examples

use byte_unit::Byte;

let byte_1 = Byte::from_u64(1024);
let byte_2 = Byte::from_u64(512);

let byte = byte_1.add(byte_2).unwrap();

assert_eq!(1536, byte.as_u64());

Points to Note

• If the calculated byte is too large, this function will return None.

pub const fn subtract(self, rhs: Byte) -> Option<Byte>

Subtract another Byte instance.

Examples

use byte_unit::Byte;

let byte_1 = Byte::from_u64(1024);
let byte_2 = Byte::from_u64(512);

let byte = byte_1.subtract(byte_2).unwrap();

assert_eq!(512, byte.as_u64());

Points to Note

• If the right-hand side is bigger then this Byte instance, this function will return None.

pub const fn multiply(self, rhs: usize) -> Option<Byte>

Multiplied by an unsigned integer.

Examples

use byte_unit::Byte;

let count = 100;
let byte = Byte::from_u64(1024);

let total_byte = byte.multiply(100).unwrap();

assert_eq!(102400, total_byte.as_u64());

Points to Note

• If the calculated byte is too large, this function will return None.

pub const fn divide(self, rhs: usize) -> Option<Byte>

Divided by an unsigned integer.

Examples

use byte_unit::Byte;

let count = 100;
let byte = Byte::from_u64(1024);

let total_byte = byte.divide(100).unwrap();

assert_eq!(10, total_byte.as_u64());

Points to Note

• If the input right-hand side is zero, this function will return None.
• The result will be rounded down.

impl Byte

Methods for finding an unit.

pub const fn get_exact_unit(self, allow_in_bits: bool) -> (u128, Unit)

Obtain the largest unit which is the greatest factor of this Byte instance.

Examples

use byte_unit::{Byte, Unit};

let byte = Byte::from_u64(3145728);

let (n, unit) = byte.get_exact_unit(true);

assert_eq!(3, n);
assert_eq!(Unit::MiB, unit);

use byte_unit::{Byte, Unit};

let byte = Byte::from_u64(375000);

let (n, unit) = byte.get_exact_unit(true);

assert_eq!(3, n);
assert_eq!(Unit::Mbit, unit);

use byte_unit::{Byte, Unit};

let byte = Byte::from_u64(375000);

let (n, unit) = byte.get_exact_unit(false);

assert_eq!(375, n);
assert_eq!(Unit::KB, unit);

Trait Implementations

impl Clone for Byte

fn clone(&self) -> Byte

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Byte

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

Formats the value using the given formatter.

impl Default for Byte

fn default() -> Byte

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Byte

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Byte

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

Formats the value using the given formatter.

Examples

use byte_unit::{Byte, Unit};

let byte = Byte::from_u64_with_unit(1555, Unit::KB).unwrap();

assert_eq!("1555000", byte.to_string());

use byte_unit::{Byte, UnitType};

let byte_based_2 = Byte::from_u64(10240);
let byte_based_10 = Byte::from_u64(10000);

assert_eq!("10240", format!("{byte_based_2}"));
assert_eq!("10000", format!("{byte_based_10}"));

// with an exact unit
assert_eq!("10 KiB", format!("{byte_based_2:#}"));
assert_eq!("10 KB", format!("{byte_based_10:#}"));

// with an exact unit, no spaces between the value and the unit
assert_eq!("10KiB", format!("{byte_based_2:-#}"));
assert_eq!("10KB", format!("{byte_based_10:-#}"));

// with a width, left alignment
assert_eq!("10     KiB", format!("{byte_based_2:#10}"));
assert_eq!("10      KB", format!("{byte_based_10:#10}"));

// with a width, right alignment
assert_eq!("    10 KiB", format!("{byte_based_2:>#10}"));
assert_eq!("     10 KB", format!("{byte_based_10:>#10}"));

// with a width, right alignment, more spaces between the value and the unit
assert_eq!("    10 KiB", format!("{byte_based_2:>+#10}"));
assert_eq!("    10  KB", format!("{byte_based_10:>+#10}"));

use byte_unit::{Byte, UnitType};

let byte = Byte::from_u64(3211776);

assert_eq!("3211776", format!("{byte}"));

// with a unit, still precisely
assert_eq!("3136.5 KiB", format!("{byte:#}"));

// with a unit and a larger precision (default is 3), still precisely
assert_eq!("3.211776 MB", format!("{byte:#.6}"));

// with a unit and a smaller precision (default is 3), still precisely
assert_eq!("3211776 B", format!("{byte:#.0}"));

impl From<AdjustedByte> for Byte

fn from(value: AdjustedByte) -> Self

Converts to this type from the input type.

impl From<Byte> for AdjustedByte

fn from(value: Byte) -> Self

unit_type is set to UnitType::Both. See Byte::get_appropriate_unit.

impl From<Byte> for u128

fn from(byte: Byte) -> Self

Converts to this type from the input type.

impl From<Byte> for u64

fn from(byte: Byte) -> Self

Converts to this type from the input type.

impl From<u16> for Byte

fn from(value: u16) -> Self

Converts to this type from the input type.

impl From<u32> for Byte

fn from(value: u32) -> Self

Converts to this type from the input type.

impl From<u64> for Byte

fn from(value: u64) -> Self

Converts to this type from the input type.

impl From<u8> for Byte

fn from(value: u8) -> Self

Converts to this type from the input type.

impl From<usize> for Byte

fn from(value: usize) -> Self

Converts to this type from the input type.

impl FromStr for Byte

fn from_str(s: &str) -> Result<Self, Self::Err>

ignore_case is set to false. See Byte::parse_str.

type Err = ParseError

The associated error which can be returned from parsing.

impl Hash for Byte

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

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 Ord for Byte

fn cmp(&self, other: &Byte) -> 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 + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Byte

fn eq(&self, other: &Byte) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Byte

fn partial_cmp(&self, other: &Byte) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Byte

Available on crate feature serde only.

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<Byte> for u16

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(byte: Byte) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Byte> for u32

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(byte: Byte) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Byte> for u8

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(byte: Byte) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Byte> for usize

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(byte: Byte) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<f32> for Byte

type Error = ExceededBoundsError

The type returned in the event of a conversion error.

fn try_from(value: f32) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<f64> for Byte

type Error = ExceededBoundsError

The type returned in the event of a conversion error.

fn try_from(value: f64) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<i128> for Byte

type Error = ExceededBoundsError

The type returned in the event of a conversion error.

fn try_from(value: i128) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<i16> for Byte

type Error = ExceededBoundsError

The type returned in the event of a conversion error.

fn try_from(value: i16) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<i32> for Byte

type Error = ExceededBoundsError

The type returned in the event of a conversion error.

fn try_from(value: i32) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<i64> for Byte

type Error = ExceededBoundsError

The type returned in the event of a conversion error.

fn try_from(value: i64) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<i8> for Byte

type Error = ExceededBoundsError

The type returned in the event of a conversion error.

fn try_from(value: i8) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<isize> for Byte

type Error = ExceededBoundsError

The type returned in the event of a conversion error.

fn try_from(value: isize) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<u128> for Byte

type Error = ExceededBoundsError

The type returned in the event of a conversion error.

fn try_from(value: u128) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for Byte

impl Eq for Byte

impl StructuralEq for Byte

impl StructuralPartialEq for Byte