Miscellaneous utility functions. More...

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

Include dependency graph for utilities.h:

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

Functions
System Information
void	vUtilApgInfo (void)
	Display the current state of apg.h. More...

void	vUtilSizes (void)
	Display the APG type sizes, the compiler's C-language type sizes and a few max values. More...

void	vUtilCurrentWorkingDirectory (void)
	Display the current working directory. More...

File Utilities
void	vUtilFileWrite (void vpMem, const char cpFileName, uint8_t *ucpData, aint uiLen)
	Write from the caller's data area to the given file name. More...

void	vUtilFileRead (void vpMem, const char cpFileName, uint8_t ucpData, aint uipLen)
	Read a file into the caller's data area. More...

abool	bUtilCompareFiles (const char cpFileL, const char cpFileR)
	Compare two files, byte for byte. More...

abool	bUtilCompareFileLines (void vpMem, const char cpFileL, const char *cpFileR)
	Compare two text files, line by line, without regard for the line ending characters. More...

Pretty Printing Utilities
void	vUtilPrintException (exception *spEx)
	Prints exception information from an exception structure. More...

void	vUtilPrintMemStats (const mem_stats *spStats)
	Display the memory object's statistics. More...

void	vUtilPrintVecStats (const vec_stats *spStats)
	Display the vector object's statistics. More...

void	vUtilPrintLine (line *spLine)
	Display one line from a line object. More...

void	vUtilPrintLineu (line_u *spLine)
	Display one line from a line_u object. More...

char *	cpUtilPrintChar (char cChar, char *cpBuf)
	Generates a string representation for a single character. More...

char *	cpUtilPrintUChar (uint32_t uiChar, char *cpBuf)
	Generates a string representation for a single Unicode character. More...

const char *	cpUtilUtfTypeName (aint uiType)
	Convert a conversion type identifier to a readable, printable ASCII string. Conversion type identifiers: More...

const char *	cpUtilTrueFalse (luint luiTrue)
	Return a human-readable string version of the given value in its true/false sense. More...

const char *	cpUtilOpName (aint uiId)
	Convert an opcode identifier to a human-readable opcode name. More...

void	vUtilPrintParserState (parser_state *spState)
	Display the parser state in human-readable format to stdout. More...

void	vUtilPrintMsgs (void *vpMsgs)
	Display the list of messages in a message object to stdout. More...

apg_phrase Utilities
achar *	acpUtilStrToAchar (void vpMem, const char cpStr, aint *uipLen)
	Convert a null-terminated ASCII string to an array of achar characters. More...

const char *	cpUtilAcharToStr (void vpMem, achar acpAchar, aint uiLen)
	Convert an array of achar characters to a null-terminated ASCII string. More...

apg_phrase *	spUtilStrToPhrase (void vpMem, const char cpStr)
	Convert a null-terminated ASCII string to an apg_phrase. More...

const char *	cpUtilPhraseToStr (void vpMem, apg_phrase spPhrase)
	Convert an apg_phrase to a null-terminated ASCII string. More...

Unicode u32_phrase Utilities
uint32_t *	uipUtilStrToUint32 (void vpMem, const char cpStr, aint *uipLen)
	Convert a null-terminated ASCII string to an array of 32-bit unsigned integers. More...

const char *	cpUtilUint32ToStr (void vpMem, const uint32_t uipUint, aint uiLen)
	Convert an array of 32-bit unsigned integers to a null-terminated ASCII string. More...

u32_phrase *	spUtilStrToPhrase32 (void vpMem, const char cpStr)
	Convert a null-terminated ASCII string to a 32-bit phrase. More...

const char *	cpUtilPhrase32ToStr (void vpMem, u32_phrase spPhrase)
	Convert an u32_phrase to a null-terminated ASCII string. More...

Odd Jobs
void	vUtilIndent (FILE *spFile, aint uiIndent)
	Indent by adding the given number of spaces to the output file. More...

void	vUtilCharsToAscii (FILE spFile, const achar acpChars, aint uiLength)
	Convert a string of alphabet characters to printable ASCII. More...

abool	bUtilAstToXml (void vpCtx, char cpType, const char *cpFileName)
	Convert the AST records to XML format. More...

void	vUtilConvertLineEnds (exception spEx, const char cpString, const char cpEnd, const char cpFileName)
	Convert all line ending characters. More...

Detailed Description

Miscellaneous utility functions.

Definition in file utilities.h.

