.\" Automatically generated by Pandoc 3.1.8
.\"
.TH "notcurses_metric" "3" "v3.0.9" "" ""
.SH NAME
notcurses_metric - fixed-width numeric output with metric suffixes
.SH SYNOPSIS
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.EX
#define NCPREFIXCOLUMNS 7
#define NCIPREFIXCOLUMNS 8
#define NCBPREFIXCOLUMNS 9
#define NCPREFIXSTRLEN (NCPREFIXCOLUMNS + 1)
#define NCIPREFIXSTRLEN (NCIPREFIXCOLUMNS + 1)
#define NCBPREFIXSTRLEN (NCBPREFIXCOLUMNS + 1)
#define NCMETRICFWIDTH(x, cols) ((int)(strlen(x) - ncstrwidth(x) + (cols)))
#define NCPREFIXFMT(x) NCMETRICFWIDTH((x), NCPREFIXCOLUMNS), (x)
#define NCIPREFIXFMT(x) NCMETRIXFWIDTH((x), NCIPREFIXCOLUMNS), (x)
#define NCBPREFIXFMT(x) NCMETRICFWIDTH((x), NCBPREFIXCOLUMNS), (x)
.EE
.PP
\f[B]const char* ncnmetric(uintmax_t \f[R]\f[I]val\f[R]\f[B], size_t s,
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* ncqprefix(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* nciprefix(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* ncbprefix(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
\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]NCPREFIX\f[R]) or 1024 (\f[B]NCIPREFIX\f[R]).
1024 is used for \[dq]digital units of information\[dq], 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µnpfazy
(Milli, Micro, Nano, Pico, Femto, Atto, Zepto, and Yocto).
This covers the range 1e24 (one septillion) through 1e-24, sufficing for
all possible values of a 64-bit \f[B]uintmax_t\f[R].
.PP
\f[B]\f[BI]val\f[B]\f[R] is the value being output, having been scaled
by \f[B]\f[BI]decimal\f[B]\f[R].
\f[B]\f[BI]decimal\f[B]\f[R] will typically be 1; to represent values
less than 1, \f[B]\f[BI]decimal\f[B]\f[R] should be larger than
\f[B]\f[BI]val\f[B]\f[R].
The output will be written to \f[B]\f[BI]buf\f[B]\f[R], which must be at
least:
.IP \[bu] 2
\f[B]NCPREFIXSTRLEN\f[R] + 1 bytes for a 1000-based value
.IP \[bu] 2
\f[B]NCIPREFIXSTRLEN\f[R] + 1 bytes for a 1024-based value
.IP \[bu] 2
\f[B]NCBPREFIXSTRLEN\f[R] + 1 bytes for a 1024-based value with an
\[aq]i\[aq] suffix
.PP
\f[B]\f[BI]s\f[B]\f[R] is the maximum output size, including
\[aq]\[rs]0\[aq], used in the same fashion as \f[B]snprintf(3)\f[R]
(which \f[B]ncnmetric\f[R] calls).
.PP
Three helper functions are provided to simplify these common cases:
.IP
.EX
// Mega, kilo, gigafoo. Use NCPREFIXSTRLEN + 1 and NCPREFIXCOLUMNS.
static inline const char*
ncqprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
  return ncmetric(val, decimal, buf, omitdec, 1000, \[aq]\[rs]0\[aq]);
}

// Mibi, kebi, gibibytes sans \[aq]i\[aq] suffix. Use NCIPREFIXSTRLEN + 1.
static inline const char*
nciprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
  return ncmetric(val, decimal, buf, omitdec, 1024, \[aq]\[rs]0\[aq]);
}

