Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
notcurses_metric(3)					   notcurses_metric(3)

NAME
       notcurses_metric	- fixed-width numeric output with metric suffixes

SYNOPSIS
       #include	<notcurses/notcurses.h>

	      #define PREFIXCOLUMNS 7
	      #define IPREFIXCOLUMNS 8
	      #define BPREFIXCOLUMNS 9
	      #define PREFIXSTRLEN (PREFIXCOLUMNS + 1)
	      #define IPREFIXSTRLEN (IPREFIXCOLUMNS + 1)
	      #define BPREFIXSTRLEN (BPREFIXCOLUMNS + 1)
	      #define NCMETRICFWIDTH(x,	cols) ((int)(strlen(x) - ncstrwidth(x) + (cols)))
	      #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);

       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);

DESCRIPTION
       ncmetric	 (and  the  helper  wrappers  qprefix and bprefix) accept very
       large (or very small) non-negative numbers, and prepare formatted  out-
       put 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,  Giga,  Tera,  Peta, Exa, Zetta, and Yotta) and the small
       suffixes	m<micro>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:

       o PREFIXSTRLEN +	1 bytes	for a 1000-based value

       o IPREFIXSTRLEN + 1 bytes for a 1024-based value

       o 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');
	      }

       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>' micro suffix).  The corresponding
       defines for maximum column length are:

       o PREFIXCOLUMNS (7)

       o IPREFIXCOLUMNS	(8)

       o BPREFIXCOLUMNS	(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 out-
       put using the results of	ncmetric.  Each	 of  these  macros  accepts  a
       character  buffer holding the result of the call, and expand to two ar-
       guments:

       o PREFIXFMT(x)

       o IPREFIXFMT(x)

       o 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.

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.

SEE ALSO
       localeconv(3), notcurses(3), notcurses_output(3), setlocale(3)

AUTHORS
       nick black <nickblack@linux.com>.

				    v2.1.4		   notcurses_metric(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | BUGS | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=notcurses_metric&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help