Function Documentation

◆ acpUtilStrToAchar()

achar* acpUtilStrToAchar	(	void *	vpMem,
		const char *	cpStr,
		aint *	uipLen
	)

Convert a null-terminated ASCII string to an array of achar characters.

This function will allocate memory for the array, relieving the caller of the allocation burden. The allocated memory may be freed with vMemFree( acpBuf ), where acpBuf is the returned pointer. However, the allocated memory will also be freed with vMemDtor() which every application should call for memory clean up anyway.

Parameters

vpMem	Pointer to a memory context returned from vpMemCtor();
cpStr	Pointer to the null-terminated string to convert.
uipLen	Pointer to an unsigned integer to receive the number of characters in the converted achar array.

Returns: Returns a pointer to the converted achar array. Returns the number of characters in the array if uipLen != NULL.

Definition at line 824 of file utilities.c.

◆ bUtilAstToXml()

abool bUtilAstToXml	(	void *	vpAst,
		char *	cpType,
		const char *	cpFileName
	)

Convert the AST records to XML format.

Parameters

vpAst	Pointer to a valid AST context previously returned from vpAstCtor(). If not valid application will silently exit with a BAD_CONTEXT exit code.
cpType	Select the character type for the parsed phrases: "u" or "U" for Unicode "h" or "H" for hexadecimal characters "d" or "D" for decimal characters default (NULL or none of the above) decimal characters
cpFileName	Name of the file to convert to. If NULL, stdout is used.

Definition at line 1126 of file utilities.c.

◆ bUtilCompareFileLines()

abool bUtilCompareFileLines	(	void *	vpMem,
		const char *	cpFileL,
		const char *	cpFileR
	)

Compare two text files, line by line, without regard for the line ending characters.

Developed for the problem of comparing files which are identical except for the line end characters. Necessitated by the different line ending conventions of different OSs.

Parameters

vpMem	Pointer to a valid memory context previously returned from vMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
cpFileL	Left file name.
cpFileR	Right file name.

Returns: True if all lines are identical. False otherwise.

Definition at line 350 of file utilities.c.

◆ bUtilCompareFiles()

abool bUtilCompareFiles	(	const char *	cpFileL,
		const char *	cpFileR
	)

Compare two files, byte for byte.

Parameters

cpFileL	Pointer to left file name.
cpFileR	Pointer to right file name.

Returns: True if both files are byte-for-byte equal. False if not equal or if either file does not exist or otherwise cannot be opened.

Definition at line 306 of file utilities.c.

◆ cpUtilAcharToStr()

const char* cpUtilAcharToStr	(	void *	vpMem,
		achar *	acpAchar,
		aint	uiLen
	)

Convert an array of achar characters to a null-terminated ASCII string.

Any achar characters that are not valid printing ASCII characters will be represented with a period ('.' or 46).

This function will allocate memory for the string, relieving the caller of the allocation burden. The allocated memory may be freed with vMemFree(cpStr), where cpStr is the returned pointer. However, the allocated memory will also be freed with vMemDtor() which every application should call for memory clean up anyway.

Parameters

vpMem	Pointer to a memory context returned from vpMemCtor();
acpAchar	Pointer to an achar array to convert. May not be NULL.
uiLen	The number of characters in the acpAchar array.

Returns: Returns a pointer to the converted, null-terminated string.

Definition at line 857 of file utilities.c.

◆ cpUtilOpName()

const char* cpUtilOpName ( aint uiId )

Convert an opcode identifier to a human-readable opcode name.

Parameters

uiId	The opcode identifier to convert.

Returns: Pointer to the opcode name.

Definition at line 659 of file utilities.c.

◆ cpUtilPhrase32ToStr()

const char* cpUtilPhrase32ToStr	(	void *	vpMem,
		u32_phrase *	spPhrase
	)

Convert an u32_phrase to a null-terminated ASCII string.

Any u32_phrase characters that are not valid printing ASCII characters will be represented with a period ('.' or 46).

This function will allocate memory for the string, relieving the caller of the allocation burden. For a simpler solution with less overhead but with risk of buffer overrun, see cpPhraseToStr() in tools.c. The allocated memory may be freed with vMemFree(cpStr), where cpStr is the returned pointer. However, the allocated memory will also be freed with vMemDtor() which every application should call for memory clean up anyway.

Parameters

vpMem	Pointer to a memory context returned from vpMemCtor();
spPhrase	Pointer to the u32_phrase to convert. May not be NULL.

