libu8
Data Structures | Functions
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:
stringa 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:
flagan 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:
ida utf-8 string
Returns:
int
U8_EXPORT void* u8_dynamic_load ( u8_string  filename)

Dynamically loads a named file into the running image.

Parameters:
filenamea 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:
szthe 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_stringa 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:
varnamea variable name
Returns:
a utf-8 string, copied

Gets a variable specified in the environment.

Parameters:
envvarthe 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:
ida 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:
szthe 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:
exa utf-8 condition string (u8_condition)
cxta utf-8 context string (a const string)
detailsa 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:
nthe 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:
seedthe 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:
szthe 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:
his 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:
fromfna function from character strings to utf-8 strings
tofna 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:
stringa utf-8 string
Returns:
a character string in the local encoding