Struct byte_unit::Bit

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

Available on crate features bit and u128 only.

Representing the size in bits.

Implementations

impl Bit

Associated functions for generating AdjustedBit.

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

Adjust the unit and value for this Bit instance.

Examples

use byte_unit::{AdjustedBit, Bit, Unit};

let bit = Bit::parse_str("123Kib").unwrap();

let adjusted_bit = bit.get_adjusted_unit(Unit::Kbit);

assert_eq!("125.952 Kb", adjusted_bit.to_string());

use byte_unit::{AdjustedBit, Bit, Unit};

let bit = Bit::parse_str("50.84 Mb").unwrap();

let adjusted_bit = bit.get_adjusted_unit(Unit::Mibit);

assert_eq!("48.48480224609375 Mib", adjusted_bit.to_string());

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

Find the appropriate unit and value for this Bit instance.

Examples

use byte_unit::{Bit, UnitType};

let bit = Bit::parse_str("123Kib").unwrap();

let adjusted_bit = bit.get_appropriate_unit(UnitType::Decimal);

assert_eq!("125.952 Kb", adjusted_bit.to_string());

use byte_unit::{Bit, UnitType};

let bit = Bit::parse_str("50.84 Mb").unwrap();

let adjusted_bit = bit.get_appropriate_unit(UnitType::Binary);

assert_eq!("48.48480224609375 Mib", adjusted_bit.to_string());

impl Bit

Constant Bits.

pub const BIT: Bit = _

One bit.

pub const KILOBIT: Bit = _

1 Kbit = 10³ bits.

pub const MEGABIT: Bit = _

1 Mbit = 10⁶ bits.

pub const GIGABIT: Bit = _

1 Gbit = 10⁹ bits.

pub const TERABIT: Bit = _

1 Tbit = 10¹² bits.

pub const PETABIT: Bit = _

1 Pbit = 10¹⁵ bits.

pub const EXABIT: Bit = _

1 Ebit = 10¹⁸ bits.

pub const ZETTABIT: Bit = _

1 Zbit = 10²¹ bits.

pub const YOTTABIT: Bit = _

1 Ybit = 10²⁴ bits.

pub const KIBIBIT: Bit = _

1 Kibit = 2¹⁰ bits.

pub const MEBIBIT: Bit = _

1 Mibit = 2²⁰ bits.

pub const GIBIBIT: Bit = _

1 Gibit = 2³⁰ bits.

pub const TEBIBIT: Bit = _

1 Tibit = 2⁴⁰ bits.

pub const PEBIBIT: Bit = _

1 Pibit = 2⁵⁰ bits.

pub const EXBIBIT: Bit = _

1 Eibit = 2⁶⁰ bits.

pub const ZEBIBIT: Bit = _

1 Zibit = 2⁷⁰ bits.

pub const YOBIBIT: Bit = _

1 Yibit = 2⁸⁰ bits.

pub const KILOBYTE: Bit = _

1 KB = 8 * 10³ bits.

pub const MEGABYTE: Bit = _

1 MB = 8 * 10⁶ bits.

pub const GIGABYTE: Bit = _

1 GB = 8 * 10⁹ bits.

pub const TERABYTE: Bit = _

1 TB = 8 * 10¹² bits.

pub const PETABYTE: Bit = _

1 PB = 8 * 10¹⁵ bits.

pub const EXABYTE: Bit = _

1 EB = 8 * 10¹⁸ bits.

pub const ZETTABYTE: Bit = _

1 ZB = 8 * 10²¹ bits.

pub const YOTTABYTE: Bit = _

1 YB = 8 * 10²⁴ bits.

pub const KIBIBYTE: Bit = _

1 KiB = 2¹³ bits.

pub const MEBIBYTE: Bit = _

1 MiB = 2²³ bits.

pub const GIBIBYTE: Bit = _

1 GiB = 2³³ bits.

pub const TEBIBYTE: Bit = _

1 TiB = 2⁴³ bits.

pub const PEBIBYTE: Bit = _

1 PiB = 2⁵³ bits.

pub const EXBIBYTE: Bit = _

1 EiB = 2⁶³ bits.

pub const ZEBIBYTE: Bit = _

1 ZiB = 2⁷³ bits.

pub const YOBIBYTE: Bit = _

1 YiB = 2⁸³ bits.

pub const MIN: Bit = _

0 bit.

pub const MAX: Bit = _

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

impl Bit

Associated functions for building Bit instances using Decimal.

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

Create a new Bit instance from a size in bits.

Examples

use byte_unit::Bit;
use rust_decimal::Decimal;

