.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_metric" "3" "v3.0.0" "" ""
.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 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)
\f[R]
.fi
.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
.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]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\[mc]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
.nf
\f[C]
// 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]);
}
\f[R]
.fi
.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]\[mc]\[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
.PP
\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
.PP
\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
.PP
This function is difficult to understand.
.SH SEE ALSO
.PP
\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>.