humanize_number(3bsd)

💖 dehumanize_number, humanize_number — bestie edition 💖

okay so. we're in humanize_number(3bsd) territory, and honestly? this page is SO useful and nobody talks about it. it's the libbsd version, aka Utility functions from BSD systems — you link it with -lbsd and it's lowkey iconic. one function turns a big scary number into something cute and readable, the other one does the reverse. glow up and glow down. 💅

---

✨ NAME ✨

dehumanize_number, humanize_number — format a number into a human readable form and viceversa 🦋

---

📚 LIBRARY 📚

Utility functions from BSD systems (libbsd, -lbsd) 🌸

---

🎀 SYNOPSIS 🎀

#include <stdlib.h>
(See libbsd(7) for include usage.)

int
dehumanize_number(const char *str, int64_t *result);

int
humanize_number(char *buf, size_t len, int64_t number,
    const char *suffix, int scale, int flags);

not me writing #include <stdlib.h> and then immediately being told to go read libbsd(7) for the actual include tea 😭 do it though. it matters.

---

🌈 DESCRIPTION 🌈

okay bestie, deep breath, two functions, both slay.

🫶 humanize_number() — the glow-up direction

humanize_number() takes that signed 64 bit quantity sitting in number and formats it into buffer. then it appends a space and then suffix at the end. so like, "5 GB" energy. your buffer has to be at least len bytes long, no negotiating.

now here's the ✨magic✨ — if the formatted number (suffix included, bestie, the whole fit) would be too long to fit into buffer, it just keeps dividing number by 1024 until it fits. and when it does that, it prefixes suffix with the appropriate SI designator. the way that just works?? obsessed.

the prefixes, in all their glory:

• k — kilo — multiplier 1024
• M — mega — multiplier 1048576
• G — giga — multiplier 1073741824
• T — tera — multiplier 1099511627776
• P — peta — multiplier 1125899906842624
• E — exa — multiplier 1152921504606846976

len must be at least 4 plus the length of suffix, because otherwise the result isn't gonna be useful and we'd simply perish. to force a specific prefix, pass it as scale, where Multiplier = 1024 ^ scale. 🔥

⚠️ you can NOT combine that with any of the scale flags below. pick a lane, bestie.

👑 the flags you can pass in scale

• HN_AUTOSCALE — format the buffer using the lowest multiplier possible. it picks for you. main character behavior.
• HN_GETSCALE — return the prefix index number (aka the number of times number must be divided to fit) instead of formatting it to the buffer. yes, instead. no buffer content for you.

💅 the flags you can pass in flags

• HN_DECIMAL — if the final result is less than 10, display it using one digit.
• HN_NOSPACE — do not put a space between the number and the prefix. snatch that space away.
• HN_B — use 'B' (bytes) as the prefix if the original result does not have a prefix.
• HN_DIVISOR_1000 — divide number with 1000 instead of 1024. metric girlies rise.

🦋 dehumanize_number() — the glow-down direction

dehumanize_number() parses the string representing an integral value that you hand it in str and stores the numerical value in the integer pointed to by result. and here's the cute part: the string you give it may hold one of those suffixes, which will be interpreted and used to scale up the numerical value riding along with it. it reads the vibe AND the number. fr fr.

---

⭐ RETURN VALUES ⭐

• humanize_number() returns the number of characters stored in buffer (excluding the terminating NUL) upon success, or -1 upon failure. and if HN_GETSCALE is specified, the prefix index number will be returned instead. 🌸
• dehumanize_number() returns 0 if the string was parsed correctly. a -1 is returned to indicate failure and an error code is stored in errno. 💀

---

🚨 ERRORS 🚨

dehumanize_number() will fail and no number will be stored in result if:

• [EINVAL] — the string in str was empty or carried an unknown suffix. bestie what even is that suffix.
• [ERANGE] — the string in str represented a number that does not fit in result. too much. overflowing. not the vibe.

---

👀 SEE ALSO 👀

humanize_number(9) — go read it, iykyk 🫶

---

📜 HISTORY 📜

• humanize_number() first appeared in NetBSD 2.0 and FreeBSD 5.3. ✨
• dehumanize_number() first appeared in NetBSD 5.0. 🌈

---

okay that's the whole page, you ate it, no crumbs. 🍓

this one came out of Debian, dated February 9, 2008, and lives under the name humanize_number(3bsd) — periodt. 💖✨🎀