wdxtools 0.4.2

Everyday formatting tools for the command line
Documentation
# wdxtools

[![crates.io](https://img.shields.io/crates/v/wdxtools.svg)](https://crates.io/crates/wdxtools)
[![docs.rs](https://docs.rs/wdxtools/badge.svg)](https://docs.rs/wdxtools)
[![CI](https://github.com/wilmanbarrios/wdxtools/actions/workflows/ci.yml/badge.svg)](https://github.com/wilmanbarrios/wdxtools/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## Install

```bash
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`]#numcrn | Abbreviate numbers for humans | Laravel `Number::abbreviate()` |
| [`wdxtools diffh`]#diffh | Human-readable time differences | Carbon `diffForHumans()` |

---

## numcrn

Abbreviate numbers for humans. Port of [Laravel's `Number::abbreviate()`](https://github.com/laravel/framework/blob/12.x/src/Illuminate/Support/Number.php) with 100% feature parity.

### Examples

```bash
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()`](https://github.com/briannesbitt/Carbon/blob/master/src/Carbon/Traits/Difference.php) with 100% feature parity.

### Examples

```bash
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.

```bash
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

```toml
[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:

```rust
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:

```rust
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:

```rust
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:

```rust
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()`]https://github.com/laravel/framework/blob/12.x/src/Illuminate/Support/Number.php | [Taylor Otwell]https://github.com/taylorotwell (Laravel) | MIT |
| `diffh` | [`diffForHumans()`]https://github.com/briannesbitt/Carbon/blob/master/src/Carbon/Traits/Difference.php | [Brian Nesbitt]https://github.com/briannesbitt (Carbon) | MIT |

Time zone handling and the tzdb come from [`jiff`](https://github.com/BurntSushi/jiff).

## License

MIT — see [LICENSE](LICENSE).