@node uniwidth.h
@chapter Display width @code{<uniwidth.h>}

@cindex width
This include file declares functions that return the display width, measured
in columns, of characters or strings, when output to a device that uses
non-proportional fonts.

@cindex ambiguous width
Note that for some rarely used characters the actual fonts or terminal
emulators can use a different width.  There is no mechanism for communicating
the display width of characters across a Unix pseudo-terminal (tty).  Also,
there are scripts with complex rendering, like the Indic scripts.  For these
scripts, there is no such concept as non-proportional fonts.  Therefore
the results of these functions usually work fine on most scripts and on
most characters but can fail to represent the actual display width.

These functions are locale dependent.  The @var{encoding} argument identifies
the encoding (e.g@. @code{"ISO-8859-2"} for Polish).

@cindex Unicode character, width
@cindex halfwidth
@cindex fullwidth
@deftypefun int uc_width (ucs4_t @var{uc}, const char *@var{encoding})
Determines and returns the number of column positions required for @var{uc}.
Returns -1 if @var{uc} is a control character that has an influence on the
column position when output.
@end deftypefun

@deftypefun int u8_width (const uint8_t *@var{s}, size_t @var{n}, const char *@var{encoding})
@deftypefunx int u16_width (const uint16_t *@var{s}, size_t @var{n}, const char *@var{encoding})
@deftypefunx int u32_width (const uint32_t *@var{s}, size_t @var{n}, const char *@var{encoding})
Determines and returns the number of column positions required for first
@var{n} units (or fewer if @var{s} ends before this) in @var{s}.  This
function ignores control characters in the string.
@end deftypefun

@deftypefun int u8_strwidth (const uint8_t *@var{s}, const char *@var{encoding})
@deftypefunx int u16_strwidth (const uint16_t *@var{s}, const char *@var{encoding})
@deftypefunx int u32_strwidth (const uint32_t *@var{s}, const char *@var{encoding})
Determines and returns the number of column positions required for @var{s}.
This function ignores control characters in the string.
@end deftypefun
