Line breaking <unilbrk.h>
*************************

This include file declares functions for determining where in a string line breaks could or should be introduced, in order to make the displayed string fit into a column of given width.

These functions are locale dependent.  The ENCODING argument identifies the encoding (e.g. "ISO-8859-2" for Polish).

The following enumerated values indicate whether, at a given position, a line break is possible or not.  Given an string S as an array S[0..N-1] and a position I, the values have the following meanings:

 -- Constant: int UC_BREAK_MANDATORY
     This value indicates that S[I] is a line break character.

 -- Constant: int UC_BREAK_POSSIBLE
     This value indicates that a line break may be inserted between S[I-1] and S[I].

 -- Constant: int UC_BREAK_HYPHENATION
     This value indicates that a hyphen and a line break may be inserted between S[I-1] and S[I].  But beware of language dependent hyphenation rules.

 -- Constant: int UC_BREAK_PROHIBITED
     This value indicates that S[I-1] and S[I] must not be separated.

 -- Constant: int UC_BREAK_UNDEFINED
     This value is not used as a return value; rather, in the overriding argument of the u*_width_linebreaks functions, it indicates the absence of an override.

The following functions determine the positions at which line breaks are possible.

 -- Function: void u8_possible_linebreaks (const uint8_t *S, size_t N, const char *ENCODING, char *P)
 -- Function: void u16_possible_linebreaks (const uint16_t *S, size_t N, const char *ENCODING, char *P)
 -- Function: void u32_possible_linebreaks (const uint32_t *S, size_t N, const char *ENCODING, char *P)
 -- Function: void ulc_possible_linebreaks (const char *S, size_t N, const char *ENCODING, char *P)
     Determines the line break points in S, and stores the result at P[0..N-1].  Every P[I] is assigned one of the values UC_BREAK_MANDATORY, UC_BREAK_POSSIBLE, UC_BREAK_HYPHENATION, UC_BREAK_PROHIBITED.

The following functions determine where line breaks should be inserted so that each line fits in a given width, when output to a device that uses non-proportional fonts.

 -- Function: int u8_width_linebreaks (const uint8_t *S, size_t N, int WIDTH, int START_COLUMN, int AT_END_COLUMNS, const char *OVERRIDE, const char *ENCODING, char *P)
 -- Function: int u16_width_linebreaks (const uint16_t *S, size_t N, int WIDTH, int START_COLUMN, int AT_END_COLUMNS, const char *OVERRIDE, const char *ENCODING, char *P)
 -- Function: int u32_width_linebreaks (const uint32_t *S, size_t N, int WIDTH, int START_COLUMN, int AT_END_COLUMNS, const char *OVERRIDE, const char *ENCODING, char *P)
 -- Function: int ulc_width_linebreaks (const char *S, size_t N, int WIDTH, int START_COLUMN, int AT_END_COLUMNS, const char *OVERRIDE, const char *ENCODING, char *P)
     Chooses the best line breaks, assuming that every character occupies a width given by the uc_width function (see uniwidth.h).

     The string is S[0..N-1].

     The maximum number of columns per line is given as WIDTH. The starting column of the string is given as START_COLUMN. If the algorithm shall keep room after the last piece, this amount of room can be given as AT_END_COLUMNS.

     OVERRIDE is an optional override; if OVERRIDE[I] != UC_BREAK_UNDEFINED, OVERRIDE[I] takes precedence over P[I] as returned by the u*_possible_linebreaks function.

     The given ENCODING is used for disambiguating widths in uc_width.

     Returns the column after the end of the string, and stores the result at P[0..N-1].  Every P[I] is assigned one of the values UC_BREAK_MANDATORY, UC_BREAK_POSSIBLE, UC_BREAK_HYPHENATION, UC_BREAK_PROHIBITED.  Here the value UC_BREAK_POSSIBLE indicates that a line break should be inserted.