include/libu8/libu8.h File Reference

These functions provide miscellaneous functionality. More...

Data Structures
struct	U8_INT16
Functions
U8_EXPORT char *	u8_2libc (u8_string string)
	Converts a UTF-8 string to the encoding expected by system (libc) functions.
U8_EXPORT char *	u8_tolibc (u8_string string)
	Converts a UTF-8 string to the encoding expected by system (libc) functions.
U8_EXPORT u8_string	u8_fromlibc (char *local_string)
	Converts a natively encoded string into a UTF-8 string.
U8_EXPORT void	u8_set_libcfns (u8_string(*fromfn)(char *), char *(*tofn)(u8_string))
	This sets the functions used to map to and from libc.
U8_EXPORT u8_string	u8_appid (void)
	Returns a UTF-8 string describing the current application for inclusion in messages or other output or logging.
U8_EXPORT void	u8_identify_application (u8_string id)
	Sets the UTF-8 string describing the current application.
U8_EXPORT int	u8_default_appid (u8_string id)
	Sets the UTF-8 string describing the current application, unless it has already been set.
U8_EXPORT int	u8_config_utf8warn (int flag)
	Sets whether warnings are produced for invalid UTF-8 sequences, which can be annoyingly common with some content.
U8_EXPORT int	u8_initialize (void) U8_LIBINIT_FN
	Initializes the core UTF-8 functions (from libu8.h)
U8_EXPORT int	u8_initialize_io (void) U8_LIBINIT_FN
	Initializes UTF-8 io functions, including character set conversion and stream I/O.
U8_EXPORT int	u8_initialize_fns (void) U8_LIBINIT_FN
	Initializes UTF-8 miscellaneous functions, including time keeping, file access, network access, and server functions.
U8_EXPORT void	u8_init_chardata_c (void) U8_LIBINIT_FN
	Initializes the full character data table for the libu8 library.
U8_EXPORT void	u8_initialize_u8stdio (void) U8_LIBINIT_FN
	Initializes the messaging functions which use POSIX stdio.
U8_EXPORT void	u8_initialize_u8syslog (void) U8_LIBINIT_FN
	Initializes the messaging functions which use POSIX syslog.
U8_EXPORT void *	u8_mallocz (size_t sz)
	Allocates and zero-clears a block of memory.
U8_EXPORT void *	u8_reallocz (void *ptr, size_t sz, size_t osz)
	Reallocates a block of memory, zero clearing any new parts.
U8_EXPORT void *	u8_extalloc (void *ptr, size_t n, size_t osz)
	Copies a block of memory into a larger block, zero clearing any new parts.
U8_EXPORT void	u8_raise (u8_condition ex, u8_context cxt, u8_string details)
	Signals an error with particular details.
U8_EXPORT void	u8_set_error_handler (void(*h)(u8_condition, u8_context, u8_string))
	Sets the function used when an error is raised.
U8_EXPORT unsigned int	u8_random (unsigned int n)
	Returns a random integer between 0 and n-1 (inclusive)
U8_EXPORT void	u8_randomize (unsigned int seed)
	Sets the random seed value used for the random number generation.
U8_EXPORT void *	u8_dynamic_load (u8_string filename)
	Dynamically loads a named file into the running image.
U8_EXPORT u8_string	u8_getenv (u8_string varname)
	Gets a variable specified in the environment.
U8_EXPORT double	u8_elapsed_time (void)
	Returns elapsed time in seconds since some moment after application startup.
U8_EXPORT void	u8_init_syslog (void)
	Initializes syslog.

---

Detailed Description

These functions provide miscellaneous functionality.

---

Function Documentation

U8_EXPORT char* u8_2libc

(

u8_string

string

)

Converts a UTF-8 string to the encoding expected by system (libc) functions.

If the system encoding is UTF-8, this returns its argument, rather than copying it, as u8_tolibc does.

Parameters:

string

a utf-8 string

Returns:

a character string in the local encoding

U8_EXPORT u8_string u8_appid

(

void

)

Returns a UTF-8 string describing the current application for inclusion in messages or other output or logging.

This string is not consed, so it should not be freed.

Returns:

a utf-8 string

U8_EXPORT int u8_config_utf8warn

(

int

flag

)

Sets whether warnings are produced for invalid UTF-8 sequences, which can be annoyingly common with some content.

Parameters:

flag

an int

Returns:

int

U8_EXPORT int u8_default_appid

(

u8_string

id

)

Sets the UTF-8 string describing the current application, unless it has already been set.

This can be used to provide default appids while allowing programs to override the default. This returns 1 if it did anything (no appid had been previously set) or zero otherwise.

