conv.c File Reference

A Unicode encoding/decoding object. More...

#include "../library/lib.h"
#include "./conv.h"

Include dependency graph for conv.c:

Go to the source code of this file.

Data Structures
struct	conv_error
	Defines the value, location and error message when a value is in error and a fatal error is issued. More...
struct	conv
	The conv object context. More...

Macros
Private Macros – used only by the conv object
#define	BASE64_LINE_LEN   76
#define	TAIL_CHAR   61
#define	NON_BYTE_MASK   0xFFFFFF00
#define	BYTE_MASK   0xFF

Functions
void *	vpConvCtor (exception *spEx)
	The data conversion object constructor. More...
void	vConvDtor (void *vpCtx)
	Conversion object destructor. More...
void	vConvConfigureBase64 (void *vpCtx, aint uiLineLen, aint uiLineEnd)
	Configures base64 output format. 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	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	vConvConvert (void *vpCtx, conv_src *spSrc, conv_dst *spDst)
	Decodes and encodes in a single functions call. More...

Detailed Description

A Unicode encoding/decoding object.

This object provides functions for encoding and decoding data represented in the UTF-8, UTF-16 and UTF-32 Unicode formats as well as the ISO 8859-1 format. Care has been taken to observe most (hopefully all) of the Unicode restrictions. Decoding or encoding of values outside the Unicode range is forbidden. That is characters 0xD800 to 0xDFFF and characters greater than 0x10FFFF are forbidden. Over long UTF-8 encodings are also forbidden. For example, encoding 0x7FF in three bytes instead of two is forbidden.

Conversions are done in a two-step process. A source data byte stream is first decoded into an array of 32-bit Unicode code points. This persistent array is then encoded into the destination data byte stream. Functions are available to access the intermediate 32-bit code point data and to insert 32-bit code points directly.

Source and destination byte streams may be base64 encoded.

Definition in file conv.c.

Macro Definition Documentation

BASE64_LINE_LEN

#define BASE64_LINE_LEN   76

Definition at line 56 of file conv.c.

BYTE_MASK

#define BYTE_MASK   0xFF

Definition at line 59 of file conv.c.

NON_BYTE_MASK

#define NON_BYTE_MASK   0xFFFFFF00

Definition at line 58 of file conv.c.

TAIL_CHAR

#define TAIL_CHAR   61

Definition at line 57 of file conv.c.

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.