let bit = Bit::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 Bit

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

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

Create a new Bit instance from a size of bits with a unit.

Examples

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

let bit = Bit::from_decimal_with_unit(Decimal::from(15u64), Unit::Mbit).unwrap(); // 15 Mb

Points to Note

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

impl Bit

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 Bit precisely.

Examples

use byte_unit::{Bit, Unit};

let bit = Bit::from_u64(3670016);

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

use byte_unit::{Bit, Unit};

let bit = Bit::from_u64(28000000);

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

use byte_unit::{Bit, Unit};

let bit = Bit::from_u64(437500);

assert_eq!(
    (437.5f64.try_into().unwrap(), Unit::Kbit),
    bit.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 Bit

Associated functions for parsing strings.

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

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

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

Examples

let bit = Bit::parse_str("123Kib").unwrap(); // 123 * 1024 bits

impl Bit

Associated functions for building Bit instances.

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

Create a new Bit instance from a size in bits.

Examples

let bit = Bit::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 Bit instance from a size in bits.

Examples

let bit = unsafe { Bit::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 Bit instance from a size in bits.

Examples

let bit = Bit::from_u64(15000000); // 15 Mb

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

Create a new Bit instance from a size im bits.

Examples

let bit = Bit::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 Bit instance from a size in bits.

Examples

let bit = Bit::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 Bit instance from a size in bits.

Examples

let bit = Bit::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 Bit instance from a size in bits.

Examples

let bit = Bit::from_i64(15000000).unwrap(); // 15 Mb

Points to Note

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

impl Bit

Associated functions for building Bit instances (with Unit).

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

Create a new Bit instance from a size of bits with a unit.

Examples

use byte_unit::{Bit, Unit};

let bit = Bit::from_u128_with_unit(15, Unit::Mbit).unwrap(); // 15 Mb

Points to Note

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

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

Create a new Bit instance from a size of bits with a unit.

Examples

use byte_unit::{Bit, Unit};

let bit = Bit::from_u64_with_unit(15, Unit::Mbit).unwrap(); // 15 Mb

Points to Note

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

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

Create a new Bit instance from a size of bits with a unit.

Examples

use byte_unit::{Bit, Unit};

let bit = Bit::from_f64_with_unit(15.0, Unit::Mbit).unwrap(); // 15 Mb

Points to Note

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

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

Create a new Bit instance from a size of bits with a unit.

Examples

use byte_unit::{Bit, Unit};

let bit = Bit::from_f32_with_unit(15.0, Unit::Mbit).unwrap(); // 15 Mb

Points to Note

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

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

Create a new Bit instance from a size of bits with a unit.

Examples

use byte_unit::{Bit, Unit};

let bit = Bit::from_i128_with_unit(15, Unit::Mibit).unwrap(); // 15 Mb

Points to Note

• If the calculated bit is too large or negative, this function will return None.

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

Create a new Bit instance from a size of bits with a unit.

Examples

use byte_unit::{Bit, Unit};

let bit = Bit::from_i64_with_unit(15, Unit::Mbit).unwrap(); // 15 Mb

Points to Note

• If the calculated bit is too large or negative, this function will return None.

impl Bit

Methods for converting a Bit instance into a primitive integer.

pub const fn as_u128(self) -> u128

Retrieve the bit represented by this Bit instance.

Examples

use byte_unit::Bit;

let bit = Bit::parse_str("123KiB").unwrap();

let result = bit.as_u128();

assert_eq!(1007616, result);

use byte_unit::Bit;

let bit = Bit::parse_str("123Kib").unwrap();

let result = bit.as_u128();

assert_eq!(125952, result);

pub const fn as_u64(self) -> u64

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

Examples

use byte_unit::Bit;

let bit = Bit::parse_str("1kb").unwrap();

let result = bit.as_u64();

assert_eq!(1000, result);

use byte_unit::Bit;

let bit = Bit::parse_str("1zb").unwrap();

let result = bit.as_u64();

assert_eq!(u64::MAX, result);

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

Retrieve the bit represented by this Bit instance.

Examples

use byte_unit::Bit;

let bit = Bit::parse_str("1k").unwrap();

let result = bit.as_u64_checked();

assert_eq!(Some(1000), result);

use byte_unit::Bit;

let bit = Bit::parse_str("1zb").unwrap();

let result = bit.as_u64_checked();

assert_eq!(None, result);

impl Bit

Methods for calculation.

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

Add another Bit instance.

Examples

use byte_unit::Bit;

let bit_1 = Bit::from_u64(1024);
let bit_2 = Bit::from_u64(512);

let bit = bit_1.add(bit_2).unwrap();

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

Points to Note

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

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

Subtract another Bit instance.

Examples

use byte_unit::Bit;

let bit_1 = Bit::from_u64(1024);
let bit_2 = Bit::from_u64(512);

let bit = bit_1.subtract(bit_2).unwrap();

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

Points to Note

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

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

Multiplied by an unsigned integer.

Examples

use byte_unit::Bit;

let count = 100;
let bit = Bit::from_u64(1024);

let total_bit = bit.multiply(100).unwrap();

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

Points to Note

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

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

Divided by an unsigned integer.

Examples

use byte_unit::Bit;

let count = 100;
let bit = Bit::from_u64(1024);

let total_bit = bit.divide(100).unwrap();

assert_eq!(10, total_bit.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 Bit

Methods for finding an unit.

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

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

Examples

use byte_unit::{Bit, Unit};

let bit = Bit::from_u64(3145728);

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

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

use byte_unit::{Bit, Unit};

let bit = Bit::from_u64(24000000);

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

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

use byte_unit::{Bit, Unit};

let bit = Bit::from_u64(24000000);

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

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

Trait Implementations

impl Clone for Bit

fn clone(&self) -> Bit

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Bit

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

Formats the value using the given formatter.

impl Default for Bit

fn default() -> Bit

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Bit

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 Bit

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

Formats the value using the given formatter.

Examples

use byte_unit::{Bit, Unit};

let bit = Bit::from_u64_with_unit(1555, Unit::Kbit).unwrap();

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

use byte_unit::{Bit, UnitType};

let bit_based_2 = Bit::from_u64(10240);
let bit_based_10 = Bit::from_u64(10000);

assert_eq!("10240", format!("{bit_based_2}"));
assert_eq!("10000", format!("{bit_based_10}"));

// with an exact unit
assert_eq!("10 Kib", format!("{bit_based_2:#}"));
assert_eq!("10 Kb", format!("{bit_based_10:#}"));

// with an exact unit, no spaces between the value and the unit
assert_eq!("10Kib", format!("{bit_based_2:-#}"));
assert_eq!("10Kb", format!("{bit_based_10:-#}"));

// with a width, left alignment
assert_eq!("10     Kib", format!("{bit_based_2:#10}"));
assert_eq!("10      Kb", format!("{bit_based_10:#10}"));

// with a width, right alignment
assert_eq!("    10 Kib", format!("{bit_based_2:>#10}"));
assert_eq!("     10 Kb", format!("{bit_based_10:>#10}"));

// with a width, right alignment, more spaces between the value and the unit
assert_eq!("    10 Kib", format!("{bit_based_2:>+#10}"));
assert_eq!("    10  Kb", format!("{bit_based_10:>+#10}"));

use byte_unit::{Bit, UnitType};

let bit = Bit::from_u64(3211776);

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

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

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

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

impl From<AdjustedBit> for Bit

fn from(value: AdjustedBit) -> Self

Converts to this type from the input type.

impl From<Bit> for AdjustedBit

fn from(value: Bit) -> Self

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

impl From<Bit> for u128

fn from(bit: Bit) -> Self

Converts to this type from the input type.

impl From<Bit> for u64

fn from(bit: Bit) -> Self

Converts to this type from the input type.

impl From<u16> for Bit

fn from(value: u16) -> Self

Converts to this type from the input type.

impl From<u32> for Bit

fn from(value: u32) -> Self

Converts to this type from the input type.

impl From<u64> for Bit

fn from(value: u64) -> Self

Converts to this type from the input type.

impl From<u8> for Bit

fn from(value: u8) -> Self

Converts to this type from the input type.

impl From<usize> for Bit

fn from(value: usize) -> Self

Converts to this type from the input type.

impl FromStr for Bit

type Err = ParseError

The associated error which can be returned from parsing.

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

Parses a string s to return a value of this type.

impl Hash for Bit

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 Bit

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

fn eq(&self, other: &Bit) -> 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 Bit

fn partial_cmp(&self, other: &Bit) -> 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 Bit

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<Bit> for u16

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(bit: Bit) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Bit> for u32

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(bit: Bit) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Bit> for u8

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(bit: Bit) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Bit> for usize

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(bit: Bit) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<f32> for Bit

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 Bit

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 Bit

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 Bit

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 Bit

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 Bit

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 Bit

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 Bit

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 Bit

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 Bit

impl Eq for Bit

impl StructuralEq for Bit

impl StructuralPartialEq for Bit