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

A few commonly used functions. More...

#include "lib.h"
Include dependency graph for tools.c:

Go to the source code of this file.

Functions

int iStriCmp (const char *cpLeft, const char *cpRight)
 Compare two strings. A case-insensitive version of strcmp(). More...
 
abool bIsBigEndian (void)
 Determine if the current machine uses big endian word storage. More...
 
abool bMultiplyLong (luint luiL, luint luiR, luint *luipA)
 Multiply two long unsigned integers with overflow notification. More...
 
abool bSumLong (luint uiL, luint uiR, luint *uipA)
 Add two long unsigned integers with overflow notification. More...
 
abool bMultiply32 (uint32_t uiL, uint32_t uiR, uint32_t *uipA)
 Multiply two 32-bit unsigned integers with overflow notification. More...
 
abool bSum32 (uint32_t uiL, uint32_t uiR, uint32_t *uipA)
 Sum two 32-bit unsigned integers with overflow notification. More...
 
abool bMultiply (aint uiL, aint uiR, aint *uipA)
 Multiply two APG unsigned integers with overflow notification. More...
 
abool bSum (aint uiL, aint uiR, aint *uipA)
 Sum two unsigned integers with overflow notification. More...
 
apg_phrasespStrToPhrase (const char *cpStr, apg_phrase *spPhrase)
 Convert an ASCII, null-terminated string to an achar phrase. More...
 
char * cpPhraseToStr (apg_phrase *spPhrase, char *cpStr)
 Convert a phrase of achar characters to a null-terminated ASCII string. More...
 
abool bIsPhraseAscii (apg_phrase *spPhrase)
 Determine if a phrase consists entirely of printable ASCII characters. More...
 
uint32_t * uipStrToUint32 (const char *cpStr, uint32_t *uipBuf, aint *uipLen)
 Convert an ASCII, null-terminated string to an 32-bit unsigned integer array. More...
 
char * cpUint32ToStr (uint32_t *uipBuf, aint uiLen, char *cpStr)
 Convert an array of 32-bit unsigned integers to a null-terminated ASCII string. More...
 
u32_phrase sStrToPhrase32 (const char *cpStr, uint32_t *uipBuf)
 Convert an ASCII, null-terminated string to a 32-bit phrase. More...
 
char * cpPhrase32ToStr (u32_phrase *spPhrase, char *cpStr)
 Convert a 32-bit phrase to a null-terminated ASCII string. More...
 
abool bIsPhrase32Ascii (u32_phrase *spPhrase)
 Determine if a 32-bit phrase consists entirely of printable ASCII characters. More...
 

Detailed Description

A few commonly used functions.

Definition in file tools.c.

Function Documentation

◆ bIsBigEndian()

abool bIsBigEndian ( void  )

Determine if the current machine uses big endian word storage.

Definition at line 96 of file tools.c.

◆ bIsPhrase32Ascii()

abool bIsPhrase32Ascii ( u32_phrase spPhrase)

Determine if a 32-bit phrase consists entirely of printable ASCII characters.

When displaying a phrase it is often convenient to use the C-language string functions if possible. This function will tell when that is possible.

Parameters
spPhraseThe 32-bit phrase to check. It may not be NULL or have a NULL character pointer.
Returns
True if the string consists entirely of printable ASCII characters. False otherwise.

Definition at line 405 of file tools.c.

◆ bIsPhraseAscii()

abool bIsPhraseAscii ( apg_phrase spPhrase)

Determine if a phrase consists entirely of printable ASCII characters.

When displaying a phrase it is often convenient to use the C-language string functions if possible. This function will tell when that is possible.

Parameters
spPhraseThe phrase to check. It may not be NULL or have a NULL character pointer.
Returns
True if the string consists entirely of printable ASCII characters. False otherwise.

Definition at line 287 of file tools.c.

◆ bMultiply()

abool bMultiply ( aint  uiL,
aint  uiR,
aint uipA 
)

Multiply two APG unsigned integers with overflow notification.

Parameters
uiLleft factor
uiRright factor
uipApointer to the product
Returns
APG_FAILURE if the multiplication results in integer overflow, APG_SUCCESS otherwise.

Definition at line 189 of file tools.c.

◆ bMultiply32()

abool bMultiply32 ( uint32_t  uiL,
uint32_t  uiR,
uint32_t *  uipA 
)

Multiply two 32-bit unsigned integers with overflow notification.

Parameters
uiLleft factor
uiRright factor
uipApointer to the product
Returns
APG_FAILURE if the multiplication results in integer overflow, APG_SUCCESS otherwise.

Definition at line 150 of file tools.c.

◆ bMultiplyLong()

abool bMultiplyLong ( luint  luiL,
luint  luiR,
luint luipA 
)

Multiply two long unsigned integers with overflow notification.

Parameters
luiLleft factor
luiRright factor
luipApointer to the product
Returns
APG_FAILURE if the multiplication results in integer overflow, APG_SUCCESS otherwise.

Definition at line 110 of file tools.c.

◆ bSum()

abool bSum ( aint  uiL,
aint  uiR,
aint uipA 
)

Sum two unsigned integers with overflow notification.

Parameters
uiLleft term
uiRright term
uipApointer to the sum
Returns
APG_FAILURE if the addition results in integer overflow, APG_SUCCESS otherwise.

Definition at line 209 of file tools.c.

