doc/uniwidth.texi

   1 @node uniwidth.h
   2 @chapter Display width @code{<uniwidth.h>}
   3
   4 @cindex width
   5 This include file declares functions that return the display width, measured
   6 in columns, of characters or strings, when output to a device that uses
   7 non-proportional fonts.
   8
   9 @cindex ambiguous width
  10 Note that for some rarely used characters the actual fonts or terminal
  11 emulators can use a different width.  There is no mechanism for communicating
  12 the display width of characters across a Unix pseudo-terminal (tty).  Also,
  13 there are scripts with complex rendering, like the Indic scripts.  For these
  14 scripts, there is no such concept as non-proportional fonts.  Therefore
  15 the results of these functions usually work fine on most scripts and on
  16 most characters but can fail to represent the actual display width.
  17
  18 These functions are locale dependent.  The @var{encoding} argument identifies
  19 the encoding (e.g@. @code{"ISO-8859-2"} for Polish).
  20
  21 @cindex Unicode character, width
  22 @cindex halfwidth
  23 @cindex fullwidth
  24 @deftypefun int uc_width (ucs4_t @var{uc}, const char *@var{encoding})
  25 Determines and returns the number of column positions required for @var{uc}.
  26 Returns -1 if @var{uc} is a control character that has an influence on the
  27 column position when output.
  28 @end deftypefun
  29
  30 @deftypefun int u8_width (const uint8_t *@var{s}, size_t @var{n}, const char *@var{encoding})
  31 @deftypefunx int u16_width (const uint16_t *@var{s}, size_t @var{n}, const char *@var{encoding})
  32 @deftypefunx int u32_width (const uint32_t *@var{s}, size_t @var{n}, const char *@var{encoding})
  33 Determines and returns the number of column positions required for first
  34 @var{n} units (or fewer if @var{s} ends before this) in @var{s}.  This
  35 function ignores control characters in the string.
  36 @end deftypefun
  37
  38 @deftypefun int u8_strwidth (const uint8_t *@var{s}, const char *@var{encoding})
  39 @deftypefunx int u16_strwidth (const uint16_t *@var{s}, const char *@var{encoding})
  40 @deftypefunx int u32_strwidth (const uint32_t *@var{s}, const char *@var{encoding})
  41 Determines and returns the number of column positions required for @var{s}.
  42 This function ignores control characters in the string.
  43 @end deftypefun