format.c File Reference

A formatting object for displaying binary data in human-readable formats. More...

#include <stdio.h>
#include <limits.h>
#include "../library/lib.h"
#include "./objects.h"

Include dependency graph for format.c:

Go to the source code of this file.

Data Structures
struct	fmt_tag
	The context for the format object. More...

Macros
Private Macros – used internally by the formatting object
#define	MAX_INDENT   80
#define	LINE_LEN   16
#define	LINE_LEN4   4
#define	LINE_LEN8   8
#define	LINE_LEN12   12
#define	FMT_BUFLEN   (128+MAX_INDENT)
#define	FILE_END   ((uint64_t)-1)

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 *ucpBytes, 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

A formatting object for displaying binary data in human-readable formats.

Displaying bytes and Unicode code points which often do not have printing ASCII character counterparts are a common problem with many applications. This object provides a common solution to this problem. It is roughly patterned after the Linux hexdump command. Once the object has been created it can be used as an iterator to display fixed line length displays of the data in several common formats.

• FMT_HEX - 8-bit bytes are displayed as pairs of hexadecimal digits, 16 bytes to a line
• FMT_HEX2 - data is displayed as 16-bit integers, 8 integers to a row. The byte order will depend on the "endianness" of the hardware.
• FMT_ASCII - 8-bit bytes are displayed as characters, 16 characters to a line
  • the ASCII character if printable
  • \t for tab, \n for line feed, \r for carriage return
  • a 3-digit decimal integer otherwise. e.g. 000, 001, 128, 255
• FMT_CANONICAL - same as FMT_HEX but followed by attempted ASCII
  • that is, the ASCII character if printable, a period (.) if not
• FMT_UNICODE - 32-bit data is displayed as 24-bit (6 hexadecimal digit) integers, 8 big-endian integers to a line

Each line is preceded with the 8 hexadecimal digit offset to the first byte of the line. The final line is empty with just the offset to the (empty) byte following the data.

Definition in file format.c.

Macro Definition Documentation

FILE_END

#define FILE_END   ((uint64_t)-1)

Definition at line 62 of file format.c.

FMT_BUFLEN

#define FMT_BUFLEN   (128+MAX_INDENT)

Definition at line 61 of file format.c.

LINE_LEN

#define LINE_LEN   16

Definition at line 57 of file format.c.

LINE_LEN12

#define LINE_LEN12   12

Definition at line 60 of file format.c.

LINE_LEN4

#define LINE_LEN4   4

Definition at line 58 of file format.c.

LINE_LEN8

#define LINE_LEN8   8

Definition at line 59 of file format.c.

MAX_INDENT

#define MAX_INDENT   80

Definition at line 56 of file format.c.

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.