notcurses_metric(3)

1notcurses_metric(3)                                        notcurses_metric(3)
2
3
4

NAME

6       notcurses_metric - fixed-width numeric output with metric suffixes
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              #define PREFIXCOLUMNS 7
12              #define IPREFIXCOLUMNS 8
13              #define BPREFIXCOLUMNS 9
14              #define PREFIXSTRLEN (PREFIXCOLUMNS + 1)
15              #define IPREFIXSTRLEN (IPREFIXCOLUMNS + 1)
16              #define BPREFIXSTRLEN (BPREFIXCOLUMNS + 1)
17              #define NCMETRICFWIDTH(x, cols) ((int)(strlen(x) - ncstrwidth(x) + (cols)))
18              #define PREFIXFMT(x) NCMETRICFWIDTH((x), PREFIXCOLUMNS), (x)
19              #define IPREFIXFMT(x) NCMETRIXFWIDTH((x), IPREFIXCOLUMNS), (x)
20              #define BPREFIXFMT(x) NCMETRICFWIDTH((x), BPREFIXCOLUMNS), (x)
21
22       const  char*  ncmetric(uintmax_t val, uintmax_t decimal, char* buf, int
23       omitdec, unsigned mult, int uprefix);
24
25       static inline const char*  qprefix(uintmax_t  val,  uintmax_t  decimal,
26       char* buf, int omitdec);
27
28       static  inline  const  char*  iprefix(uintmax_t val, uintmax_t decimal,
29       char* buf, int omitdec);
30
31       static inline const char*  bprefix(uintmax_t  val,  uintmax_t  decimal,
32       char* buf, int omitdec);
33

DESCRIPTION

35       ncmetric  (and  the  helper  wrappers  qprefix and bprefix) accept very
36       large (or very small) non-negative numbers, and prepare formatted  out‐
37       put of a maximum width using metric suffixes.  The suffix can represent
38       arbitrary amounts of growth, but is designed for 1000 (PREFIX) or  1024
39       (IPREFIX).   1024  is  used  for  "digital  units of information", i.e.
40       kibibytes and gibibits.  ncmetric supports the large suffixes  KMGTPEZY
41       (Kilo,  Mega,  Giga,  Tera,  Peta, Exa, Zetta, and Yotta) and the small
42       suffixes mµnpfazy (Milli, Micro, Nano, Pico, Femto,  Atto,  Zepto,  and
43       Yocto).   This  covers  the  range 1e24 (one septillion) through 1e-24,
44       sufficing for all possible values of a 64-bit uintmax_t.
45
46       val is the value being output, having been scaled by decimal.   decimal
47       will typically be 1; to represent values less than 1, decimal should be
48       larger than val.  The output will be written to buf, which must  be  at
49       least:
50
51       · PREFIXSTRLEN + 1 bytes for a 1000-based value
52
53       · IPREFIXSTRLEN + 1 bytes for a 1024-based value
54
55       · BPREFIXSTRLEN + 1 bytes for a 1024-based value with an 'i' suffix
56
57       Three helper functions are provided to simplify these common cases:
58
59              // Mega, kilo, gigafoo. Use PREFIXSTRLEN + 1 and PREFIXCOLUMNS.
60              static inline const char*
61              qprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
62                return ncmetric(val, decimal, buf, omitdec, 1000, '\0');
63              }
64
65              // Mibi, kebi, gibibytes sans 'i' suffix. Use IPREFIXSTRLEN + 1.
66              static inline const char*
67              iprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
68                return ncmetric(val, decimal, buf, omitdec, 1024, '\0');
69              }
70
71              // Mibi, kebi, gibibytes. Use BPREFIXSTRLEN + 1 and BPREFIXCOLUMNS.
72              static inline const char*
73              bprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
74                return ncmetric(val, decimal, buf, omitdec, 1024, 'i');
75              }
76
77       If  omitdec is not zero, the decimal point and mantissa will be omitted
78       if all digits to be displayed would be zero.  The decimal  point  takes
79       the  current  locale into account (see setlocale(3) and localeconv(3)).
80       mult is the relative multiple for each suffix.  uprefix, if  not  zero,
81       will be used as a suffix following any metric suffix.
82
83       The  maximum  number  of columns is not directly related to the maximum
84       number of bytes, since Unicode doesn't necessarily map  to  single-byte
85       characters (including the 'µ' micro suffix).  The corresponding defines
86       for maximum column length are:
87
88       · PREFIXCOLUMNS (7)
89
90       · IPREFIXCOLUMNS (8)
91
92       · BPREFIXCOLUMNS (9)
93
94       In general, the maximum-width output will take the form CCC.mmMu, where
95       C  are  digits  of the characteristic (up to ceil(log10(mult)) digits),
96       the decimal point follows, m are digits of the mantissa (up to 2), M is
97       the metric suffix, and u is the uprefix.  The minimum-width output will
98       take the form C.  This minimal form can occur if  omitdec  is  non-zero
99       and a single-column value such as 5 is passed for val.
100
101       Three  more defines are provided to simplify formatted fixed-width out‐
102       put using the results of ncmetric.  Each  of  these  macros  accepts  a
103       character  buffer holding the result of the call, and expand to two ar‐
104       guments:
105
106       · PREFIXFMT(x)
107
108       · IPREFIXFMT(x)
109
110       · BPREFIXFMT(x)
111
112       These can be used in e.g.  the following ungainly fashion:
113
114       **ncplane_printf(n, "%*s", PREFIXFMT(buf));**
115
116       to ensure that the output is always PREFIXCOLUMNS wide.
117

RETURN VALUES

119       NULL if input parameters were invalid.  Otherwise, a  pointer  to  buf,
120       filled in with the formatted output.
121

EXAMPLES

123       ncmetric(0, 1, buf, 0, 1000, '\0'): "0.00".
124
125       ncmetric(0, 1, buf, 1, 1000, '\0'): "0".
126
127       ncmetric(1023, 1, buf, 1, 1000, '\0'): "1.02K".
128
129       ncmetric(1023, 1, buf, 1, 1024, 'i'): "1023".
130
131       ncmetric(1024, 1, buf, 1, 1024, 'i'): "1Ki".
132
133       ncmetric(4096, 1, buf, 0, 1024, 'i'): "4.00Ki".
134
135       ncmetric(0x7fffffffffffffff, 1, buf, 0, 1000, '\0'): "9.22E".
136
137       ncmetric(0xffffffffffffffff, 1, buf, 0, 1000, '\0'): "18.45E".
138

BUGS

140       This function is difficult to understand.
141

AUTHORS

146       nick black <nickblack@linux.com>.
147
148
149
150                                    v2.2.3                 notcurses_metric(3)