Merge branch 'master' into rm-arb-derive

Author: robjtede

.prettierrc.yml

@@ -0,0 +1,5 @@
+overrides:
+  - files: '*.md'
+    options:
+      proseWrap: never
+      printWidth: 9999

CHANGELOG.md

@@ -2,9 +2,10 @@
 
 ## Unreleased
 
-- Use SI format by default with `Display`.
-- Use "KiB" for SI unit.
+- Use IEC (binary) format by default with `Display`.
+- Use "kB" for SI unit.
 - Implement `Sub<ByteSize>` for `ByteSize`.
 - Implement `Sub<impl Into<u64>>` for `ByteSize`.
 - Implement `SubAssign<ByteSize>` for `ByteSize`.
 - Implement `SubAssign<impl Into<u64>>` for `ByteSize`.
+- Reject parsing non-unit characters after whitespace.

Cargo.toml

@@ -2,7 +2,11 @@
 name = "bytesize"
 description = "A utility for human-readable byte count representations"
 version = "1.3.0"
-authors = ["Hyunsik Choi <[email protected]>", "MrCroxx <[email protected]>"]
+authors = [
+    "Hyunsik Choi <[email protected]>",
+    "MrCroxx <[email protected]>",
+    "Rob Ede <[email protected]>",
+]
 keywords = ["byte", "byte-size", "utility", "human-readable", "format"]
 categories = ["development-tools", "filesystem"]
 repository = "https://github.com/bytesize-rs/bytesize"

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)
+<!-- prettier-ignore-start -->
+
+[![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.
+<!-- prettier-ignore-end -->
+
+<!-- cargo-rdme start -->
+
+`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);
 ```
+
+<!-- cargo-rdme end -->

codecov.yml

@@ -0,0 +1,16 @@
+comment: false
+
+coverage:
+  status:
+    project:
+      default:
+        threshold: 100% # make CI green
+    patch:
+      default:
+        threshold: 100% # make CI green
+
+# ignore code coverage on following paths
+ignore:
+  - "**/tests"
+  - "**/benches"
+  - "**/examples"

examples/ls.rs

@@ -0,0 +1,27 @@
+//! Emulates running `ls -la` in the terminal, showing human-readable file sizes and file names.
+
+use std::{fs, io};
+
+fn main() -> io::Result<()> {
+    let dir = fs::read_dir(".")?;
+
+    for entry in dir {
+        let entry = entry?;
+
+        let md = entry.metadata()?;
+
+        let file_name = entry.file_name();
+        let file_name = file_name.to_string_lossy();
+
+        if md.is_file() {
+            let file_size = md.len();
+            let file_size = bytesize::ByteSize::b(file_size);
+
+            println!("{file_size}\t{file_name}");
+        } else {
+            println!("-\t{file_name}");
+        }
+    }
+
+    Ok(())
+}

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: