Header for the Unicode UTF encoding module. More...

This graph shows which files directly or indirectly include this file:

Data Structures
struct	conv_src
	Defines the input data type, location and length. More...

struct	conv_dst
	Defines the output data type, location, length and whether or not to preface with a Byte Order Mark (BOM). More...

Macros
Base64 Bits and Masks
#define	BASE64 0x8000
	The base64 bit. Or (\|) with data type for base64 encoding/decoding. More...

#define	BASE64_MASK 0xFF00
	The base64 mask. And (&) with the type to extract the base64 bit, if any. More...

#define	TYPE_MASK 0xFF
	The type mask. And (&) with the type to extract the type, without the base64 bit. More...

The Encoding Type Identifiers
#define	BINARY 4
	Alias for ISO_8895_1. More...

#define	LATIN1 4
	Alias for ISO_8895_1. More...

#define	ISO_8859_1 4
	All 8-bit, single-byte characters. Unicode characters ranging from U+0000 to U+00FF. More...

#define	UTF_8 8
	Data type macro for UTF-8 encoding/decoding. More...

#define	UTF_16 16
	Data type macro for UTF-16 encoding/decoding. More...

#define	UTF_16BE 17
	Data type macro for UTF-16BE encoding/decoding. More...

#define	UTF_16LE 18
	Data type macro for UTF-16LE encoding/decoding. More...

#define	UTF_32 32
	Data type macro for UTF-32 encoding/decoding. More...

#define	UTF_32BE 33
	Data type macro for UTF-32BE encoding/decoding. More...

#define	UTF_32LE 34
	Data type macro for UTF-32LE encoding/decoding. More...

Miscellaneous
#define	UTF_UNKNOWN 40
	Data type macro for unknown encoding type. More...

#define	BOM 1
	The "true" macro for destination BOM flag. More...

#define	NOBOM 0
	The "false" macro for destination BOM flag. More...

#define	BASE64_LF 10
	For configuring base64 destinations, indicates line breaks as line feed (\n, 0x0A). More...

#define	BASE64_CRLF 13
	For configuring base64 destinations, indicates line breaks as carriage return + line feed (\r\n, 0x0D0A). More...

Functions
void *	vpConvCtor (exception *spEx)
	The data conversion object constructor. More...

void	vConvDtor (void *vpCtx)
	Conversion object destructor. More...

void	vConvDecode (void vpCtx, conv_src spSrc)
	Decode a source byte stream to 32-bit Unicode code points. More...

void	vConvEncode (void vpCtx, conv_dst spDst)
	Encode the 32-bit Unicode code points to a byte stream. More...

void	vConvConvert (void vpCtx, conv_src spSrc, conv_dst *spDst)
	Decodes and encodes in a single functions call. More...

void	vConvGetCodePoints (void vpCtx, uint32_t uipData, uint32_t *uipDataLen)
	Access the intermediate 32-bit data following a call to vConvDecode() or vConvUseCodePoints(). More...

void	vConvUseCodePoints (void vpCtx, uint32_t uipSrc, aint uiSrcLen)
	Insert a stream of 32-bit Unicode code points as the intermediate data. More...

void	vConvConfigureBase64 (void *vpCtx, aint uiLineLen, aint uiLineEnd)
	Configures base64 output format. More...

Detailed Description

Header for the Unicode UTF encoding module.

Definition in file conv.h.

Macro Definition Documentation

◆ BASE64

#define BASE64 0x8000

The base64 bit. Or (|) with data type for base64 encoding/decoding.

When or'ed with a data source type identifier, base64 decoding will precede the type decoding.
When or'ed with a data destination type identifier, base64 encoding with follow the type encoding.

Definition at line 44 of file conv.h.

◆ BASE64_CRLF

#define BASE64_CRLF 13

For configuring base64 destinations, indicates line breaks as carriage return + line feed (\r\n, 0x0D0A).

Definition at line 103 of file conv.h.

◆ BASE64_LF

#define BASE64_LF 10

For configuring base64 destinations, indicates line breaks as line feed (\n, 0x0A).

Definition at line 101 of file conv.h.

◆ BASE64_MASK

#define BASE64_MASK 0xFF00

The base64 mask. And (&) with the type to extract the base64 bit, if any.

e.g.

uiType & BASE64_MASK > 0, base64 bit is set
uiType & BASE64_MASK == 0, base64 bit is not set

Definition at line 51 of file conv.h.

◆ BINARY

#define BINARY 4

Alias for ISO_8895_1.

Definition at line 64 of file conv.h.

◆ BOM

#define BOM 1

The "true" macro for destination BOM flag.

Definition at line 97 of file conv.h.

◆ ISO_8859_1

#define ISO_8859_1 4

All 8-bit, single-byte characters. Unicode characters ranging from U+0000 to U+00FF.

For a discussion and mapping of the characters, see the Wikipedia page.

Note: Care must be taken using this as the destination type. Unicode code points > 0xFF will result in an error.

Definition at line 75 of file conv.h.

◆ LATIN1

#define LATIN1 4

Alias for ISO_8895_1.

Definition at line 66 of file conv.h.

◆ NOBOM

#define NOBOM 0

The "false" macro for destination BOM flag.

Definition at line 99 of file conv.h.

◆ TYPE_MASK

#define TYPE_MASK 0xFF

The type mask. And (&) with the type to extract the type, without the base64 bit.

e.g.

uiType & TYPE_MASK is the encode/decode type

Definition at line 58 of file conv.h.

◆ UTF_16

#define UTF_16 16

Data type macro for UTF-16 encoding/decoding.

Definition at line 79 of file conv.h.

◆ UTF_16BE

#define UTF_16BE 17

Data type macro for UTF-16BE encoding/decoding.

