docs: document all public items (#73)

* fix: swap values of `LN_KIB` & `LN_KB`

* fix: invert SI/IEC conditions

- Conditions that check whether the SI or IEC units must be used were
  inverted, i.e., when `si_prefix == true` it would use `"iB"` instead of
  `"B"`.
- KB & kiB were used instead of kB & KiB.
- Switches (true/false) in tests are also fixed.

* fix: format with IEC (binary) by default

* docs: doc units_* statics

* refactor: move statics to consts

* refactor: introduce format enum

* test: use to_string_format in tests

* chore: expand debug impl

* fix: increase precision of LN_ constants

* chore: remove to_string_as method

* docs: document all public items

* chore: remove useless B constant

---------

Co-authored-by: Andrew Voynov <[email protected]>

Author: robjtede

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.

Cargo.toml

@@ -28,3 +28,6 @@ quickcheck = "1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 toml = "0.8"
+
+[lints.rust]
+missing-docs = "warn"

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<V: Into<u64>>(size: V) -> u64 {
+/// Converts a quantity of kilobytes to bytes.
+pub fn kb(size: impl Into<u64>) -> u64 {
     size.into() * KB
 }
 
+/// Converts a quantity of kibibytes to bytes.
 pub fn kib<V: Into<u64>>(size: V) -> u64 {
     size.into() * KIB
 }
 
+/// Converts a quantity of megabytes to bytes.
 pub fn mb<V: Into<u64>>(size: V) -> u64 {
     size.into() * MB
 }
 
+/// Converts a quantity of mebibytes to bytes.
 pub fn mib<V: Into<u64>>(size: V) -> u64 {
     size.into() * MIB
 }
 
+/// Converts a quantity of gigabytes to bytes.
 pub fn gb<V: Into<u64>>(size: V) -> u64 {
     size.into() * GB
 }
 
+/// Converts a quantity of gibibytes to bytes.
 pub fn gib<V: Into<u64>>(size: V) -> u64 {
     size.into() * GIB
 }
 
+/// Converts a quantity of terabytes to bytes.
 pub fn tb<V: Into<u64>>(size: V) -> u64 {
     size.into() * TB
 }
 
+/// Converts a quantity of tebibytes to bytes.
 pub fn tib<V: Into<u64>>(size: V) -> u64 {
     size.into() * TIB
 }
 
+/// Converts a quantity of petabytes to bytes.
 pub fn pb<V: Into<u64>>(size: V) -> u64 {
     size.into() * PB
 }
 
+/// Converts a quantity of pebibytes to bytes.
 pub fn pib<V: Into<u64>>(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;

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,
         }
     }
 }