From 4e4a75bc527f4acd00b37c52a88c6ea1ca3be300 Mon Sep 17 00:00:00 2001 From: nick black Date: Wed, 5 Jun 2024 07:01:51 -0400 Subject: [PATCH] notcurses_metric: corrections, add note to BUGS --- doc/man/man3/notcurses_metric.3.md | 24 +++++++++++++++--------- include/notcurses/notcurses.h | 3 +-- src/lib/plot.c | 8 ++++---- 3 files changed, 20 insertions(+), 15 deletions(-) diff --git a/doc/man/man3/notcurses_metric.3.md b/doc/man/man3/notcurses_metric.3.md index c684327d2..3f5c750fc 100644 --- a/doc/man/man3/notcurses_metric.3.md +++ b/doc/man/man3/notcurses_metric.3.md @@ -33,12 +33,12 @@ notcurses_metric - fixed-width numeric output with metric suffixes # DESCRIPTION -**ncmetric** (and the helper wrappers **qprefix** and **bprefix**) accept -very large (or very small) non-negative numbers, and prepare formatted output +**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. **ncmetric** supports the large suffixes KMGTPEZY (Kilo, Mega, +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 @@ -62,19 +62,19 @@ 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 ncmetric(val, decimal, buf, omitdec, 1000, '\0'); + 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 ncmetric(val, decimal, buf, omitdec, 1024, '\0'); + 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 ncmetric(val, decimal, buf, omitdec, 1024, 'i'); + return ncnmetric(val, decimal, buf, omitdec, 1024, 'i'); } ``` @@ -101,7 +101,7 @@ suffix, and u is the ***uprefix***. The minimum-width output will take the form 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 **ncmetric**. Each of these macros accepts a character buffer +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)** @@ -116,7 +116,8 @@ to ensure that the output is always **NCPREFIXCOLUMNS** wide. # RETURN VALUES -**NULL** if input parameters were invalid. Otherwise, a pointer to ***buf***, +**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 @@ -139,7 +140,12 @@ filled in with the formatted output. # BUGS -This function is difficult to understand. +This function is difficult to understand, and takes too many arguments. + +This function uses a library-wide instance of **struct notcurses**, created +in **notcurses_init**. If **notcurses_init** is called multiple times in a +process's lifetime, behavior is undefined. If **notcurses_stop** is called, +behavior is undefined. # SEE ALSO diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index c2e1b4c41..9a859e9a0 100644 --- a/include/notcurses/notcurses.h +++ b/include/notcurses/notcurses.h @@ -3790,8 +3790,7 @@ API struct ncplane* nctablet_plane(struct nctablet* t); // // You are encouraged to consult notcurses_metric(3). API const char* ncnmetric(uintmax_t val, size_t s, uintmax_t decimal, - char* buf, int omitdec, uintmax_t mult, - int uprefix) + char* buf, int omitdec, uintmax_t mult, int uprefix) __attribute__ ((nonnull (4))); // The number of columns is one fewer, as the STRLEN expressions must leave diff --git a/src/lib/plot.c b/src/lib/plot.c index 99954d017..e240d0e06 100644 --- a/src/lib/plot.c +++ b/src/lib/plot.c @@ -89,7 +89,7 @@ typedef struct nc##X##plot { \ ncplot plot; \ } nc##X##plot; \ \ -int redraw_pixelplot_##T(nc##X##plot* ncp){ \ +static int redraw_pixelplot_##T(nc##X##plot* ncp){ \ if(calculate_gradient_vector(&ncp->plot, 1)){ \ return -1; \ } \ @@ -256,7 +256,7 @@ int redraw_pixelplot_##T(nc##X##plot* ncp){ \ return 0; \ } \ \ -int redraw_plot_##T(nc##X##plot* ncp){ \ +static int redraw_plot_##T(nc##X##plot* ncp){ \ if(ncp->plot.bset->geom == NCBLIT_PIXEL){ \ return redraw_pixelplot_##T(ncp); \ } \ @@ -429,8 +429,8 @@ int redraw_plot_##T(nc##X##plot* ncp){ \ } \ \ static const struct blitset* \ -create_##T(nc##X##plot* ncpp, ncplane* n, const ncplot_options* opts, const T miny, const T maxy, \ - const T trueminy, const T truemaxy){ \ +create_##T(nc##X##plot* ncpp, ncplane* n, const ncplot_options* opts, \ + const T miny, const T maxy, const T trueminy, const T truemaxy){ \ /* set up ->plot.ncp first so it gets destroyed on error */ \ ncpp->plot.ncp = n; \ if(ncplane_set_widget(ncpp->plot.ncp, ncpp, (void(*)(void*))nc##X##plot_destroy)){ \