Documentation of <uniwidth.h>.

1 files changed, 38 insertions, 0 deletions

diff --git a/doc/uniwidth.texi b/doc/uniwidth.texi
new file mode 100644
index 0000000..8c53d04
--- /dev/null
+++ b/doc/uniwidth.texi
@@ -0,0 +1,38 @@
+@node uniwidth.h
+@chapter Display width @code{<uniwidth.h>}
+
+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.
+
+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).
+
+@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