Returns: Returns a pointer to the converted, null-terminated string.

Definition at line 1065 of file utilities.c.

◆ cpUtilPhraseToStr()

const char* cpUtilPhraseToStr	(	void *	vpMem,
		apg_phrase *	spPhrase
	)

Convert an apg_phrase to a null-terminated ASCII string.

Any apg_phrase characters that are not valid printing ASCII characters will be represented with a period ('.' or 46).

This function will allocate memory for the string, relieving the caller of the allocation burden. For a simpler solution with less overhead but with risk of buffer overrun, see cpPhraseToStr() in tools.c. The allocated memory may be freed with vMemFree(cpStr), where cpStr is the returned pointer. However, the allocated memory will also be freed with vMemDtor() which every application should call for memory clean up anyway.

Parameters

vpMem	Pointer to a memory context returned from vpMemCtor();
spPhrase	Pointer to the apg_phrase to convert. May not be NULL.

Returns: Returns a pointer to the converted, null-terminated string.

Definition at line 925 of file utilities.c.

◆ cpUtilPrintChar()

char* cpUtilPrintChar	(	char	cChar,
		char *	cpBuf
	)

Generates a string representation for a single character.

Parameters

cChar	The character to represent
cpBuf	Pointer to a character buffer that must be at least 5 characters in length

Returns: a pointer to cpBuf;

Definition at line 504 of file utilities.c.

◆ cpUtilPrintUChar()

char* cpUtilPrintUChar	(	uint32_t	uiChar,
		char *	cpBuf
	)

Generates a string representation for a single Unicode character.

Parameters

uiChar	The character to represent
cpBuf	Pointer to a character buffer that must be at least 11 characters in length

Returns: a pointer to cpBuf;

Definition at line 539 of file utilities.c.

◆ cpUtilTrueFalse()

const char* cpUtilTrueFalse ( luint luiTrue )

Return a human-readable string version of the given value in its true/false sense.

Parameters

luiTrue The value to display.

Returns: Pointer to the true/false string.

Definition at line 646 of file utilities.c.

◆ cpUtilUint32ToStr()

const char* cpUtilUint32ToStr	(	void *	vpMem,
		const uint32_t *	uipUint,
		aint	uiLen
	)

Convert an array of 32-bit unsigned integers to a null-terminated ASCII string.

Any 32-bit unsigned integers that are not valid printing ASCII characters will be represented with a period ('.' or 46).

This function will allocate memory for the string, relieving the caller of the allocation burden. For a simpler solution with less overhead but with risk of buffer overrun, see cpUint32ToStr() in tools.c. The allocated memory may be freed with vMemFree(cpStr), where cpStr is the returned pointer. However, the allocated memory will also be freed with vMemDtor() which every application should call for memory clean up anyway.

Parameters

vpMem	Pointer to a memory context returned from vpMemCtor();
uipUint	Pointer to a 32-bit unsigned integer array to convert. May not be NULL.
uiLen	The number of characters in the uipUint array.

Returns: Returns a pointer to the converted, null-terminated string.

Definition at line 997 of file utilities.c.

◆ cpUtilUtfTypeName()

const char* cpUtilUtfTypeName ( aint uiType )

Convert a conversion type identifier to a readable, printable ASCII string. Conversion type identifiers:

BINARY
UTF_8
UTF_16
UTF_16BE
UTF_16LE
UTF_32
UTF_32BE
UTF_32LE Any of which may be "ORed" with the base64 mask, BASE64.
Parameters

uiType The type to convert. May or may not include the base64 bit.

Returns
Pointer to the ASCII string representation.

Definition at line 607 of file utilities.c.

◆ spUtilStrToPhrase()

apg_phrase* spUtilStrToPhrase	(	void *	vpMem,
		const char *	cpStr
	)

Convert a null-terminated ASCII string to an apg_phrase.

This function will allocate memory for the apg_phrase, relieving the caller of the allocation burden. For a simpler solution with less overhead but with risk of buffer overrun, see acpStrToPhrase() in tools.c. The allocated memory may be freed with vMemFree( spPhrase ), where spPhrase is the returned pointer. However, the allocated memory will also be freed with vMemDtor() which every application should call for memory clean up anyway.

Parameters

vpMem	Pointer to a memory context returned from vpMemCtor();
cpStr	Pointer to the null-terminated string to convert.

