doc/unilbrk.texi

   1 @node unilbrk.h
   2 @chapter Line breaking @code{<unilbrk.h>}
   3
   4 @cindex line breaks
   5 @cindex breaks, line
   6 @cindex wrapping
   7 This include file declares functions for determining where in a string
   8 line breaks could or should be introduced, in order to make the displayed
   9 string fit into a column of given width.
  10
  11 These functions are locale dependent.  The @var{encoding} argument identifies
  12 the encoding (e.g@. @code{"ISO-8859-2"} for Polish).
  13
  14 The following enumerated values indicate whether, at a given position, a line
  15 break is possible or not.  Given an string @var{s} as an array
  16 @code{@var{s}[0..@var{n}-1]} and a position @var{i}, the values have the
  17 following meanings:
  18
  19 @deftypevr Constant int UC_BREAK_MANDATORY
  20 This value indicates that @code{@var{s}[@var{i}]} is a line break character.
  21 @end deftypevr
  22
  23 @deftypevr Constant int UC_BREAK_POSSIBLE
  24 This value indicates that a line break may be inserted between
  25 @code{@var{s}[@var{i}-1]} and @code{@var{s}[@var{i}]}.
  26 @end deftypevr
  27
  28 @deftypevr Constant int UC_BREAK_HYPHENATION
  29 This value indicates that a hyphen and a line break may be inserted between
  30 @code{@var{s}[@var{i}-1]} and @code{@var{s}[@var{i}]}.  But beware of language
  31 dependent hyphenation rules.
  32 @end deftypevr
  33
  34 @deftypevr Constant int UC_BREAK_PROHIBITED
  35 This value indicates that @code{@var{s}[@var{i}-1]} and @code{@var{s}[@var{i}]}
  36 must not be separated.
  37 @end deftypevr
  38
  39 @deftypevr Constant int UC_BREAK_UNDEFINED
  40 This value is not used as a return value; rather, in the overriding argument of
  41 the @code{u*_width_linebreaks} functions, it indicates the absence of an
  42 override.
  43 @end deftypevr
  44
  45 The following functions determine the positions at which line breaks are
  46 possible.
  47
  48 @deftypefun void u8_possible_linebreaks (const uint8_t *@var{s}, size_t @var{n}, const char *@var{encoding}, char *@var{p})
  49 @deftypefunx void u16_possible_linebreaks (const uint16_t *@var{s}, size_t @var{n}, const char *@var{encoding}, char *@var{p})
  50 @deftypefunx void u32_possible_linebreaks (const uint32_t *@var{s}, size_t @var{n}, const char *@var{encoding}, char *@var{p})
  51 @deftypefunx void ulc_possible_linebreaks (const char *@var{s}, size_t @var{n}, const char *@var{encoding}, char *@var{p})
  52 Determines the line break points in @var{s}, and stores the result at
  53 @code{@var{p}[0..@var{n}-1]}.  Every @code{@var{p}[@var{i}]} is assigned one of
  54 the values @code{UC_BREAK_MANDATORY}, @code{UC_BREAK_POSSIBLE},
  55 @code{UC_BREAK_HYPHENATION}, @code{UC_BREAK_PROHIBITED}.
  56 @end deftypefun
  57
  58 The following functions determine where line breaks should be inserted so that
  59 each line fits in a given width, when output to a device that uses
  60 non-proportional fonts.
  61
  62 @deftypefun int u8_width_linebreaks (const uint8_t *@var{s}, size_t @var{n}, int @var{width}, int @var{start_column}, int @var{at_end_columns}, const char *@var{override}, const char *@var{encoding}, char *@var{p})
  63 @deftypefunx int u16_width_linebreaks (const uint16_t *@var{s}, size_t @var{n}, int @var{width}, int @var{start_column}, int @var{at_end_columns}, const char *@var{override}, const char *@var{encoding}, char *@var{p})
  64 @deftypefunx int u32_width_linebreaks (const uint32_t *@var{s}, size_t @var{n}, int @var{width}, int @var{start_column}, int @var{at_end_columns}, const char *@var{override}, const char *@var{encoding}, char *@var{p})
  65 @deftypefunx int ulc_width_linebreaks (const char *@var{s}, size_t @var{n}, int @var{width}, int @var{start_column}, int @var{at_end_columns}, const char *@var{override}, const char *@var{encoding}, char *@var{p})
  66 Chooses the best line breaks, assuming that every character occupies a width
  67 given by the @code{uc_width} function (see @ref{uniwidth.h}).
  68
  69 The string is @code{@var{s}[0..@var{n}-1]}.
  70
  71 The maximum number of columns per line is given as @var{width}.
  72 The starting column of the string is given as @var{start_column}.
  73 If the algorithm shall keep room after the last piece, this amount of room can
  74 be given as @var{at_end_columns}.
  75
  76 @var{override} is an optional override; if
  77 @code{@var{override}[@var{i}] != UC_BREAK_UNDEFINED},
  78 @code{@var{override}[@var{i}]} takes precedence over @code{@var{p}[@var{i}]}
  79 as returned by the @code{u*_possible_linebreaks} function.
  80
  81 The given @var{encoding} is used for disambiguating widths in @code{uc_width}.
  82
  83 Returns the column after the end of the string, and stores the result at
  84 @code{@var{p}[0..@var{n}-1]}.  Every @code{@var{p}[@var{i}]} is assigned one of
  85 the values @code{UC_BREAK_MANDATORY}, @code{UC_BREAK_POSSIBLE},
  86 @code{UC_BREAK_HYPHENATION}, @code{UC_BREAK_PROHIBITED}.  Here the value
  87 @code{UC_BREAK_POSSIBLE} indicates that a line break @emph{should} be inserted.
  88 @end deftypefun