humfmt 0.1.1

Ergonomic human-readable number formatting for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

<div align="center">

# humfmt


**Ergonomic human-readable formatting toolkit for Rust**

[![CI](https://github.com/MuXolotl/humfmt/actions/workflows/ci.yml/badge.svg)](https://github.com/MuXolotl/humfmt/actions/workflows/ci.yml)
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Status](https://img.shields.io/badge/status-actively--developing-brightgreen.svg)

</div>

---

`humfmt` is a lightweight Rust library for turning raw machine values into human-friendly text.

Designed to provide:

- compact number rendering (`15320 -> 15.3K`)
- fluent builder-style customization
- locale-ready suffix formatting
- ergonomic extension trait API
- `no_std`-friendly usage with `alloc`
- zero-macro, zero-nonsense usage

The crate aims to be tiny, intuitive, and pleasant enough that formatting stops feeling like work.

---

## ✨ Quick Example


```rust
use humfmt::Humanize;

fn main() {
    println!("{}", humfmt::number(15320));          // 15.3K
    println!("{}", 1_500_000.human_number());      // 1.5M
}
```

---

## ⚙️ Customized Formatting


```rust
use humfmt::{Humanize, NumberOptions};

fn main() {
    let out = 15_320.human_number_with(
        NumberOptions::new()
            .precision(2)
            .long_units()
    );

    println!("{out}"); // 15.32 thousand
}
```

---

## ✅ Current Features


* [x] Compact number formatter
* [x] Builder-style `NumberOptions`
* [x] `Humanize` extension trait
* [x] Long and short suffix units
* [x] Locale abstraction foundation
* [x] Doctests and integration tests

---

## 🗺️ Planned Roadmap


Upcoming humanizers planned for future releases:

* [ ] `bytes()` — human-readable byte sizes
* [ ] `duration()` — compact duration formatting
* [ ] `ago()` — relative time rendering
* [ ] `ordinal()` — 1st / 2nd / 3rd style helpers
* [ ] additional locale packs
* [ ] zero-allocation optimization pass

---

## 📦 Installation


Add dependency:

```toml
[dependencies]
humfmt = "0.1"
```

For `no_std` targets with `alloc` available:

```toml
[dependencies]
humfmt = { version = "0.1", default-features = false }
```

---

## Feature Flags


- `std` (default): enables the standard-library build.
- `default-features = false`: builds the current formatter on `no_std` + `alloc`.
- `english` stays in the default set for forward-compatible locale gating in `0.1.x`.
- `alloc`, `russian`, and `polish` are reserved compatibility flags in `0.1.x`; they do not change runtime behavior yet.
- `chrono` and `time` keep their optional dependencies wired and CI-checked, but no public integration API is exposed yet.

---

## 🧪 Development Status


`humfmt` is under active early-stage development.

The current public surface is intentionally small and focused on compact number formatting first.

Expect rapid iteration, formatter additions, and locale improvements.

---

## 📚 Documentation


* examples available in `/examples`
* integration tests available in `/tests`
* rustdoc examples available on all public number APIs
* published crate: <https://crates.io/crates/humfmt>
* API docs: <https://docs.rs/humfmt>

---

## 📄 License


Licensed under MIT.

---

## ⭐ Philosophy


This crate follows one simple rule:

> Human formatting should feel stupidly easy.

No giant config structs.
No formatting gymnastics.
No "why is this so annoying?" moments.

Just:

```rust
println!("{}", 1500000.human_number());
```

and move on with your life.