.\" 
.\" Copyright 2003 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH text 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
text \- I18N text abstraction
.SH SYNOPSIS
.nf
.B #include <mba/text.h>
.sp

.sp

.sp

.sp
.sp
.BI "int text_length(const tchar *" src ", const tchar *" slim ");
.br
.BI "int text_copy(const tchar *" src ", const tchar *" slim ", tchar *" dst ", tchar *" dlim ", int " n ");
.br
.BI "int text_copy_new(const tchar *" src ",
.BI "            const tchar *" slim ",
.BI "            tchar **" dst ",
.BI "            int " n ",
.BI "            struct allocator *" al ");
.br
.BI "size_t text_size(const tchar *" src ", const tchar *" slim ");
.br

.fi
.SH DESCRIPTION
The
.B text
module provides typedefs and macros to abstract the character type and all standard library functions that operate on them. The resulting source code will support extended charsets and can be used with little or no modification on a variety of popular platforms. If
.I USE_WCHAR
is defined, wide characters will be used (e.g.
.I wchar_t
is UTF-16LE on Windows). Otherwise the locale dependent encoding will be used (e.g. UTF-8 on Unix). Many functions in this library now accept
.I tchar *
strings however
.I char *
or
.I wchar_t *
strings can be used with these functions as
.I tchar
is just a typedef for
.I unsigned char
or
.IR "wchar_t" .
.sp
Additionally, several sentinel pointer string functions are provided.
.sp
See
.I Tchar I18N Text Abstraction
for details.
.PP
.TP
.B text_length
The
.B text_length
function returns the number of elements in the text at
.I src
up to but not including the '\\0' terminator. This function returns 0 if;
.sp
.br
no '\\0' terminator is encountered before
.IR "slim" ,
.br
.IR "src == NULL" ,
.br
or
.IR "src >= slim" 
.sp
The
.B text_length
function is actually a macro for either
.B str_length
or
.BR "wcs_length" .
The
.B wcs_length
function has the same prototype but accepts
.I wchar_t
parameters whereas
.B str_length
accepts
.I unsigned char
parameters.
.TP
.B text_copy
The
.B copy
function copies at most
.I n
elements of the text at
.I src
into
.I dst
up to and including the '\\0' terminator. The text at
.I dst
is always '\\0' terminated unless
.I dst
is a null pointer or
.IR "dst >= dlim" .
.sp
The
.B text_copy
function is actually a macro for either
.B str_copy
or
.BR "wcs_copy" .
The
.B wcs_copy
function has the same prototype but accepts
.I wchar_t
parameters whereas
.B str_copy
accepts
.I unsigned char
parameters.
.TP
.B text_copy_new
The
.B text_copy_new
function copies at most
.I n
elements of the text at
.I src
up to and including the '\\0' terminator into memory allocated from the
.B allocator
specified by the
.I al
parameter. The pointer pointed to by
.I dst
is set to point to the new memory. If the text is copied successfully it is always '\\0' terminated.
.sp
The
.B text_copy_new
function is actually a macro for either
.B str_copy_new
or
.BR "wcs_copy_new" .
The
.B wcs_copy_new
function has the same prototype but accepts
.I wchar_t
parameters whereas
.B str_copy_new
accepts
.I unsigned char
parameters.
.TP
.B text_size
The
.B size
function returns the number of bytes occupied by the text at
.I src
including the '\\0' terminator. This function returns 0 if;
.sp
.br
no '\\0' terminator is encountered before
.IR "slim" ,
.br
.IR "src == NULL" ,
.br
or
.IR "src >= slim" 
.sp
The
.B text_size
function is actually a macro for either
.B str_size
or
.BR "wcs_size" .
The
.B wcs_size
function has the same prototype but accepts
.I wchar_t
parameters whereas
.B str_size
accepts
.I unsigned char
parameters.
.SH RETURNS
.TP
.B text_copy
The
.B text_copy
function returns the number of elements in the text copied to
.I dst
not including the '\\0' terminator. This function returns 0 if;
.sp
.br
no '\\0' terminator is encountered before
.IR "slim" ,
.br
.IR "dst == NULL" ,
.br
.IR "dst >= dlim" ,
.br
.IR "src == NULL" ,
.br
or
.IR "src >= slim" 
.sp

.TP
.B text_copy_new
The
.B text_copy_new
function returns the number of elements in the text at
.I *dst
not including the '\\0' terminator. This function sets
.I *dst
to
.I NULL
and returns 0 if;
.sp
.br
no '\\0' terminator is encountered before
.IR "slim" ,
.br
.IR "src == NULL" ,
.br
or
.IR "src >= slim" 
.sp
and returns 0 if
.IR "dst == NULL" .
If memory for the text cannot be allocated -1 will be returned and
.I errno
will be set appropriately.
.SH LINKS

.I http://www.ioplex.com/~miallen/libmba/dl/docs/text_details.html