NAME
textwrap - line-folding (text-wrapping) library with i18n support
SYNOPSIS
#include <textwrap.h>
void textwrap_init(textwrap_t *prop);
void textwrap_columns(textwrap_t *prop, int columns);
void textwrap_tab(textwrap_t *prop, int tab);
void textwrap_head(textwrap_t *prop, const char *head1, const char
*head2);
char *textwrap(const textwrap_t *prop, const char *text);
DESCRIPTION
textwrap is a library to wrap given text to fit the terminal with a
certain width. This is like Text::Wrap(3pm).
Unlike other libraries or functions, this supports
internationalization.
At first, this automatically detects the current LC_CTYPE locale and
follows it. To enable this, your application must call setlocale(3) in
advance.
Next, this supports multibyte encodings such as UTF-8 and EUC-JP. In
multibyte encodings, one character consists from one or more bytes.
Third, this supports fullwidth characters such as CJK Ideogram,
Katakana, Hiragana, and Hangul. These characters occupy two columns
per one character on the terminal.
Forth, this supports combining characters such as Thai and accents for
Latin scripts. These characters occupy zero columns per one character
on the terminal.
Fifth, this supports languages which do not use whitespaces between
words. In these languages, lines can be folded at any places with
small amount of exception (such as before commas).
USAGE
At first, you will have to prepare a set of parameters as textwrap_t.
Prepare a variable of textwrap_t and then call textwrap_init() with the
pointer to the variable.
Members of textwrap_t may change in future. Thus, please use API
functions to modify values of these members.
textwrap_columns()
Specifies the number of columns or width of your terminal. The
result string will not have longer line than this value. The
default value is 76.
textwrap_tab()
Specifies the number of columns for TAB code. The default is 8.
textwrap_head()
Specifies strings which will be added at the top of the top line
and following lines. The defaults are NULL for head1 and NULL
for head2.
The real text-wrapping is performed by textwrap(). The text to be
folded is given as text. The text must be encoded in the current
LC_CTYPE locale, i.e., ISO-8859-1 in ISO-8859-1 locales, KOI8-R in
KOI8-R locales, EUC-JP in EUC-JP locales, UTF-8 in UTF-8 locales, and
so on. Though you might not be very familiar with the term LC_CTYPE
locale, this behavior is under what most of users use UNIX-like
systems. Thus, you do not have to convert the encoding of the string.
The text can contain tab code (0x09). The tab is converted into proper
number of space code (0x20) by textwrap.
RETURN VALUE
textwrap() returns the line-folded text. You can free(3) the given
value.
EXAMPLE
#include <stdio.h>
#include <textwrap.h>
main()
{
textwrap_t property;
char *text = "This is a sample.\n";
char *outtext;
textwrap_init(&property);
textwrap_columns(&property, 70);
outtext = textwrap(&property, text);
printf("%s\n",outtext);
free(outtext);
}
SEE ALSO
Manual pages of dotextwrap(1), setlocale(3), locale(7), charsets(7),
and UTF-8(7).
AUTHOR
Tomohiro KUBOTA <kubota@debian.org>.
2003-08-16 textwrap(3)