Parameters:

id	a utf-8 string

Returns:

int

U8_EXPORT void* u8_dynamic_load

(

u8_string

filename

)

Dynamically loads a named file into the running image.

Parameters:

filename

a utf-8 pathname

Returns:

void

U8_EXPORT double u8_elapsed_time

(

void

)

Returns elapsed time in seconds since some moment after application startup.

Returns:

a double indicating seconds

U8_EXPORT void* u8_extalloc	(	void *	ptr,
		size_t	n,
		size_t	osz
	)

Copies a block of memory into a larger block, zero clearing any new parts.

Parameters:

sz	the number of bytes to allocate

Returns:

void *

U8_EXPORT u8_string u8_fromlibc

(

char *

local_string

)

Converts a natively encoded string into a UTF-8 string.

If the system encoding is UTF-8, this validates and copies the argument.

Parameters:

local_string

a locally encoded text string

Returns:

a utf-8 encoded string

U8_EXPORT u8_string u8_getenv

(

u8_string

envvar

)

Gets a variable specified in the environment.

Parameters:

varname

a variable name

Returns:

a utf-8 string, copied

Gets a variable specified in the environment.

Parameters:

envvar

the variable name, as a UTF-8 string.

Returns:

a utf8 string (converted from the value) or NULL

U8_EXPORT void u8_identify_application

(

u8_string

id

)

Sets the UTF-8 string describing the current application.

Parameters:

id	a utf-8 string

Returns:

void

U8_EXPORT void u8_init_chardata_c

(

void

)

Initializes the full character data table for the libu8 library.

Returns:

void

U8_EXPORT void u8_init_syslog

(

void

)

Initializes syslog.

Returns:

void

U8_EXPORT int u8_initialize

(

void

)

Initializes the core UTF-8 functions (from libu8.h)

Returns:

void

U8_EXPORT int u8_initialize_fns

(

void

)

Initializes UTF-8 miscellaneous functions, including time keeping, file access, network access, and server functions.

Returns:

void

U8_EXPORT int u8_initialize_io

(

void

)

Initializes UTF-8 io functions, including character set conversion and stream I/O.

Returns:

void

U8_EXPORT void u8_initialize_u8stdio

(

void

)

Initializes the messaging functions which use POSIX stdio.

U8_EXPORT void u8_initialize_u8syslog

(

void

)

Initializes the messaging functions which use POSIX syslog.

U8_EXPORT void* u8_mallocz

(

size_t

sz

)

Allocates and zero-clears a block of memory.

Parameters:

sz	the number of bytes to allocate

Returns:

void *

U8_EXPORT void u8_raise	(	u8_condition	ex,
		u8_context	cxt,
		u8_string	details
	)

Signals an error with particular details.

This currently exits, though it may be expanded to an exception throwing architecture in the near future.

Parameters:

ex	a utf-8 condition string (u8_condition)
cxt	a utf-8 context string (a const string)
details	a utf-8 string detailing the error, or NULL

Returns:

void (shouldn't)

U8_EXPORT unsigned int u8_random

(

unsigned int

n

)

Returns a random integer between 0 and n-1 (inclusive)

Parameters:

n	the upper limit for the random number

Returns:

an int between 0 and n-1

U8_EXPORT void u8_randomize

(

unsigned int

seed

)

Sets the random seed value used for the random number generation.

Setting the random seed value to the same value will cause the sequence of numbers generated by u8_random to be the same.

Parameters:

seed	the seed value

Returns:

void

U8_EXPORT void* u8_reallocz	(	void *	ptr,
		size_t	sz,
		size_t	osz
	)

Reallocates a block of memory, zero clearing any new parts.

Parameters:

sz	the number of bytes to allocate

Returns:

void *

U8_EXPORT void u8_set_error_handler

(

void(*)(u8_condition, u8_context, u8_string)

h

)

Sets the function used when an error is raised.

Parameters:

h	is a function on a condition, a context, and a utf-8 string

Returns:

void (shouldn't)

U8_EXPORT void u8_set_libcfns	(	u8_string(*)(char *)	fromfn,
		char *(*)(u8_string)	tofn
	)

This sets the functions used to map to and from libc.

Parameters:

fromfn	a function from character strings to utf-8 strings
tofn	a function from utf-8 strings to character strings.

Returns:

void

U8_EXPORT char* u8_tolibc

(

u8_string

string

)

Converts a UTF-8 string to the encoding expected by system (libc) functions.

If the system encoding is UTF-8, this validates and copies the argument.

Parameters:

string

a utf-8 string

Returns:

a character string in the local encoding