From 2bdd45f603299b47d3157773a4836bf71bfacc6e Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Mon, 10 Feb 2025 00:11:21 +0000 Subject: [PATCH] docs: use cargo-rdme to match readme to tested docs (#68) --- .prettierrc.yml | 5 +++ README.md | 106 +++++++++++++----------------------------------- justfile | 6 +++ src/lib.rs | 41 ++++++++++++------- 4 files changed, 67 insertions(+), 91 deletions(-) create mode 100644 .prettierrc.yml diff --git a/.prettierrc.yml b/.prettierrc.yml new file mode 100644 index 0000000..8cce8dd --- /dev/null +++ b/.prettierrc.yml @@ -0,0 +1,5 @@ +overrides: + - files: '*.md' + options: + proseWrap: never + printWidth: 9999 diff --git a/README.md b/README.md index a8e9fc0..2f457de 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,53 @@ ## ByteSize -[![CI](https://github.com/hyunsik/bytesize/actions/workflows/ci.yml/badge.svg)](https://github.com/hyunsik/bytesize/actions/workflows/ci.yml) + + +[![CI](https://github.com/bytesize-rs/bytesize/actions/workflows/ci.yml/badge.svg)](https://github.com/bytesize-rs/bytesize/actions/workflows/ci.yml) [![Crates.io Version](https://img.shields.io/crates/v/bytesize.svg)](https://crates.io/crates/bytesize) -`ByteSize` is a utility for human-readable byte count representations. + + + + +`ByteSize` is a semantic wrapper for byte count representations. Features: - Pre-defined constants for various size units (e.g., B, Kb, Kib, Mb, Mib, Gb, Gib, ... PB). - `ByteSize` type which presents size units convertible to different size units. - Arithmetic operations for `ByteSize`. -- FromStr impl for `ByteSize`, allowing to parse from string size representations like 1.5KiB and 521TiB. +- `FromStr` impl for `ByteSize`, allowing for parsing string size representations like "1.5KiB" and "521TiB". - Serde support for binary and human-readable deserializers like JSON. -[API Documentation](https://docs.rs/bytesize) +### Examples -## Examples - -### Human readable representations (SI unit and Binary unit) +Construction using SI or IEC helpers. ```rust -fn assert_display(expected: &str, b: ByteSize) { - assert_eq!(expected, format!("{}", b)); -} - -#[test] -fn test_display() { - assert_display("215 B", ByteSize::b(215)); - assert_display("1.0 KiB", ByteSize::kib(1)); - assert_display("301.0 KiB", ByteSize::kib(301)); - assert_display("419.0 MiB", ByteSize::mib(419)); - assert_display("518.0 GiB", ByteSize::gib(518)); - assert_display("815.0 TiB", ByteSize::tib(815)); - assert_display("609.0 PiB", ByteSize::pib(609)); -} - -#[test] -fn test_display_alignment() { - assert_eq!("|357 B |", format!("|{:10}|", ByteSize(357))); - assert_eq!("| 357 B|", format!("|{:>10}|", ByteSize(357))); - assert_eq!("|357 B |", format!("|{:<10}|", ByteSize(357))); - assert_eq!("| 357 B |", format!("|{:^10}|", ByteSize(357))); - - assert_eq!("|-----357 B|", format!("|{:->10}|", ByteSize(357))); - assert_eq!("|357 B-----|", format!("|{:-<10}|", ByteSize(357))); - assert_eq!("|--357 B---|", format!("|{:-^10}|", ByteSize(357))); -} - -fn assert_to_string(expected: &str, b: ByteSize, si: bool) { - assert_eq!(expected.to_string(), b.to_string_as(si)); -} - -#[test] -fn test_to_string_as() { - assert_to_string("215 B", ByteSize::b(215), true); - assert_to_string("215 B", ByteSize::b(215), false); - - assert_to_string("1.0 KiB", ByteSize::kib(1), true); - assert_to_string("1.0 KB", ByteSize::kib(1), false); - - assert_to_string("293.9 KiB", ByteSize::kb(301), true); - assert_to_string("301.0 KB", ByteSize::kb(301), false); - - assert_to_string("1.0 MiB", ByteSize::mib(1), true); - assert_to_string("1048.6 KB", ByteSize::mib(1), false); - - // a bug case: https://github.com/flang-project/bytesize/issues/8 - assert_to_string("1.9 GiB", ByteSize::mib(1907), true); - assert_to_string("2.0 GB", ByteSize::mib(1908), false); - - assert_to_string("399.6 MiB", ByteSize::mb(419), true); - assert_to_string("419.0 MB", ByteSize::mb(419), false); - - assert_to_string("482.4 GiB", ByteSize::gb(518), true); - assert_to_string("518.0 GB", ByteSize::gb(518), false); - - assert_to_string("741.2 TiB", ByteSize::tb(815), true); - assert_to_string("815.0 TB", ByteSize::tb(815), false); - - assert_to_string("540.9 PiB", ByteSize::pb(609), true); - assert_to_string("609.0 PB", ByteSize::pb(609), false); -} +use bytesize::ByteSize; + +assert!(ByteSize::kib(4) > ByteSize::kb(4)); ``` -### Arithmetic Operations +Display as human-readable string. ```rust use bytesize::ByteSize; -fn byte_arithmetic_operator() { - let x = ByteSize::mb(1); - let y = ByteSize::kb(100); +assert_eq!("482.4 GiB", ByteSize::gb(518).to_string_as(true)); +assert_eq!("518.0 GB", ByteSize::gb(518).to_string_as(false)); +``` + +Arithmetic operations are supported. + +```rust +use bytesize::ByteSize; - let plus = x + y; - print!("{}", plus); +let plus = ByteSize::mb(1) + ByteSize::kb(100); +println!("{plus}"); - let minus = ByteSize::tb(100) + ByteSize::gb(4); - print!("{}", minus); -} +let minus = ByteSize::tb(1) - ByteSize::gb(4); +assert_eq!(ByteSize::gb(996), minus); ``` + + diff --git a/justfile b/justfile index 8fec6df..709d3e2 100644 --- a/justfile +++ b/justfile @@ -25,6 +25,12 @@ fmt: # fd --hidden --type=file -e=md -e=yml --exec-batch prettier --write cargo +nightly fmt +# Update READMEs from crate root documentation. +[group("lint")] +update-readme: + cargo rdme --force + npx -y prettier --write README.md + # Lint workspace with Clippy. [group("lint")] clippy: diff --git a/src/lib.rs b/src/lib.rs index 4395007..3ab3483 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,24 +1,25 @@ -//! ByteSize is an utility that easily makes bytes size representation -//! and helps its arithmetic operations. +//! `ByteSize` is a semantic wrapper for byte count representations. //! -//! ## Example +//! Features: //! -//! ```ignore -//! use bytesize::ByteSize; +//! - Pre-defined constants for various size units (e.g., B, Kb, Kib, Mb, Mib, Gb, Gib, ... PB). +//! - `ByteSize` type which presents size units convertible to different size units. +//! - Arithmetic operations for `ByteSize`. +//! - `FromStr` impl for `ByteSize`, allowing for parsing string size representations like "1.5KiB" +//! and "521TiB". +//! - Serde support for binary and human-readable deserializers like JSON. +//! +//! # Examples //! -//! fn byte_arithmetic_operator() { -//! let x = ByteSize::mb(1); -//! let y = ByteSize::kb(100); +//! Construction using SI or IEC helpers. //! -//! let plus = x + y; -//! print!("{} bytes", plus.as_u64()); +//! ``` +//! use bytesize::ByteSize; //! -//! let minus = ByteSize::tb(100) - ByteSize::gb(4); -//! print!("{} bytes", minus.as_u64()); -//! } +//! assert!(ByteSize::kib(4) > ByteSize::kb(4)); //! ``` //! -//! It also provides its human readable string as follows: +//! Display as human-readable string. //! //! ``` //! use bytesize::ByteSize; @@ -26,6 +27,18 @@ //! assert_eq!("482.4 GiB", ByteSize::gb(518).to_string_as(true)); //! assert_eq!("518.0 GB", ByteSize::gb(518).to_string_as(false)); //! ``` +//! +//! Arithmetic operations are supported. +//! +//! ``` +//! use bytesize::ByteSize; +//! +//! let plus = ByteSize::mb(1) + ByteSize::kb(100); +//! println!("{plus}"); +//! +//! let minus = ByteSize::tb(1) - ByteSize::gb(4); +//! assert_eq!(ByteSize::gb(996), minus); +//! ``` mod parse; #[cfg(feature = "serde")]