diff options
author | Bruno Haible <bruno@clisp.org> | 2009-04-05 13:42:11 +0200 |
---|---|---|
committer | Bruno Haible <bruno@clisp.org> | 2009-04-05 13:42:11 +0200 |
commit | 2a7574c8ee4f01db28aa57e41e26db19ad138de0 (patch) | |
tree | 60b591185c8d4bf9d67e4594bd7e61740ec1bc84 /doc | |
parent | c01cf0e5628faefdc80cc126a2cddb6403f315d5 (diff) | |
download | libunistring-2a7574c8ee4f01db28aa57e41e26db19ad138de0.tar.gz |
Documentation of <unilbrk.h>.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/unilbrk.texi | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/doc/unilbrk.texi b/doc/unilbrk.texi new file mode 100644 index 0000000..545bc3b --- /dev/null +++ b/doc/unilbrk.texi @@ -0,0 +1,85 @@ +@node unilbrk.h +@chapter Line breaking @code{<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 @var{encoding} argument identifies +the encoding (e.g@. @code{"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 @var{s} as an array +@code{@var{s}[0..@var{n}-1]} and a position @var{i}, the values have the +following meanings: + +@deftypevr Constant int UC_BREAK_MANDATORY +This value indicates that @code{@var{s}[@var{i}]} is a line break character. +@end deftypevr + +@deftypevr Constant int UC_BREAK_POSSIBLE +This value indicates that a line break may be inserted between +@code{@var{s}[@var{i}-1]} and @code{@var{s}[@var{i}]}. +@end deftypevr + +@deftypevr Constant int UC_BREAK_HYPHENATION +This value indicates that a hyphen and a line break may be inserted between +@code{@var{s}[@var{i}-1]} and @code{@var{s}[@var{i}]}. But beware of language +dependent hyphenation rules. +@end deftypevr + +@deftypevr Constant int UC_BREAK_PROHIBITED +This value indicates that @code{@var{s}[@var{i}-1]} and @code{@var{s}[@var{i}]} +must not be separated. +@end deftypevr + +@deftypevr Constant int UC_BREAK_UNDEFINED +This value is not used as a return value; rather, in the overriding argument of +the @code{u*_width_linebreaks} functions, it indicates the absence of an +override. +@end deftypevr + +The following functions determine the positions at which line breaks are +possible. + +@deftypefun void u8_possible_linebreaks (const uint8_t *@var{s}, size_t @var{n}, const char *@var{encoding}, char *@var{p}) +@deftypefunx void u16_possible_linebreaks (const uint16_t *@var{s}, size_t @var{n}, const char *@var{encoding}, char *@var{p}) +@deftypefunx void u32_possible_linebreaks (const uint32_t *@var{s}, size_t @var{n}, const char *@var{encoding}, char *@var{p}) +@deftypefunx void ulc_possible_linebreaks (const char *@var{s}, size_t @var{n}, const char *@var{encoding}, char *@var{p}) +Determines the line break points in @var{s}, and stores the result at +@code{@var{p}[0..@var{n}-1]}. Every @code{@var{p}[@var{i}]} is assigned one of +the values @code{UC_BREAK_MANDATORY}, @code{UC_BREAK_POSSIBLE}, +@code{UC_BREAK_HYPHENATION}, @code{UC_BREAK_PROHIBITED}. +@end deftypefun + +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. + +@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}) +@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}) +@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}) +@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}) +Chooses the best line breaks, assuming that every character occupies a width +given by the @code{uc_width} function (see @ref{uniwidth.h}). + +The string is @code{@var{s}[0..@var{n}-1]}. + +The maximum number of columns per line is given as @var{width}. +The starting column of the string is given as @var{start_column}. +If the algorithm shall keep room after the last piece, this amount of room can +be given as @var{at_end_columns}. + +@var{override} is an optional override; if +@code{@var{override}[@var{i}] != UC_BREAK_UNDEFINED}, +@code{@var{override}[@var{i}]} takes precedence over @code{@var{p}[@var{i}]} +as returned by the @code{u*_possible_linebreaks} function. + +The given @var{encoding} is used for disambiguating widths in @code{uc_width}. + +Returns the column after the end of the string, and stores the result at +@code{@var{p}[0..@var{n}-1]}. Every @code{@var{p}[@var{i}]} is assigned one of +the values @code{UC_BREAK_MANDATORY}, @code{UC_BREAK_POSSIBLE}, +@code{UC_BREAK_HYPHENATION}, @code{UC_BREAK_PROHIBITED}. Here the value +@code{UC_BREAK_POSSIBLE} indicates that a line break @emph{should} be inserted. +@end deftypefun |