wdxtools 0.4.2

Everyday formatting tools for the command line
Documentation

wdxtools

crates.io docs.rs CI License: MIT

Everyday formatting tools for the command line. Lightning-fast Rust ports of popular library functions.

Install

brew install wilmanbarrios/tap/wdxtools
# or
cargo install wdxtools
# or grab a binary from the releases page
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/wilmanbarrios/wdxtools/releases/latest/download/wdxtools-installer.sh | sh

Utilities

Command Description Ported from
wdxtools numcrn Abbreviate numbers for humans Laravel Number::abbreviate()
wdxtools diffh Human-readable time differences Carbon diffForHumans()

numcrn

Abbreviate numbers for humans. Port of Laravel's Number::abbreviate() with 100% feature parity.

Examples

wdxtools numcrn 489939              # 490K
wdxtools numcrn -m 2 489939         # 489.94K
wdxtools numcrn -p 2 1000000        # 1.00M
wdxtools numcrn -l 1000000          # 1 million
wdxtools numcrn -1000               # -1K
echo -1000 | wdxtools numcrn        # -1K
wdxtools numcrn 1000000000000000000 # 1KQ

Run wdxtools numcrn --help for all flags.

Original vs wdxtools

Laravel (PHP 8.3) wdxtools (Rust) Speedup
Abbreviate(489939) 7,037 ns/op 20.6 ns/op 342x
Abbreviate(1e18) 4,089 ns/op 17.5 ns/op 234x
ForHumans(489939) 6,942 ns/op 20.2 ns/op 343x
Abbreviate(42) 3,903 ns/op 13.2 ns/op 297x
Abbreviate(-489939) 7,503 ns/op 20.6 ns/op 365x
Original (PHP) wdxtools (Rust)
Runtime PHP 8.x + Laravel Native binary
Install composer require laravel/framework brew install / single binary
Dependencies Laravel + intl extension None at runtime
Pipe support No Yes (echo 1000 | wdxtools numcrn)

diffh

Human-readable time differences. Port of Carbon's diffForHumans() with 100% feature parity.

Examples

wdxtools diffh 2024-01-15                   # 1 year ago
wdxtools diffh -s 2024-01-15                # 1y ago
wdxtools diffh -p 3 2024-01-15              # 1 year, 2 months, and 14 days ago
wdxtools diffh -s -p 3 2024-01-15           # 1y 2mo 14d ago
wdxtools diffh -a 2024-01-15 2025-01-15     # 1 year
wdxtools diffh 1774820647                   # unix timestamp
echo 2024-01-15 | wdxtools diffh            # 1 year ago

# Batch mode with templates (-f)
printf '%s\n' ts1 ts2 | wdxtools diffh              # one line per input
cat log.csv | wdxtools diffh -f '$2 ($d)'           # $1..$N=fields, $d=diff
cat events.tsv | wdxtools diffh -f '$1\t$2\t$d'     # tab-separated output

Accepted inputs: unix timestamps, 2006-01-02, 2006-01-02T15:04:05, 2006-01-02 15:04:05 and RFC 3339. Values without an offset are read as local wall time; values carrying one are absolute instants. Calendar arithmetic runs in a single zone, so DST transitions don't turn a day into 23 hours.

Run wdxtools diffh --help for all flags.

Original vs wdxtools

Carbon (PHP 8.3) wdxtools (Rust) Speedup
diffForHumans() 27,350 ns/op 27.6 ns/op 990x
diffForHumans(parts: 3) 33,322 ns/op 43.8 ns/op 761x
diffForHumans(short) 28,298 ns/op 28.4 ns/op 995x
Original (PHP) wdxtools (Rust)
Runtime PHP 8.x + Carbon Native binary
Install composer require nesbot/carbon brew install / single binary
Dependencies Carbon + intl extension None at runtime
Unix timestamps No Yes (wdxtools diffh 1774820647)
Pipe support No Yes (echo date | wdxtools diffh)

Backward compatibility

Releases ship diffh and numcrn alongside wdxtools, so diffh 2024-01-15 and numcrn 1000 keep working as standalone commands.

Versions up to v0.3.4 were written in Go. The CLI surface is unchanged — a differential suite of 1,531 invocations covering every flag combination, input format, template and symlink confirmed byte-identical output between the two implementations. Two error paths differ on purpose:

  • Negative positional arguments (numcrn -1000, diffh -86400) used to be rejected by the flag parser and now work.
  • Error messages are uniformly <command>: <message>; the Go build prefixed some of them with Error:.

Benchmark methodology

All benchmarks run inside Docker containers on the same host. No emulation — both containers run natively on arm64.

PHP container Rust container
Base image php:8.3-cli-alpine rust:1.90-slim-bookworm
Runtime PHP 8.3 (NTS) Rust 1.90
Optimization OPcache + JIT (tracing mode) opt-level=3, fat LTO, codegen-units=1
Harness manual loop criterion (100 samples)
Architecture linux/arm64 (native) linux/arm64 (native)

Host: Apple M2, 8 cores, 16 GB RAM, Docker Desktop.

PHP runs in its best performance mode: OPcache enabled and JIT in tracing mode.

Reproduce locally: make bench (Rust) and make bench-php (PHP).


Build from source

All builds run via Docker — no Rust toolchain required on host.

make build        # builds binary to ./bin/wdxtools
make test         # runs all tests
make lint         # clippy
make fmt          # rustfmt check
make bench        # runs benchmarks

With a local toolchain, the usual cargo build --release / cargo test work too.

Use as a library

[dependencies]
wdxtools = "0.4"

Both utilities are available as plain functions. Each module has its own Config builder, so qualify them by module rather than importing both names:

use wdxtools::{number, timediff};

// Laravel Number::abbreviate()
assert_eq!(number::abbreviate(1000.0, number::Config::new()), "1K");
assert_eq!(
    number::abbreviate(489939.0, number::Config::new().max_precision(2)),
    "489.94K",
);

// Carbon diffForHumans()
let cfg = timediff::Config::new().short(true).parts(3);
let s = timediff::diff_for_humans(&from, &now, cfg); // "1y 2mo 14d ago"

timediff takes jiff::Zoned values. The jiff this crate links is re-exported as wdxtools::jiff, so you get the matching version without declaring it yourself:

use wdxtools::jiff::Zoned;

let from: Zoned = "2024-01-15T00:00:00[UTC]".parse()?;
let now = Zoned::now();

Hot loops

Both modules expose allocation-free append_* variants that write into a buffer you own:

let mut buf = String::new();
number::append_abbreviate(&mut buf, 489939.0, number::Config::new());

For repeated formatting against a fixed reference instant, timediff::Formatter captures the reference once at construction:

let fmt = timediff::Formatter::new(Zoned::now(), timediff::Config::new());
for ts in timestamps {
    println!("{}", fmt.format(&ts));
}

Credits

Tool Original Author License
numcrn Number::abbreviate() Taylor Otwell (Laravel) MIT
diffh diffForHumans() Brian Nesbitt (Carbon) MIT

Time zone handling and the tzdb come from jiff.

License

MIT — see LICENSE.