◆ bSum32()

abool bSum32 ( uint32_t  uiL,
uint32_t  uiR,
uint32_t *  uipA 
)

Sum two 32-bit unsigned integers with overflow notification.

Parameters
uiLleft term
uiRright term
uipApointer to the sum
Returns
APG_FAILURE if the addition results in integer overflow, APG_SUCCESS otherwise.

Definition at line 170 of file tools.c.

◆ bSumLong()

abool bSumLong ( luint  uiL,
luint  uiR,
luint uipA 
)

Add two long unsigned integers with overflow notification.

Parameters
uiLleft term
uiRright term
uipApointer to the sum
Returns
APG_FAILURE if the addition results in integer overflow, APG_SUCCESS otherwise.

Definition at line 131 of file tools.c.

◆ cpPhrase32ToStr()

char* cpPhrase32ToStr ( u32_phrase spPhrase,
char *  cpStr 
)

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

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

Parameters
spPhrasePointer to the u32_phrase to convert. May not be NULL or have a NULL array pointer.
cpStrPointer to the buffer of characters to receive the string. It is the caller's responsibility to ensure that cpStr points to an array of at least (spPhrase->uiLength + 1) characters. Otherwise buffer overrun will occur.
Returns
Returns a pointer to cpStr, the caller's string buffer.

Definition at line 382 of file tools.c.

◆ cpPhraseToStr()

char* cpPhraseToStr ( apg_phrase spPhrase,
char *  cpStr 
)

Convert a phrase 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).

Parameters
spPhrasePointer to the apg_phrase to convert. May not be NULL or have a NULL array pointer.
cpStrPointer to the buffer of characters to receive the string. It is the caller's responsibility to ensure that cpStr points to an array of at least (spPhrase->uiLength + 1) characters. Otherwise buffer overrun will occur.
Returns
Returns a pointer to cpStr, the caller's string buffer.

Definition at line 264 of file tools.c.

◆ cpUint32ToStr()

char* cpUint32ToStr ( uint32_t *  uipBuf,
aint  uiLen,
char *  cpStr 
)

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

Parameters
uipBufPointer to an 32-bit unsigned integer array to convert. May not be NULL.
uiLenThe number of characters in the uipBuf array.
cpStrPointer to the buffer of characters to receive the string. It is the caller's responsibility to ensure that cpStr points to an array of at least (uiLen + 1) characters. Otherwise buffer overrun will occur.
Returns
Returns a pointer to cpStr, the caller's string buffer.

Definition at line 336 of file tools.c.

◆ iStriCmp()

int iStriCmp ( const char *  cpLeft,
const char *  cpRight 
)

Compare two strings. A case-insensitive version of strcmp().

Two strings are considered equal if

  • all characters are case-insensitive equal
    • that is equal when both are converted to lower case
  • if both are NULL
  • if both are empty.
Parameters
cpLeftPointer to the left string.
cpRightPointer to the right string.
Returns
0 if the two strings are case-insensitively the equal
  • 0 indicates that the two strings are equal
  • -1 indicates that cpLeft is alphabetically lower than cpRight
  • +1 indicates that cpLeft is alphabetically higher than cpRight

Definition at line 53 of file tools.c.

◆ spStrToPhrase()

apg_phrase* spStrToPhrase ( const char *  cpStr,
apg_phrase spPhrase 
)

Convert an ASCII, null-terminated string to an achar phrase.

Parameters
cpStrPointer to the string to convert.
spPhrasePointer to a phrase.
  • spPhrase->acpPhrase = an empty array of achar characters
  • spPhrase->uiLength = the length of the array
Returns
On success, returns a pointer to the input spPhrase with
  • spPhrase->acpPhrase = pointer to the converted to achar characters
  • spPhrase->uiLength = strlen(cpStr), the number of converted characters

On failure returns NULL. However,

  • spPhrase->uiLength = strlen(cpStr), the number of converted characters

This can be used to adjust the buffer size for successful conversion.

Definition at line 237 of file tools.c.

◆ sStrToPhrase32()

u32_phrase sStrToPhrase32 ( const char *  cpStr,
uint32_t *  uipBuf 
)

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

Parameters
cpStrPointer to the string to convert. May not be NULL.
uipBufPointer to the 32-bit array to receive the converted string characters. May not be NULL. It is the caller's responsibility to ensure that the array is at least strlen(cpStr) in length. Otherwise buffer overrun will result.
Returns
Returns a u32_phrase structure. NOTE: Returns a structure, not a pointer to a structure.

Definition at line 360 of file tools.c.

◆ uipStrToUint32()

uint32_t* uipStrToUint32 ( const char *  cpStr,
uint32_t *  uipBuf,
aint uipLen 
)

Convert an ASCII, null-terminated string to an 32-bit unsigned integer array.

Parameters
cpStrPointer to the string to convert. May not be NULL.
uipBufPointer to an 32-bit unsigned integer array to receive the converted string characters. May not be NULL. It is the caller's responsibility to ensure that the array is at least strlen(cpStr) in length. Otherwise buffer overrun will result.
uipLenPointer to an unsigned integer to receive the number of characters in the ucpBuf array. May be NULL if no returned length is needed.
Returns
Returns a pointer to the caller's 32-bit unsigned integer array. Returns the number of integers in the array if uipLen != NULL.

Definition at line 313 of file tools.c.

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