1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
% notcurses_metric(3)
% nick black <nickblack@linux.com>
% v3.0.16
# NAME
notcurses_metric - fixed-width numeric output with metric suffixes
# SYNOPSIS
**#include <notcurses/notcurses.h>**
```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)
```
**const char* ncnmetric(uintmax_t ***val***, size_t s, uintmax_t ***decimal***, char* ***buf***, int ***omitdec***, unsigned ***mult***, int ***uprefix***);**
**static inline const char* ncqprefix(uintmax_t ***val***, uintmax_t ***decimal***, char* ***buf***, int ***omitdec***);**
**static inline const char* nciprefix(uintmax_t ***val***, uintmax_t ***decimal***, char* ***buf***, int ***omitdec***);**
**static inline const char* ncbprefix(uintmax_t ***val***, uintmax_t ***decimal***, char* ***buf***, int ***omitdec***);**
# DESCRIPTION
**ncnmetric** (and the helper wrappers **nc[qib]prefix**) accept
very large (or very small) non-negative integers, and prepare formatted output
of a maximum width using metric suffixes. The suffix can represent arbitrary
amounts of growth, but is designed for 1000 (**NCPREFIX**) or 1024
(**NCIPREFIX**). 1024 is used for "digital units of information", i.e. kibibytes
and gibibits. **ncnmetric** 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 **uintmax_t**.
***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:
* **NCPREFIXSTRLEN** + 1 bytes for a 1000-based value
* **NCIPREFIXSTRLEN** + 1 bytes for a 1024-based value
* **NCBPREFIXSTRLEN** + 1 bytes for a 1024-based value with an 'i' suffix
***s*** is the maximum output size, including '\0', used in the same
fashion as **snprintf(3)** (which **ncnmetric** calls).
Three helper functions are provided to simplify these common cases:
```
// Mega, kilo, gigafoo. Use NCPREFIXSTRLEN + 1 and NCPREFIXCOLUMNS.
static inline const char*
ncqprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
return ncnmetric(val, decimal, buf, omitdec, 1000, '\0');
}
// Mibi, kebi, gibibytes sans 'i' suffix. Use NCIPREFIXSTRLEN + 1.
static inline const char*
nciprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
return ncnmetric(val, decimal, buf, omitdec, 1024, '\0');
}
// Mibi, kebi, gibibytes. Use NCBPREFIXSTRLEN + 1 and NCBPREFIXCOLUMNS.
static inline const char*
ncbprefix(uintmax_t val, uintmax_t decimal, char* buf, int omitdec){
return ncnmetric(val, decimal, buf, omitdec, 1024, 'i');
}
```
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:
* **NCPREFIXCOLUMNS** (7)
* **NCIPREFIXCOLUMNS** (8)
* **NCBPREFIXCOLUMNS** (9)
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***.
Three more defines are provided to simplify formatted fixed-width output using
the results of **ncnmetric**. Each of these macros accepts a character buffer
holding the result of the call, and expand to *two* arguments:
* **NCPREFIXFMT(x)**
* **NCIPREFIXFMT(x)**
* **NCBPREFIXFMT(x)**
These can be used in e.g. the following ungainly fashion:
**ncplane_printf(n, "%*s", NCPREFIXFMT(buf));**
to ensure that the output is always **NCPREFIXCOLUMNS** wide.
# RETURN VALUES
**NULL** if input parameters were invalid, or if **notcurses_init**
has not been successfully called. Otherwise, a pointer to ***buf***,
filled in with the formatted output.
# EXAMPLES
**ncnmetric(0, INT_MAX, buf, 0, 1000, '\0')**: "0.00".
**ncnmetric(0, INT_MAX, buf, 1, 1000, '\0')**: "0".
**ncnmetric(1023, INT_MAX, buf, 1, 1000, '\0')**: "1.02K".
**ncnmetric(1023, INT_MAX, buf, 1, 1024, 'i')**: "1023".
**ncnmetric(1024, INT_MAX, buf, 1, 1024, 'i')**: "1Ki".
**ncnmetric(4096, INT_MAX, buf, 0, 1024, 'i')**: "4.00Ki".
**ncnmetric(0x7fffffffffffffff, INT_MAX, buf, 0, 1000, '\0')**: "9.22E".
**ncnmetric(0xffffffffffffffff, INT_MAX, buf, 0, 1000, '\0')**: "18.45E".
# BUGS
This function is difficult to understand, and takes too many arguments.
If UTF-8 is available, 'µ' (U+00B5 MICRO SIGN) will be used in place of
'u' (U+0075 LATIN SMALL LETTER U) for the 'micro-' prefix. This is
determined by **notcurses_init**/**ncdirect_init**. Once UTF-8 is detected,
it is used for the lifetime of the process. The alternative would require
accepting a **const struct notcurses** (and associated API break).
# SEE ALSO
**localeconv(3)**,
**notcurses(3)**,
**notcurses_output(3)**,
**setlocale(3)**,
**snprintf(3)**,
**utf-8(7)**
|
