A few simple, commonly used functions. More...

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

Functions
int	iStriCmp (const char cpStrl, const char cpStrr)
	Compare two strings. A case-insensitive version of strcmp(). More...

abool	bIsBigEndian (void)
	Determine if the current machine uses big endian word storage. More...

Multiply and Add with Overflow Protection
Occasionally, it is necessary to implement overflow protection on multiplication and summation. For example, ABNF defines a character with the syntax %xHHHHH.... There is nothing in the ABNF syntax that limits the number of digits. Therefore, it is the syntax parser's job to check that the character does not overflow the computer's integer length. This is a set of such functions specialized for various integer types.
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...

Alphabet Character Arrays and Phrases
ABNF is syntax for defining phrases, a phrase being an array of alphabet characters. The size of the alphabet character integers is configurable in apg.h and, in general, a phrase does not lend itself well to the null-terminated string convention. For this reason, a phrase structure, apg_phrase, has been defined. This is a suite of functions for converting strings to phrases and vice versa. See also the utility functions acpUtilStrToAchar() cpUtilAcharToStr() spUtilStrToPhrase() cpUtilPhraseToStr()
apg_phrase *	spStrToPhrase (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...

Unicode Character Arrays and Phrases
The special case of Unicode characters is common enough to warrant a special set of phrase conversion functions. The Unicode phrase, u32_phrase, is analogous to the alphabet character phrase, apg_phrase. This suite of functions is likewise analogous to the apg_phrase functions. See also the utility functions uipUtilStrToUint32() cpUtilUint32ToStr() spUtilStrToPhrase32() cpUtilPhrase32ToStr()
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 acpBuf)
	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 simple, commonly used functions.

Definition in file tools.h.

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

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

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

uiL	left factor
uiR	right factor
uipA	pointer 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

uiL	left factor
uiR	right factor
uipA	pointer 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

luiL	left factor
luiR	right factor
luipA	pointer 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

uiL	left term
uiR	right term
uipA	pointer 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

uiL	left term
uiR	right term
uipA	pointer 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

uiL	left term
uiR	right term
uipA	pointer 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

spPhrase	Pointer to the u32_phrase to convert. May not be NULL or have a NULL array pointer.
cpStr	Pointer 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

spPhrase	Pointer to the apg_phrase to convert. May not be NULL or have a NULL array pointer.
cpStr	Pointer 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

uipBuf	Pointer to an 32-bit unsigned integer array to convert. May not be NULL.
uiLen	The number of characters in the uipBuf array.
cpStr	Pointer 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

cpLeft	Pointer to the left string.
cpRight	Pointer 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

cpStr	Pointer to the string to convert.
spPhrase	Pointer 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

cpStr	Pointer to the string to convert. May not be NULL.
uipBuf	Pointer 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

cpStr	Pointer to the string to convert. May not be NULL.
uipBuf	Pointer 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.
uipLen	Pointer 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.

Functions

Detailed Description

Function Documentation

◆ bIsBigEndian()

◆ bIsPhrase32Ascii()

◆ bIsPhraseAscii()

◆ bMultiply()

◆ bMultiply32()

◆ bMultiplyLong()

◆ bSum()

◆ bSum32()

◆ bSumLong()

◆ cpPhrase32ToStr()

◆ cpPhraseToStr()

◆ cpUint32ToStr()

◆ iStriCmp()

◆ spStrToPhrase()

◆ sStrToPhrase32()

◆ uipStrToUint32()