diff --git a/CHANGELOG.md b/CHANGELOG.md index c0fc29b..11b4286 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,3 +11,4 @@ - Reject parsing non-unit characters after whitespace. - Remove `ByteSize::to_string_as()` method. - Remove top-level `to_string()` method. +- Remove top-level `B` constant. diff --git a/Cargo.toml b/Cargo.toml index 2b1fdef..d381243 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -28,3 +28,6 @@ quickcheck = "1" serde = { version = "1", features = ["derive"] } serde_json = "1" toml = "0.8" + +[lints.rust] +missing-docs = "warn" diff --git a/src/lib.rs b/src/lib.rs index 170fbf4..d750201 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -48,28 +48,26 @@ mod serde; use std::fmt::{self, Debug, Display, Formatter}; use std::ops::{Add, AddAssign, Mul, MulAssign, Sub, SubAssign}; -/// byte size for 1 byte -pub const B: u64 = 1; -/// bytes size for 1 kilobyte +/// Number of bytes in 1 kilobyte. pub const KB: u64 = 1_000; -/// bytes size for 1 megabyte +/// Number of bytes in 1 megabyte. pub const MB: u64 = 1_000_000; -/// bytes size for 1 gigabyte +/// Number of bytes in 1 gigabyte. pub const GB: u64 = 1_000_000_000; -/// bytes size for 1 terabyte +/// Number of bytes in 1 terabyte. pub const TB: u64 = 1_000_000_000_000; -/// bytes size for 1 petabyte +/// Number of bytes in 1 petabyte. pub const PB: u64 = 1_000_000_000_000_000; -/// bytes size for 1 kibibyte +/// Number of bytes in 1 kibibyte. pub const KIB: u64 = 1_024; -/// bytes size for 1 mebibyte +/// Number of bytes in 1 mebibyte. pub const MIB: u64 = 1_048_576; -/// bytes size for 1 gibibyte +/// Number of bytes in 1 gibibyte. pub const GIB: u64 = 1_073_741_824; -/// bytes size for 1 tebibyte +/// Number of bytes in 1 tebibyte. pub const TIB: u64 = 1_099_511_627_776; -/// bytes size for 1 pebibyte +/// Number of bytes in 1 pebibyte. pub const PIB: u64 = 1_125_899_906_842_624; /// IEC (binary) units. @@ -88,119 +86,150 @@ const LN_KIB: f64 = 6.931_471_805_599_453; /// `ln(1000) ~= 6.908` const LN_KB: f64 = 6.907_755_278_982_137; +/// Formatting style. #[derive(Debug, Clone, Default)] pub enum Format { + /// IEC (binary) representation. + /// + /// E.g., "1.0 MiB" #[default] IEC, + + /// SI (decimal) representation. + /// + /// E.g., "1.02 MB" SI, } -pub fn kb>(size: V) -> u64 { +/// Converts a quantity of kilobytes to bytes. +pub fn kb(size: impl Into) -> u64 { size.into() * KB } +/// Converts a quantity of kibibytes to bytes. pub fn kib>(size: V) -> u64 { size.into() * KIB } +/// Converts a quantity of megabytes to bytes. pub fn mb>(size: V) -> u64 { size.into() * MB } +/// Converts a quantity of mebibytes to bytes. pub fn mib>(size: V) -> u64 { size.into() * MIB } +/// Converts a quantity of gigabytes to bytes. pub fn gb>(size: V) -> u64 { size.into() * GB } +/// Converts a quantity of gibibytes to bytes. pub fn gib>(size: V) -> u64 { size.into() * GIB } +/// Converts a quantity of terabytes to bytes. pub fn tb>(size: V) -> u64 { size.into() * TB } +/// Converts a quantity of tebibytes to bytes. pub fn tib>(size: V) -> u64 { size.into() * TIB } +/// Converts a quantity of petabytes to bytes. pub fn pb>(size: V) -> u64 { size.into() * PB } +/// Converts a quantity of pebibytes to bytes. pub fn pib>(size: V) -> u64 { size.into() * PIB } -/// Byte size representation +/// Byte size representation. #[derive(Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Hash, Default)] pub struct ByteSize(pub u64); impl ByteSize { + /// Constructs a byte size wrapper from a quantity of bytes. #[inline(always)] pub const fn b(size: u64) -> ByteSize { ByteSize(size) } + /// Constructs a byte size wrapper from a quantity of kilobytes. #[inline(always)] pub const fn kb(size: u64) -> ByteSize { ByteSize(size * KB) } + /// Constructs a byte size wrapper from a quantity of kibibytes. #[inline(always)] pub const fn kib(size: u64) -> ByteSize { ByteSize(size * KIB) } + /// Constructs a byte size wrapper from a quantity of megabytes. #[inline(always)] pub const fn mb(size: u64) -> ByteSize { ByteSize(size * MB) } + /// Constructs a byte size wrapper from a quantity of mebibytes. #[inline(always)] pub const fn mib(size: u64) -> ByteSize { ByteSize(size * MIB) } + /// Constructs a byte size wrapper from a quantity of gigabytes. #[inline(always)] pub const fn gb(size: u64) -> ByteSize { ByteSize(size * GB) } + /// Constructs a byte size wrapper from a quantity of gibibytes. #[inline(always)] pub const fn gib(size: u64) -> ByteSize { ByteSize(size * GIB) } + /// Constructs a byte size wrapper from a quantity of terabytes. #[inline(always)] pub const fn tb(size: u64) -> ByteSize { ByteSize(size * TB) } + /// Constructs a byte size wrapper from a quantity of tebibytes. #[inline(always)] pub const fn tib(size: u64) -> ByteSize { ByteSize(size * TIB) } + /// Constructs a byte size wrapper from a quantity of petabytes. #[inline(always)] pub const fn pb(size: u64) -> ByteSize { ByteSize(size * PB) } + /// Constructs a byte size wrapper from a quantity of pebibytes. #[inline(always)] pub const fn pib(size: u64) -> ByteSize { ByteSize(size * PIB) } + /// Returns byte count. #[inline(always)] pub const fn as_u64(&self) -> u64 { self.0 } } +/// Constructs human-readable string representation of `bytes` with given `format` style. pub fn to_string_format(bytes: u64, format: Format) -> String { let unit = match format { Format::IEC => KIB, @@ -430,21 +459,12 @@ mod tests { let mut x = ByteSize::mb(1); assert_eq!((x + MB as u64).as_u64(), 2_000_000); - assert_eq!((x + MB as u32).as_u64(), 2_000_000); - assert_eq!((x + KB as u16).as_u64(), 1_001_000); - - assert_eq!((x + B as u8).as_u64(), 1_000_001); - assert_eq!((x - MB as u64).as_u64(), 0); - assert_eq!((x - MB as u32).as_u64(), 0); - assert_eq!((x - KB as u32).as_u64(), 999_000); - assert_eq!((x - B as u32).as_u64(), 999_999); - x += MB as u64; x += MB as u32; x += 10u16; diff --git a/src/parse.rs b/src/parse.rs index 3912eb5..83c5c5d 100644 --- a/src/parse.rs +++ b/src/parse.rs @@ -70,19 +70,19 @@ enum Unit { impl Unit { fn factor(&self) -> u64 { match self { - Self::Byte => super::B, - // power of tens - Self::KiloByte => super::KB, - Self::MegaByte => super::MB, - Self::GigaByte => super::GB, - Self::TeraByte => super::TB, - Self::PetaByte => super::PB, - // power of twos - Self::KibiByte => super::KIB, - Self::MebiByte => super::MIB, - Self::GibiByte => super::GIB, - Self::TebiByte => super::TIB, - Self::PebiByte => super::PIB, + Self::Byte => 1, + // decimal units + Self::KiloByte => crate::KB, + Self::MegaByte => crate::MB, + Self::GigaByte => crate::GB, + Self::TeraByte => crate::TB, + Self::PetaByte => crate::PB, + // binary units + Self::KibiByte => crate::KIB, + Self::MebiByte => crate::MIB, + Self::GibiByte => crate::GIB, + Self::TebiByte => crate::TIB, + Self::PebiByte => crate::PIB, } } }