NAME

text - I18N text abstraction

SYNOPSIS

#include <mba/text.h>





int text_length(const tchar *src, const tchar *slim);


int text_copy(const tchar *src, const tchar *slim, tchar *dst, tchar *dlim, int n);


int text_copy_new(const tchar *src,
            const tchar *slim,
            tchar **dst,
            int n,
            struct allocator *al);


size_t text_size(const tchar *src, const tchar *slim);

DESCRIPTION

The 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 USE_WCHAR is defined, wide characters will be used (e.g. 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 tchar * strings however char * or wchar_t * strings can be used with these functions as tchar is just a typedef for unsigned char or wchar_t.

Additionally, several sentinel pointer string functions are provided.

See Tchar I18N Text Abstraction for details.

text_length

The text_length function returns the number of elements in the text at src up to but not including the '\0' terminator. This function returns 0 if;

no '\0' terminator is encountered before slim,
src == NULL,
or src >= slim

The text_length function is actually a macro for either str_length or wcs_length. The wcs_length function has the same prototype but accepts wchar_t parameters whereas str_length accepts unsigned char parameters.

text_copy

The copy function copies at most n elements of the text at src into dst up to and including the '\0' terminator. The text at dst is always '\0' terminated unless dst is a null pointer or dst >= dlim.

The text_copy function is actually a macro for either str_copy or wcs_copy. The wcs_copy function has the same prototype but accepts wchar_t parameters whereas str_copy accepts unsigned char parameters.

text_copy_new

The text_copy_new function copies at most n elements of the text at src up to and including the '\0' terminator into memory allocated from the allocator specified by the al parameter. The pointer pointed to by dst is set to point to the new memory. If the text is copied successfully it is always '\0' terminated.

The text_copy_new function is actually a macro for either str_copy_new or wcs_copy_new. The wcs_copy_new function has the same prototype but accepts wchar_t parameters whereas str_copy_new accepts unsigned char parameters.

text_size

The size function returns the number of bytes occupied by the text at src including the '\0' terminator. This function returns 0 if;

no '\0' terminator is encountered before slim,
src == NULL,
or src >= slim

The text_size function is actually a macro for either str_size or wcs_size. The wcs_size function has the same prototype but accepts wchar_t parameters whereas str_size accepts unsigned char parameters.

RETURNS

text_copy

The text_copy function returns the number of elements in the text copied to dst not including the '\0' terminator. This function returns 0 if;

no '\0' terminator is encountered before slim,
dst == NULL,
dst >= dlim,
src == NULL,
or src >= slim

text_copy_new

The text_copy_new function returns the number of elements in the text at *dst not including the '\0' terminator. This function sets *dst to NULL and returns 0 if;

no '\0' terminator is encountered before slim,
src == NULL,
or src >= slim

and returns 0 if dst == NULL. If memory for the text cannot be allocated -1 will be returned and errno will be set appropriately.

LINKS

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