// Mibi, kebi, gibibytes. Use NCBPREFIXSTRLEN + 1 and NCBPREFIXCOLUMNS.
static inline const char*
ncbprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
  return ncmetric(val, decimal, buf, omitdec, 1024, \[aq]i\[aq]);
}
.EE
.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]\f[BI]mult\f[B]\f[R] is the relative multiple for each suffix.
\f[B]\f[BI]uprefix\f[B]\f[R], if not zero, will be used as a suffix
following any metric suffix.
.PP
The maximum number of columns is not directly related to the maximum
number of bytes, since Unicode doesn\[aq]t necessarily map to
single-byte characters (including the \[aq]µ\[aq] micro suffix).
The corresponding defines for maximum column length are:
.IP \[bu] 2
\f[B]NCPREFIXCOLUMNS\f[R] (7)
.IP \[bu] 2
\f[B]NCIPREFIXCOLUMNS\f[R] (8)
.IP \[bu] 2
\f[B]NCBPREFIXCOLUMNS\f[R] (9)
.PP
In general, the maximum-width output will take the form
\f[B]CCC.mmMu\f[R], 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]\f[BI]uprefix\f[B]\f[R].
The minimum-width output will take the form \f[B]C\f[R].
This minimal form can occur if \f[B]\f[BI]omitdec\f[B]\f[R] is non-zero
and a single-column value such as 5 is passed for
\f[B]\f[BI]val\f[B]\f[R].
.PP
Three more defines are provided to simplify formatted fixed-width output
using the results of \f[B]ncmetric\f[R].
Each of these macros accepts a character buffer holding the result of
the call, and expand to \f[I]two\f[R] arguments:
.IP \[bu] 2
\f[B]NCPREFIXFMT(x)\f[R]
.IP \[bu] 2
\f[B]NCIPREFIXFMT(x)\f[R]
.IP \[bu] 2
\f[B]NCBPREFIXFMT(x)\f[R]
.PP
These can be used in e.g.
the following ungainly fashion:
.PP
**ncplane_printf(n, \[dq]%*s\[dq], NCPREFIXFMT(buf));**
.PP
to ensure that the output is always \f[B]NCPREFIXCOLUMNS\f[R] wide.
.SH RETURN VALUES
\f[B]NULL\f[R] if input parameters were invalid.
Otherwise, a pointer to \f[B]\f[BI]buf\f[B]\f[R], filled in with the
formatted output.
.SH EXAMPLES
\f[B]ncnmetric(0, INT_MAX, buf, 0, 1000, \[aq]\[rs]0\[aq])\f[R]:
\[dq]0.00\[dq].
.PP
\f[B]ncnmetric(0, INT_MAX, buf, 1, 1000, \[aq]\[rs]0\[aq])\f[R]:
\[dq]0\[dq].
.PP
\f[B]ncnmetric(1023, INT_MAX, buf, 1, 1000, \[aq]\[rs]0\[aq])\f[R]:
\[dq]1.02K\[dq].
.PP
\f[B]ncnmetric(1023, INT_MAX, buf, 1, 1024, \[aq]i\[aq])\f[R]:
\[dq]1023\[dq].
.PP
\f[B]ncnmetric(1024, INT_MAX, buf, 1, 1024, \[aq]i\[aq])\f[R]:
\[dq]1Ki\[dq].
.PP
\f[B]ncnmetric(4096, INT_MAX, buf, 0, 1024, \[aq]i\[aq])\f[R]:
\[dq]4.00Ki\[dq].
.PP
\f[B]ncnmetric(0x7fffffffffffffff, INT_MAX, buf, 0, 1000,
\[aq]\[rs]0\[aq])\f[R]: \[dq]9.22E\[dq].
.PP
\f[B]ncnmetric(0xffffffffffffffff, INT_MAX, buf, 0, 1000,
\[aq]\[rs]0\[aq])\f[R]: \[dq]18.45E\[dq].
.SH BUGS
This function is difficult to understand.
.SH SEE ALSO
\f[B]localeconv(3)\f[R], \f[B]notcurses(3)\f[R],
\f[B]notcurses_output(3)\f[R], \f[B]setlocale(3)\f[R],
\f[B]snprintf(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.