# wdxtools
[](https://crates.io/crates/wdxtools)
[](https://docs.rs/wdxtools)
[](https://github.com/wilmanbarrios/wdxtools/actions/workflows/ci.yml)
[](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
## Utilities
| [`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
```
Run `wdxtools numcrn --help` for all flags.
### Original vs wdxtools
| `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** |
| 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
# Batch mode with templates (-f)
printf '%s\n' ts1 ts2 | wdxtools diffh # one line per input
```
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
| `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** |
| 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.
| 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
| `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).