Version 7.0
Copyright © 2021 Lowell D. Thomas
APG
… an ABNF Parser Generator
Functions
utilities.c File Reference

Utility functions code. More...

#include <unistd.h>
#include <limits.h>
#include "./utilities.h"
Include dependency graph for utilities.c:

Go to the source code of this file.

Functions

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...
 
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...
 
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...
 
void vPrintPPPTMap (uint8_t *ucpMap, aint uiBegin, aint uiLength, const char *cpMode)
 
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...
 
acharacpUtilStrToAchar (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_phrasespUtilStrToPhrase (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...
 
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_phrasespUtilStrToPhrase32 (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...
 
abool bUtilAstToXml (void *vpAst, 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

Utility functions code.

Definition in file utilities.c.

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
vpMemPointer to a memory context returned from vpMemCtor();
cpStrPointer to the null-terminated string to convert.
uipLenPointer 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
vpAstPointer to a valid AST context previously returned from vpAstCtor(). If not valid application will silently exit with a BAD_CONTEXT exit code.
cpTypeSelect 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
cpFileNameName 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
vpMemPointer to a valid memory context previously returned from vMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
cpFileLLeft file name.
cpFileRRight 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
cpFileLPointer to left file name.
cpFileRPointer 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
vpMemPointer to a memory context returned from vpMemCtor();
acpAcharPointer to an achar array to convert. May not be NULL.
uiLenThe 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
uiIdThe 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
vpMemPointer to a memory context returned from vpMemCtor();
spPhrasePointer 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
vpMemPointer to a memory context returned from vpMemCtor();
spPhrasePointer 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
cCharThe character to represent
cpBufPointer 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
uiCharThe character to represent
cpBufPointer 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
luiTrueThe 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
vpMemPointer to a memory context returned from vpMemCtor();
uipUintPointer to a 32-bit unsigned integer array to convert. May not be NULL.
uiLenThe 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:

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
vpMemPointer to a memory context returned from vpMemCtor();
cpStrPointer 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
vpMemPointer to a memory context returned from vpMemCtor();
cpStrPointer 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
vpMemPointer to a memory context returned from vpMemCtor();
cpStrPointer to the null-terminated string to convert.
uipLenPointer 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.

◆ vPrintPPPTMap()

void vPrintPPPTMap ( uint8_t *  ucpMap,
aint  uiBegin,
aint  uiLength,
const char *  cpMode 
)

Definition at line 758 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
spFileThe open file handle to print to. If NULL, stdout will be used.
acpCharsThe string of alphabet characters to interpret.
uiLengthThe 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
spExPointer to a valid exception structure. If not valid application will silently exit with a BAD_CONTEXT exit code.
cpStringPointer to a null-terminated string whose line ends to translate. May not be NULL or empty.
cpEndPointer 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.
cpFileNameName 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
vpMemPointer to a valid memory context previously returned from vMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
cpFileNameRelative or absolute path name of the file to read into.
ucpDataPointer to the caller's 8-bit byte data buffer. If NULL, no data is read.
[in,out]uipLenPointer 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
vpMemPointer to a valid memory context previously returned from vMemCtor(). If invalid the application will silently exit with a BAD_CONTEXT exit code.
cpFileNameRelative or absolute path name of the file to write.
ucpDataPointer to the caller's 8-bit byte data array.
uiLenLength, 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
spFileThe open file handle to print to. If NULL, stdout will be used.
uiIndentThe 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
spExPointer 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
spLinePointer 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
spLinePointer 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
spStatsPointer 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
vpMsgsPointer 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
spStatePointer 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
spStatsPointer 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.

APG Version 7.0 is licensed under the 2-Clause BSD License,
an Open Source Initiative Approved License.