feat(format): expand pow_format modifiers

Extend the pow_format spec parser beyond alignment so configs can shape the
rendered number, not just pad it. A forced scale (#, k, M, G, T, P) pins the SI
prefix instead of auto-selecting it and, since the author then knows both scale
and unit, hides the prefix and unit by default; U brings the unit back, u hides
it in auto mode, and i forces integer display. b and B override the decimal or
binary base independently of the call site, and a trailing width now fixes the
coefficient field when a scale is forced, overflowing to '#' when it does not
fit.

The old '>' and '<' branches rendered via fmt::format("{}", s), which discarded
every new field on the recursive call; they now build from a single render path
that reads the current formatter, so modifiers survive alignment. The auto path
is byte-identical to before, verified against the previous implementation.

Adds a Catch2 suite covering each modifier alone and combined, plus the
backward-compatible alignment cases, and documents the modifiers in the network
and disk man pages.
This commit is contained in:
Guillaume Maudoux
2026-07-04 23:08:42 +02:00
parent 2d9b95e9de
commit a3dc55f9ee
5 changed files with 273 additions and 44 deletions
+23
View File
@@ -146,6 +146,29 @@ Addressed by *disk*
*{specific_free}*: Amount of available disk space for normal users in a specific unit. Defaults to bytes.
# NUMBER FORMAT MODIFIERS
*{total}*, *{used}* and *{free}* auto-scale with a binary prefix (KiB, GiB, …).
Their rendering can be tuned with fmt-style modifiers, e.g. *"{free:>}"* or
*"{free:G}"*, combined in any order:
*<*, *=*, *>*: Alignment/padding (left, column-align, right).
*u* / *U*: Hide (*u*) or show (*U*) the unit suffix. Shown by default with an auto
scale, hidden by default when a scale is forced.
*#*, *k*, *M*, *G*, *T*, *P*: Force a fixed scale instead of auto-selecting
(*#* = base scale). Forcing a scale hides the scale prefix and, by default, the
unit. E.g. *"{free:G}"* always shows gibibytes.
*i*: Force integer display (no decimals).
*b* / *B*: Force decimal base 1000 (*b*) or binary base 1024 (*B*); disk values
are binary by default.
A trailing number is a fixed width for the coefficient when a scale is forced;
overflow is shown as *#* characters (e.g. *"{free:=3#}"**###*).
# EXAMPLES
```