ubyte/
lib.rs

1#![no_std]
2
3//! A simple, complete, `const`-everything, saturating, human-friendly,
4//! `#![no_std]` library for byte units.
5//!
6//! ```rust
7//! use ubyte::{ByteUnit, ToByteUnit};
8//!
9//! // Constructors and associated units for all SI units up to exbibyte.
10//! let half_mb = 500.kilobytes();
11//! let half_mb = ByteUnit::Kilobyte(500);
12//! let half_mb = 500 * ByteUnit::kB;
13//!
14//! // All arithmetic operations and conversions saturate.
15//! let exbibyte_too_large_a = 1024 * ByteUnit::EiB;
16//! let exbibyte_too_large_b = ByteUnit::Exbibyte(1024);
17//! let exbibyte_too_large_c = 1024.exbibytes();
18//! assert_eq!(exbibyte_too_large_a, ByteUnit::max_value());
19//! assert_eq!(exbibyte_too_large_b, ByteUnit::max_value());
20//! assert_eq!(exbibyte_too_large_c, ByteUnit::max_value());
21//!
22//! // Printing is human-friendly and customizeable.
23//! assert_eq!(323.kilobytes().to_string(), "323kB");
24//! assert_eq!(3.mebibytes().to_string(), "3MiB");
25//! assert_eq!((7.gigabytes() + 58.mebibytes() + 3.kilobytes()).to_string(), "7.06GB");
26//! assert_eq!(format!("{:.0}", 7.gibibytes() + 920.mebibytes()), "8GiB");
27//! assert_eq!(format!("{:.3}", 7.gibibytes() + 920.mebibytes()), "7.898GiB");
28//! assert_eq!(format!("{:04.2}", 999.kilobytes() + 990.bytes()), "0976.55KiB");
29//! assert_eq!(format!("{:02.0}", 999.kilobytes() + 990.bytes()), "01MB");
30//!
31//! // Parsing is intuitive. Explicit `ByteUnit` is typically unnecessary.
32//! assert_eq!("10 KiB".parse::<ByteUnit>().unwrap(), 10.kibibytes());
33//! assert_eq!("10 kb".parse::<ByteUnit>().unwrap(), 10.kilobytes());
34//! assert_eq!("512Kb".parse::<ByteUnit>().unwrap(), 512.kilobytes());
35//! assert_eq!("99kb".parse::<ByteUnit>().unwrap(), 99.kilobytes());
36//! assert_eq!("1 MiB".parse::<ByteUnit>().unwrap(), 1.mebibytes());
37//! assert_eq!("1.5 MiB".parse::<ByteUnit>().unwrap(), 1.mebibytes() + 512.kibibytes());
38//! assert_eq!("0.2MB".parse::<ByteUnit>().unwrap(), 200.kilobytes());
39//! assert_eq!("7.25 gb".parse::<ByteUnit>().unwrap(), 7.gigabytes() + 250.megabytes());
40//! ```
41//!
42//! # Overview
43//!
44//! * [`ByteUnit`] constructors -- [`ByteUnit::Byte`] and friends -- for all SI
45//! units of bytes up to the exbibyte are provided; all constructors are `const`
46//! and saturating. Associated constants -- [`ByteUnit::B`] and friends -- for
47//! `1`-valued units are provided. Saturating arithmetic operations between
48//! `ByteUnit` and all integers types are implemented. `From<{integer}> for
49//! ByteUnit` for all integer types is implemented. `From<ByteUnit> for {u64,
50//! u128}>` is implemented.
51//!
52//! * [`ToByteUnit`] provides human-friendly methods on all integer types for
53//! converting into a `ByteUnit`: [`512.kilobytes()`](ToByteUnit::kilobytes).
54//!
55//! * The [`Display`](struct.ByteUnit.html#impl-Display) implementation displays
56//! `ByteUnit`s in a human-friendly format. For truly custom printing,
57//! [`ByteUnit::repr()`] splits a value into its minimal components.
58//!
59//! * The [`FromStr`](struct.ByteUnit.html#impl-FromStr) implementation parses
60//! byte units in a case-free manner: `1B` or `1b` or `1 b` => `1.bytes()`.
61//!
62//! * With the `serde` feaure enabled (disabled by default), `ByteUnit`
63//! implements [`Deserialize`](struct.ByteUnit.html#impl-Deserialize<%27de>)
64//! from strings and all integer types as well as
65//! [`Serialize`](struct.ByteUnit.html#impl-Serialize) into a `u64`.
66//!
67//! * All operations -- constructors, arithmetic -- saturate. Overflow,
68//! underflow, divide-by-zero, and mod-by-zero are impossible.
69
70mod arithmetic;
71mod byte_unit;
72mod parse;
73#[cfg(feature = "serde")]
74mod ser_de;
75
76pub use byte_unit::{ByteUnit, ToByteUnit};
77pub use parse::Error;
ubyte/lib.rs

ubyte/
lib.rs
