Library Configuration

Global library configuration.

Text Attributes 🔗

Text attributes are bit flags of type uniattr.

#define UNI_SCALAR 0x1: Unicode scalar value.

#define UNI_UTF8 0x2: UTF-8 encoding form.

#define UNI_UTF16 0x4: UTF-16 encoding form.

#define UNI_UTF32 0x8: UTF-32 encoding form.

#define UNI_BIG 0x10: Big endian byte order.

#define UNI_LITTLE 0x20: Little endian byte order.

#define UNI_NATIVE: Native endian byte order.

#define UNI_TRUST 0x40: Well-formed text.

#define UNI_NULIFY 0x80: Null terminated output.

Types 🔗

typedef uint32_t unichar: Code point.

typedef int32_t unisize: Code unit count.

typedef uint32_t uniattr: Text attributes.

typedef void *(*unimemfunc)(void *user_data, void *ptr, size_t old_size, size_t new_size): Memory allocation function.

typedef void(*unierrfunc)(void *user_data, const char *message): Diagnostic function.

Enumerations 🔗

enum unistat: Status code.

Functions 🔗

void uni_getversion( int32_t *major, int32_t *minor, int32_t *patch): Library version.

void uni_getucdversion( int32_t *major, int32_t *minor, int32_t *patch): Unicode standard version.

unistat uni_setmemfunc( void *user_data, unimemfunc allocf): Custom memory allocator.

void uni_seterrfunc( void *user_data, unierrfunc callback): Receive diagnostic events.

Discussion 🔗

Unicorn defines several foundational types that are used throughout the library. An example would be the unistat type which represents a status code. Most functions in Unicorn return a unistat value making for a consistent approach to error reporting. Global features of the library can be queried and configured at runtime. An example is the uni_setmemfunc function which allows overriding the dynamic allocator used by the library at runtime. All interfaces that are globally applicable to the library are defined here.

Status Codes 🔗

Most functions in Unicorn return an element from the unistat enumeration indicating the success or failure status of an operation. Each function documents the possible status codes it can return. This narrows down which codes a caller must check for.

Dynamic Memory Allocation 🔗

Unicorn is designed with performance in mind and minimizes dynamic memory allocations where possible. In fact, most functions do not allocate memory at all! Functions that can allocate memory are identified by having UNI_NO_MEMORY listed as a potential return value in their documentation.

By default, Unicorn uses the C standard memory allocators (realloc and free) for dynamic memory allocation. Using uni_setmemfunc you can provide your own dynamic memory allocator.

If a dynamic memory allocation fails, then Unicorn will gracefully free all intermediate allocations and return UNI_NO_MEMORY.

Manual