format.h File Reference

Header file for the formatting object. More...

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

Go to the source code of this file.

Macros
Format Style Identifiers
#define	FMT_HEX   0
	Display lines of single 8-bit hexadecimal bytes. More...
#define	FMT_HEX2   1
	Display lines of 16-bit hexadecimal integers. More...
#define	FMT_ASCII   2
	Display lines of single 8-bit characters. More...
#define	FMT_CANONICAL   3
	Display lines with both FMT_HEX and FMT_ASCII formats. More...
#define	FMT_UNICODE   4
	Display lines of 24-bit integers. More...

Functions
void *	vpFmtCtor (exception *spEx)
	The object constructor. More...
void	vFmtDtor (void *vpCtx)
	The object destructor. More...
abool	bFmtValidate (void *vpCtx)
	Validate a format context pointer. More...
void	vFmtIndent (void *vpCtx, int iIndent)
	Set the an indentation for the display. More...
const char *	cpFmtFirstBytes (void *vpCtx, const uint8_t *ucpChars, uint64_t uiLength, int iStyle, uint64_t uiOffset, uint64_t uiLimit)
	Initiate the iterator over an array of 8-bit byte data. More...
const char *	cpFmtFirstFile (void *vpCtx, const char *cpFileName, int iStyle, uint64_t uiOffset, uint64_t uiLimit)
	Initiate the iterator over file of 8-bit byte data. More...
const char *	cpFmtFirstUnicode (void *vpCtx, const uint32_t *uipChars, uint64_t uiLength, uint64_t uiOffset, uint64_t uiLimit)
	Initiate the iterator over an array of 32-bit Unicode code points. More...
const char *	cpFmtNext (void *vpCtx)
	Formats the next line of data. More...

Detailed Description

Header file for the formatting object.

Definition in file format.h.

Macro Definition Documentation

FMT_ASCII

#define FMT_ASCII   2

Display lines of single 8-bit characters.

ASCII characters are displayed when possible. Otherwise the 3-digit decimal value is displayed.

Definition at line 51 of file format.h.

FMT_CANONICAL

#define FMT_CANONICAL   3

Display lines with both FMT_HEX and FMT_ASCII formats.

Definition at line 55 of file format.h.

FMT_HEX

#define FMT_HEX   0

Display lines of single 8-bit hexadecimal bytes.

Definition at line 42 of file format.h.

FMT_HEX2

#define FMT_HEX2   1

Display lines of 16-bit hexadecimal integers.

Definition at line 45 of file format.h.

FMT_UNICODE

#define FMT_UNICODE   4

Display lines of 24-bit integers.

Definition at line 59 of file format.h.

Function Documentation

bFmtValidate()

abool bFmtValidate

(

void *

vpCtx

)

Validate a format context pointer.

Parameters

vpCtx

A pointer to a possibly valid format context previously return from vpFmtCtor().

Returns

True if valid. False otherwise.

Definition at line 167 of file format.c.

cpFmtFirstBytes()

const char* cpFmtFirstBytes	(	void *	vpCtx,
		const uint8_t *	ucpBytes,
		uint64_t	uiLength,
		int	iStyle,
		uint64_t	uiOffset,
		uint64_t	uiLimit
	)

Initiate the iterator over an array of 8-bit byte data.

Parameters

vpCtx	- Pointer to a valid object context, previously returned from vpFmtCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
ucpBytes	- Pointer to the array of bytes to display. Cannot be NULL.
uiLength	- The number of bytes in the array. Cannot be 0.
iStyle	- The display style identifier. Any of these except FMT_UNICODE. default - invalid types default to FMT_HEX
uiOffset	- If > 0, this is the offset to the first byte do display.
uiLimit	- If > 0, this is the maximum number of bytes to display.

Returns

Pointer to a string representing the first display line.

Definition at line 210 of file format.c.

cpFmtFirstFile()

const char* cpFmtFirstFile	(	void *	vpCtx,
		const char *	cpFileName,
		int	iStyle,
		uint64_t	uiOffset,
		uint64_t	uiLimit
	)

Initiate the iterator over file of 8-bit byte data.

Parameters

vpCtx	- Pointer to a valid object context, previously returned from vpFmtCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
cpFileName	- Name of the file whose bytes to display.
iStyle	- The display style identifier. Any of these except FMT_UNICODE. default - invalid types default to FMT_HEX
uiOffset	- If > 0, this is the offset to the first byte do display.
uiLimit	- If > 0, this is the maximum number of bytes to display.

Returns

Pointer to a string representing the first display line. Exception thrown on file open failure.

Definition at line 271 of file format.c.

cpFmtFirstUnicode()

const char* cpFmtFirstUnicode	(	void *	vpCtx,
		const uint32_t *	uipChars,
		uint64_t	uiLength,
		uint64_t	uiOffset,
		uint64_t	uiLimit
	)

Initiate the iterator over an array of 32-bit Unicode code points.

Will actually work for any 32-bit unsigned integers. It will display values in the surrogate pair range. However, values outside the range (> 0xFFFFFF) will result in a distorted display.

Parameters

vpCtx	- Pointer to a valid object context, previously returned from vpFmtCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
uipChars	- Pointer to the 32-bit data array.
uiLength	- The number of code points in the arry.
uiOffset	- If > 0, this is the offset to the first code point do display.
uiLimit	- If > 0, this is the maximum number of code points to display.

Returns

Pointer to a string representing the first line of data.

Definition at line 341 of file format.c.

cpFmtNext()

const char* cpFmtNext

(

void *

vpCtx

)

Formats the next line of data.

Parameters

vpCtx

- Pointer to a valid object context, previously returned from vpFmtCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.

Returns

Pointer to a string representing the next line of data. NULL if the end of data has been reached.

Definition at line 386 of file format.c.

vFmtDtor()

void vFmtDtor

(

void *

vpCtx

)

The object destructor.

Closes any open files, frees all memory associated with this object. Clears the context to prevent accidental reuse attempts.

Parameters

vpCtx

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

Definition at line 146 of file format.c.

vFmtIndent()

void vFmtIndent	(	void *	vpCtx,
		int	iIndent
	)

Set the an indentation for the display.

Parameters

vpCtx	A pointer to a valid format context previously return from vpFmtCtor(). If not valid the application will silently exit with a BAD_CONTEXT exit code.
iIndent	- The number of spaces to indent before displaying each line. The value is truncated to the range 0 <= iIndent <= MAX_INDENT.

Definition at line 181 of file format.c.

vpFmtCtor()

void* vpFmtCtor

(

exception *

spEx

)

The 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.

Definition at line 118 of file format.c.