Definition at line 81 of file conv.h.

◆ UTF_16LE

#define UTF_16LE 18

Data type macro for UTF-16LE encoding/decoding.

Definition at line 83 of file conv.h.

◆ UTF_32

#define UTF_32 32

Data type macro for UTF-32 encoding/decoding.

Definition at line 85 of file conv.h.

◆ UTF_32BE

#define UTF_32BE 33

Data type macro for UTF-32BE encoding/decoding.

Definition at line 87 of file conv.h.

◆ UTF_32LE

#define UTF_32LE 34

Data type macro for UTF-32LE encoding/decoding.

Definition at line 89 of file conv.h.

◆ UTF_8

#define UTF_8 8

Data type macro for UTF-8 encoding/decoding.

Definition at line 77 of file conv.h.

◆ UTF_UNKNOWN

#define UTF_UNKNOWN 40

Data type macro for unknown encoding type.

Definition at line 95 of file conv.h.

Function Documentation

◆ vConvConfigureBase64()

void vConvConfigureBase64	(	void *	vpCtx,
		aint	uiLineLen,
		aint	uiLineEnd
	)

Configures base64 output format.

The default base64 output has LF (\n) line breaks at 76 characters. This function will modify that output format if called prior to vConvEncode().

Parameters

vpCtx	A pointer to a valid context previously return from vpConvCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
uiLineLen	Break output lines at every uiLineLen characters. If 0 (zero), no line breaks will be added.
uiLineEnd	Must be one of: BASE64_LF for \n line ends BASE64_CRLF for \r\n line breaks.

Definition at line 186 of file conv.c.

◆ vConvConvert()

void vConvConvert	(	void *	vpCtx,
		conv_src *	spSrc,
		conv_dst *	spDst
	)

Decodes and encodes in a single functions call.

Equivalent to calling vConvDecode() and vConvEncode() in succession.

Parameters

	vpCtx	A pointer to a valid context previously return from vpConvCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
	spSrc	Pointer to the source byte stream definition.
[in,out]	spDst	Pointer to the destination byte stream definition.

Definition at line 422 of file conv.c.

◆ vConvDecode()

void vConvDecode	(	void *	vpCtx,
		conv_src *	spSrc
	)

Decode a source byte stream to 32-bit Unicode code points.

Parameters

vpCtx	A pointer to a valid context previously return from vpConvCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
spSrc	Pointer to the source byte stream definition.

Definition at line 205 of file conv.c.

◆ vConvDtor()

void vConvDtor ( void * vpCtx )

Conversion object destructor.

Parameters

vpCtx A pointer to a valid context previously return from vpConvCtor(). Silently ignored if NULL. However, if non-NULL it must be a valid context pointer. The application will silently exit with BAD_CONTEXT exit code if vpCtx is invalid.

Definition at line 161 of file conv.c.

◆ vConvEncode()

void vConvEncode	(	void *	vpCtx,
		conv_dst *	spDst
	)

Encode the 32-bit Unicode code points to a byte stream.

Parameters

vpCtx	A pointer to a valid context previously return from vpConvCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
spDst	Pointer to the destination byte stream definition. Byte stream data remains valid until another call on the context handle vpCtx.

Definition at line 302 of file conv.c.

◆ vConvGetCodePoints()

void vConvGetCodePoints	(	void *	vpCtx,
		uint32_t *	uipData,
		uint32_t *	uipDataLen
	)

Access the intermediate 32-bit data following a call to vConvDecode() or vConvUseCodePoints().

Copies the code points into the caller's array.

if uipData == NULL, the number of code points is returned in *uipDataLen
if uipData != NULL, *uipDataLen is taken as the array length and up to *uipDataLen code points are copied to uipData
- on return if *uipDataLen > than its original value, not all data was copied. Try again with a larger array buffer.
- on return if *uipDataLen <= than its original value all data was copied

Parameters

vpCtx	A pointer to a valid context previously return from vpConvCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
uipData	Pointer to the array to receive the data. If NULL no data is returned but the number of code points is set.
uipDataLen	Pointer to an unsigned integer to receive the number of code points.

Definition at line 361 of file conv.c.

◆ vConvUseCodePoints()

void vConvUseCodePoints	(	void *	vpCtx,
		uint32_t *	uipSrc,
		aint	uiSrcLen
	)

Insert a stream of 32-bit Unicode code points as the intermediate data.

This data provided will be encoded with a call to vConvEncode().

Parameters

vpCtx	A pointer to a valid context previously return from vpConvCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
uipSrc-	pointer to an array of 32-bit Unicode code points.
uiSrcLen	- the number of code points.

Definition at line 395 of file conv.c.

◆ vpConvCtor()

void* vpConvCtor ( exception * spEx )

The data conversion object constructor.

Parameters

spEx	Pointer to a valid exception structure initialized with XCTOR(). If not valid the application will silently exit with a BAD_CONTEXT exit code.

Returns: Pointer to the object context on success. An exception is thrown on failure, which can only be a memory allocation failure.

Definition at line 134 of file conv.c.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ BASE64

◆ BASE64_CRLF

◆ BASE64_LF

◆ BASE64_MASK

◆ BINARY

◆ BOM

◆ ISO_8859_1

◆ LATIN1

◆ NOBOM

◆ TYPE_MASK

◆ UTF_16

◆ UTF_16BE

◆ UTF_16LE

◆ UTF_32

◆ UTF_32BE

◆ UTF_32LE

◆ UTF_8

◆ UTF_UNKNOWN

Function Documentation

◆ vConvConfigureBase64()

◆ vConvConvert()

◆ vConvDecode()

◆ vConvDtor()

◆ vConvEncode()

◆ vConvGetCodePoints()

◆ vConvUseCodePoints()

◆ vpConvCtor()