HUMANIZE_NUMBER

Section: Misc. Reference Manual Pages (3bsd)
Page Index

BSD mandoc

NAME

dehumanize_number humanize_number - format a number into a human readable form and viceversa

LIBRARY

Lb libbsd

SYNOPSIS

In stdlib.h (See libbsd(7) for include usage.) Ft int Fn dehumanize_number const char *str int64_t *result Ft int Fn humanize_number char *buf size_t len int64_t number const char *suffix int scale int flags

DESCRIPTION

The Fn humanize_number function formats the signed 64 bit quantity given in Fa number into Fa buffer . A space and then Fa suffix is appended to the end. Fa buffer must be at least Fa len bytes long.

If the formatted number (including Fa suffix ) would be too long to fit into Fa buffer , then divide Fa number by 1024 until it will. In this case, prefix Fa suffix with the appropriate SI designator.

The prefixes are:

Prefix Ta Description Ta Multiplier
k kilo 1024
M mega 1048576
G giga1073741824
Ttera1099511627776
Ppeta1125899906842624
Eexa1152921504606846976

Fa len must be at least 4 plus the length of
Fa suffix , in order to ensure a useful result is generated into Fa buffer . To use a specific prefix, specify this as Fa scale (Multiplier = 1024 ^ scale). This can not be combined with any of the Fa scale flags below.

The following flags may be passed in scale

HN_AUTOSCALE: Format the buffer using the lowest multiplier possible.
HN_GETSCALE: Return the prefix index number (the number of times Fa number must be divided to fit) instead of formatting it to the buffer.

The following flags may be passed 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 Fa number and the prefix.
HN_B: Use 'B' (bytes) as prefix if the original result does not have a prefix.
HN_DIVISOR_1000: Divide Fa number with 1000 instead of 1024.

The Fn dehumanize_number function parses the string representing an integral value given in Fa str and stores the numerical value in the integer pointed to by Fa result . The provided string may hold one of the suffixes, which will be interpreted and used to scale up its accompanying numerical value.

RETURN VALUES

Fn humanize_number returns the number of characters stored in Fa buffer (excluding the terminating NUL) upon success, or -1 upon failure. If HN_GETSCALE is specified, the prefix index number will be returned instead.

Fn 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

Fn dehumanize_number will fail and no number will be stored in Fa result if:

Bq Er EINVAL: The string in Fa str was empty or carried an unknown suffix.
Bq Er ERANGE: The string in Fa str represented a number that does not fit in Fa result .

HISTORY

Fn humanize_number first appeared in Nx 2.0 .

Fn dehumanize_number first appeared in Nx 5.0 .