Returns: Returns a pointer to the converted apg_phrase.

Definition at line 891 of file utilities.c.

◆ spUtilStrToPhrase32()

u32_phrase* spUtilStrToPhrase32	(	void *	vpMem,
		const char *	cpStr
	)

Convert a null-terminated ASCII string to a 32-bit phrase.

This function will allocate memory for the phrase, relieving the caller of the allocation burden. For a simpler solution with less overhead but with risk of buffer overrun, see acpStrToPhrase32() in tools.c. The allocated memory may be freed with vMemFree( spPhrase ), where spPhrase is the returned pointer. However, the allocated memory will also be freed with vMemDtor() which every application should call for memory clean up anyway.

Parameters

vpMem	Pointer to a memory context returned from vpMemCtor();
cpStr	Pointer to the null-terminated string to convert.

Returns: Returns a pointer to the converted 32-bit phrase.

Definition at line 1031 of file utilities.c.

◆ uipUtilStrToUint32()

uint32_t* uipUtilStrToUint32	(	void *	vpMem,
		const char *	cpStr,
		aint *	uipLen
	)

Convert a null-terminated ASCII string to an array of 32-bit unsigned integers.

This function will allocate memory for the array, relieving the caller of the allocation burden. For a simpler solution with less overhead but with risk of buffer overrun, see uipStrToUint32() in tools.c. The allocated memory may be freed with vMemFree(acpBuf), where acpBuf is the returned pointer. However, the allocated memory will also be freed with vMemDtor() which every application should call for memory clean up anyway.

Parameters

vpMem	Pointer to a memory context returned from vpMemCtor();
cpStr	Pointer to the null-terminated string to convert.
uipLen	Pointer to an unsigned integer to receive the number of characters in the converted achar array.

Returns

Returns a pointer to the converted 32-bit unsigned integer array.

Returns the number of integers in the array if uipLen != NULL.

Definition at line 963 of file utilities.c.

◆ vUtilApgInfo()

void vUtilApgInfo ( void )

Display the current state of apg.h.

Definition at line 60 of file utilities.c.

◆ vUtilCharsToAscii()

void vUtilCharsToAscii	(	FILE *	spFile,
		const achar *	acpChars,
		aint	uiLength
	)

Convert a string of alphabet characters to printable ASCII.

Parameters

spFile	The open file handle to print to. If NULL, stdout will be used.
acpChars	The string of alphabet characters to interpret.
uiLength	The number of alphabet characters in the string.

Definition at line 790 of file utilities.c.

◆ vUtilConvertLineEnds()

void vUtilConvertLineEnds	(	exception *	spEx,
		const char *	cpString,
		const char *	cpEnd,
		const char *	cpFileName
	)

Convert all line ending characters.

Line ending are \r\n, \n or \r (CRLF, LF or CR) (0x0D0A, 0x0A or 0x0D). This function will replace any of these line end forms with the cpEnd string. The cpEnd string will also end the last line, even if the input string has no final line ending.

Parameters

spEx	Pointer to a valid exception structure. If not valid application will silently exit with a BAD_CONTEXT exit code.
cpString	Pointer to a null-terminated string whose line ends to translate. May not be NULL or empty.
cpEnd	Pointer to a null-terminated string of characters to add to the end of each line. NOTE: Normally this will be one of the common line ending strings, "\\r\\n", "\\n" or "\\r". However, there is no restriction here. Any string can be used. If NULL or empty, all line endings in the input string will be removed.
cpFileName	Name of the converted file. If NULL, stdout is used.

Definition at line 1228 of file utilities.c.

◆ vUtilCurrentWorkingDirectory()

void vUtilCurrentWorkingDirectory ( void )

Display the current working directory.

Definition at line 191 of file utilities.c.

◆ vUtilFileRead()

void vUtilFileRead	(	void *	vpMem,
		const char *	cpFileName,
		uint8_t *	ucpData,
		aint *	uipLen
	)

Read a file into the caller's data area.

Parameters

	vpMem	Pointer to a valid memory context previously returned from vMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
	cpFileName	Relative or absolute path name of the file to read into.
	ucpData	Pointer to the caller's 8-bit byte data buffer. If NULL, no data is read.
[in,out]	uipLen	Pointer to the integer to receive the number of bytes in the file. On input, this is the length of the caller's data buffer. Data, up to this length, will be read into the buffer. Regardless of its value on input, it will be set to the actual number of bytes in the file on output. On return, if uipLen is <= its original value then the caller can be confident that all data is in the buffer provided. If uipLen > its original value, then the caller must repeat the call with a larger data buffer.

