notcurses/doc/man/man3/notcurses_metric.3.md

147 lines
5.2 KiB
Markdown
Raw Normal View History

2020-05-24 08:48:17 +00:00
% notcurses_metric(3)
% nick black <nickblack@linux.com>
2021-02-03 13:34:49 +00:00
% v2.1.8
2020-05-24 08:48:17 +00:00
# NAME
notcurses_metric - fixed-width numeric output with metric suffixes
# SYNOPSIS
**#include <notcurses/notcurses.h>**
```c
#define PREFIXCOLUMNS 7
#define IPREFIXCOLUMNS 8
#define BPREFIXCOLUMNS 9
#define PREFIXSTRLEN (PREFIXCOLUMNS + 1)
#define IPREFIXSTRLEN (IPREFIXCOLUMNS + 1)
#define BPREFIXSTRLEN (BPREFIXCOLUMNS + 1)
2020-09-15 05:39:42 +00:00
#define NCMETRICFWIDTH(x, cols) ((int)(strlen(x) - ncstrwidth(x) + (cols)))
2020-05-24 08:48:17 +00:00
#define PREFIXFMT(x) NCMETRICFWIDTH((x), PREFIXCOLUMNS), (x)
#define IPREFIXFMT(x) NCMETRIXFWIDTH((x), IPREFIXCOLUMNS), (x)
#define BPREFIXFMT(x) NCMETRICFWIDTH((x), BPREFIXCOLUMNS), (x)
```
**const char* ncmetric(uintmax_t ***val***, uintmax_t ***decimal***, char* ***buf***, int ***omitdec***, unsigned ***mult***, int ***uprefix***);**
2020-05-24 08:48:17 +00:00
**static inline const char* qprefix(uintmax_t ***val***, uintmax_t ***decimal***, char* ***buf***, int ***omitdec***);**
**static inline const char* iprefix(uintmax_t ***val***, uintmax_t ***decimal***, char* ***buf***, int ***omitdec***);**
**static inline const char* bprefix(uintmax_t ***val***, uintmax_t ***decimal***, char* ***buf***, int ***omitdec***);**
2020-05-24 08:48:17 +00:00
# DESCRIPTION
**ncmetric** (and the helper wrappers **qprefix** and **bprefix**) 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 (**PREFIX**) or 1024
(**IPREFIX**). 1024 is used for "digital units of information", i.e. kibibytes
and gibibits. **ncmetric** supports the large suffixes KMGTPEZY (Kilo, Mega,
2020-05-24 08:48:17 +00:00
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 **uintmax_t**.
2020-05-24 08:48:17 +00:00
**val** is the value being output, having been scaled by **decimal**.
**decimal** will typically be 1; to represent values less than 1, **decimal**
should be larger than **val**. The output will be written to **buf**, which
must be at least:
* **PREFIXSTRLEN** + 1 bytes for a 1000-based value
* **IPREFIXSTRLEN** + 1 bytes for a 1024-based value
* **BPREFIXSTRLEN** + 1 bytes for a 1024-based value with an 'i' suffix
Three helper functions are provided to simplify these common cases:
```
// Mega, kilo, gigafoo. Use PREFIXSTRLEN + 1 and PREFIXCOLUMNS.
static inline const char*
qprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
return ncmetric(val, decimal, buf, omitdec, 1000, '\0');
}
// Mibi, kebi, gibibytes sans 'i' suffix. Use IPREFIXSTRLEN + 1.
static inline const char*
iprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
return ncmetric(val, decimal, buf, omitdec, 1024, '\0');
}
// Mibi, kebi, gibibytes. Use BPREFIXSTRLEN + 1 and BPREFIXCOLUMNS.
static inline const char*
bprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
return ncmetric(val, decimal, buf, omitdec, 1024, 'i');
}
```
2020-05-24 08:48:17 +00:00
If **omitdec** 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 **setlocale(3)** and **localeconv(3)**).
**mult** is the relative multiple for each suffix. **uprefix**, if not zero,
will be used as a suffix following any metric suffix.
The maximum number of columns is not directly related to the maximum number of
bytes, since Unicode doesn't necessarily map to single-byte characters
(including the 'µ' micro suffix). The corresponding defines for maximum column
length are:
2020-05-24 08:48:17 +00:00
* **PREFIXCOLUMNS** (7)
* **IPREFIXCOLUMNS** (8)
* **BPREFIXCOLUMNS** (9)
2020-05-24 08:48:17 +00:00
In general, the maximum-width output will take the form **CCC.mmMu**, where C
are digits of the characteristic (up to ceil(log10(**mult**)) digits), the
decimal point follows, m are digits of the mantissa (up to 2), M is the metric
suffix, and u is the **uprefix**. The minimum-width output will take the form
**C**. This minimal form can occur if **omitdec** is non-zero and a
single-column value such as 5 is passed for **val**.
2020-05-24 08:48:17 +00:00
Three more defines are provided to simplify formatted fixed-width output using
the results of **ncmetric**. Each of these macros accepts a character buffer
holding the result of the call, and expand to *two* arguments:
2020-05-24 08:48:17 +00:00
* **PREFIXFMT(x)**
* **IPREFIXFMT(x)**
* **BPREFIXFMT(x)**
These can be used in e.g. the following ungainly fashion:
**ncplane_printf(n, "%*s", PREFIXFMT(buf));**
to ensure that the output is always **PREFIXCOLUMNS** wide.
2020-05-24 08:48:17 +00:00
# RETURN VALUES
**NULL** if input parameters were invalid. Otherwise, a pointer to **buf**,
filled in with the formatted output.
# EXAMPLES
**ncmetric(0, 1, buf, 0, 1000, '\0')**: "0.00".
**ncmetric(0, 1, buf, 1, 1000, '\0')**: "0".
**ncmetric(1023, 1, buf, 1, 1000, '\0')**: "1.02K".
**ncmetric(1023, 1, buf, 1, 1024, 'i')**: "1023".
**ncmetric(1024, 1, buf, 1, 1024, 'i')**: "1Ki".
**ncmetric(4096, 1, buf, 0, 1024, 'i')**: "4.00Ki".
**ncmetric(0x7fffffffffffffff, 1, buf, 0, 1000, '\0')**: "9.22E".
**ncmetric(0xffffffffffffffff, 1, buf, 0, 1000, '\0')**: "18.45E".
# BUGS
This function is difficult to understand.
2020-05-24 08:48:17 +00:00
# SEE ALSO
**localeconv(3)**,
**notcurses(3)**,
**notcurses_output(3)**,
2020-05-24 08:48:17 +00:00
**setlocale(3)**