.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_metric" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_metric - fixed-width numeric output with metric suffixes
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[C]
#define PREFIXCOLUMNS 7
#define IPREFIXCOLUMNS 8
#define BPREFIXCOLUMNS 9
#define PREFIXSTRLEN (PREFIXCOLUMNS + 1)
#define IPREFIXSTRLEN (IPREFIXCOLUMNS + 1)
#define BPREFIXSTRLEN (BPREFIXCOLUMNS + 1)
#define NCMETRICFWIDTH(x, cols) ((int)(strlen(x) - ncstrwidth(x) + (cols)))
#define PREFIXFMT(x) NCMETRICFWIDTH((x), PREFIXCOLUMNS), (x)
#define IPREFIXFMT(x) NCMETRIXFWIDTH((x), IPREFIXCOLUMNS), (x)
#define BPREFIXFMT(x) NCMETRICFWIDTH((x), BPREFIXCOLUMNS), (x)
\f[R]
.fi
.PP
\f[B]const char* ncmetric(uintmax_t \f[R]\f[I]val\f[R]\f[B], uintmax_t
\f[R]\f[I]decimal\f[R]\f[B], char* \f[R]\f[I]buf\f[R]\f[B], int
\f[R]\f[I]omitdec\f[R]\f[B], unsigned \f[R]\f[I]mult\f[R]\f[B], int
\f[R]\f[I]uprefix\f[R]\f[B]);\f[R]
.PP
\f[B]static inline const char* qprefix(uintmax_t
\f[R]\f[I]val\f[R]\f[B], uintmax_t \f[R]\f[I]decimal\f[R]\f[B], char*
\f[R]\f[I]buf\f[R]\f[B], int \f[R]\f[I]omitdec\f[R]\f[B]);\f[R]
.PP
\f[B]static inline const char* bprefix(uintmax_t
\f[R]\f[I]val\f[R]\f[B], uintmax_t \f[R]\f[I]decimal\f[R]\f[B], char*
\f[R]\f[I]buf\f[R]\f[B], int \f[R]\f[I]omitdec\f[R]\f[B]);\f[R]
.SH DESCRIPTION
.PP
\f[B]ncmetric\f[R] (and the helper wrappers \f[B]qprefix\f[R] and
\f[B]bprefix\f[R]) accept very large (or very small) non-negative
numbers, and prepare formatted output of a maximum width using metric
suffixes.
The suffix can represent arbitrary amounts of growth, but is designed
for 1000 (\f[B]PREFIX\f[R]) or 1024 (\f[B]IPREFIX\f[R]).
1024 is used for \[lq]digital units of information\[rq], i.e.\ kibibytes
and gibibits.
\f[B]ncmetric\f[R] supports the large suffixes KMGTPEZY (Kilo, Mega,
Giga, Tera, Peta, Exa, Zetta, and Yotta) and the small suffixes
m\[mc]npfazy (Milli, Micro, Nano, Pico, Femto, Atto, Zepto, and Yocto).
This covers the range 10\[ha]-24 through 10\[ha]24.
As \f[B]uintmax_t\f[R] is typically only 64 bits, this covers the
entirety of its range.
.PP
\f[B]val\f[R] is the value being output, having been scaled by
\f[B]decimal\f[R].
\f[B]decimal\f[R] will typically be 1; to represent values less than 1,
\f[B]decimal\f[R] should be larger than \f[B]val\f[R].
The output will be written to \f[B]buf\f[R], which must be at least:
.IP \[bu] 2
\f[B]PREFIXSTRLEN\f[R] + 1 bytes for a 1000-based value
.IP \[bu] 2
\f[B]IPREFIXSTRLEN\f[R] + 1 bytes for a 1024-based value
.IP \[bu] 2
\f[B]BPREFIXSTRLEN\f[R] + 1 bytes for a 1024-based value with an `i'
suffix
.PP
If \f[B]omitdec\f[R] is not zero, the decimal point and mantissa will be
omitted if all digits to be displayed would be zero.
The decimal point takes the current locale into account (see
\f[B]setlocale(3)\f[R] and \f[B]localeconv(3)\f[R]).
\f[B]mult\f[R] is the relative multiple for each suffix.
\f[B]uprefix\f[R], if not zero, will be used as a suffix following any
metric suffix.
.PP
In general, the maximum-width output will take the form:
.PP
CCC.mmMu
.PP
Where C are digits of the characteristic (up to
ceil(log10(\f[B]mult\f[R])) digits), the decimal point follows, m are
digits of the mantissa (up to 2), M is the metric suffix, and u is the
\f[B]uprefix\f[R].
The minimum-width output will take the form:
.PP
C
.PP
This can occur if \f[B]omitdec\f[R] is non-zero and a value such as 5 is
passed for \f[B]val\f[R].
.SH RETURN VALUES
.PP
\f[B]NULL\f[R] if input parameters were invalid.
Otherwise, a pointer to \f[B]buf\f[R], filled in with the formatted
output.
.SH SEE ALSO
.PP
\f[B]localeconv(3)\f[R], \f[B]notcurses(3)\f[R],
\f[B]notcurses_plane(3)\f[R], \f[B]setlocale(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.