Returns: Throws exception on file open or read error.

Definition at line 252 of file utilities.c.

◆ vUtilFileWrite()

void vUtilFileWrite	(	void *	vpMem,
		const char *	cpFileName,
		uint8_t *	ucpData,
		aint	uiLen
	)

Write from the caller's data area to the given file name.

Parameters

vpMem	Pointer to a valid memory context previously returned from vMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
cpFileName	Relative or absolute path name of the file to write.
ucpData	Pointer to the caller's 8-bit byte data array.
uiLen	Length, or number of bytes in the data array.

Returns: Throws exceptions on file open and write errors.

Definition at line 210 of file utilities.c.

◆ vUtilIndent()

void vUtilIndent	(	FILE *	spFile,
		aint	uiIndent
	)

Indent by adding the given number of spaces to the output file.

Parameters

spFile	The open file handle to print to. If NULL, stdout will be used.
uiIndent	The number of spaces to indent.

Definition at line 774 of file utilities.c.

◆ vUtilPrintException()

void vUtilPrintException ( exception * spEx )

Prints exception information from an exception structure.

Parameters

spEx	Pointer to a valid exception structure.

Definition at line 415 of file utilities.c.

◆ vUtilPrintLine()

void vUtilPrintLine ( line * spLine )

Display one line from a line object.

Parameters

spLine Pointer to a line structure returned from spLinesFirst() or spLinesNext();

Definition at line 464 of file utilities.c.

◆ vUtilPrintLineu()

void vUtilPrintLineu ( line_u * spLine )

Display one line from a line_u object.

Parameters

spLine Pointer to a line_u structure returned from spLinesuFirst() or spLinesuNext();

Definition at line 483 of file utilities.c.

◆ vUtilPrintMemStats()

void vUtilPrintMemStats ( const mem_stats * spStats )

Display the memory object's statistics.

Parameters

spStats Pointer to a memory statistics structure, returned from vMemStats().

Definition at line 427 of file utilities.c.

◆ vUtilPrintMsgs()

void vUtilPrintMsgs ( void * vpMsgs )

Display the list of messages in a message object to stdout.

Parameters

vpMsgs Pointer to a valid message log object. Previously returned from vpMsgsCtor(). If not valid application will silently exit with a BAD_CONTEXT exit code.

Definition at line 747 of file utilities.c.

◆ vUtilPrintParserState()

void vUtilPrintParserState ( parser_state * spState )

Display the parser state in human-readable format to stdout.

Parameters

spState Pointer to the parser's state returned from vParserParse().

Definition at line 727 of file utilities.c.

◆ vUtilPrintVecStats()

void vUtilPrintVecStats ( const vec_stats * spStats )

Display the vector object's statistics.

Parameters

spStats Pointer to a vector statistics structure, returned from vVecStats().

Definition at line 440 of file utilities.c.

◆ vUtilSizes()

void vUtilSizes ( void )

Display the APG type sizes, the compiler's C-language type sizes and a few max values.

Definition at line 153 of file utilities.c.

Functions

Detailed Description

Function Documentation

◆ acpUtilStrToAchar()

◆ bUtilAstToXml()

◆ bUtilCompareFileLines()

◆ bUtilCompareFiles()

◆ cpUtilAcharToStr()

◆ cpUtilOpName()

◆ cpUtilPhrase32ToStr()

◆ cpUtilPhraseToStr()

◆ cpUtilPrintChar()

◆ cpUtilPrintUChar()

◆ cpUtilTrueFalse()

◆ cpUtilUint32ToStr()

◆ cpUtilUtfTypeName()

◆ spUtilStrToPhrase()

◆ spUtilStrToPhrase32()

◆ uipUtilStrToUint32()

◆ vUtilApgInfo()

◆ vUtilCharsToAscii()

◆ vUtilConvertLineEnds()

◆ vUtilCurrentWorkingDirectory()

◆ vUtilFileRead()

◆ vUtilFileWrite()

◆ vUtilIndent()

◆ vUtilPrintException()

◆ vUtilPrintLine()

◆ vUtilPrintLineu()

◆ vUtilPrintMemStats()

◆ vUtilPrintMsgs()

◆ vUtilPrintParserState()

◆ vUtilPrintVecStats()

◆ vUtilSizes()