API for input/output utilities and safe string interfaces. More...

Collaboration diagram for I/O Utils:

Macros
#define	qIOUtil_PrintString(fcn, pStorage, s)
	Macro interface to write a string through fcn.

#define	qIOUtil_PrintRaw(fcn, pStorage, Data, n)
	Macro interface to write RAW data through fcn.

Typedefs
typedef void(*	qPutChar_t) (void *arg1, const char arg2)
	Pointer to function that write-out a single character.

typedef char(*	qIOFcn_t) (void *arg1, const char arg2)
	Pointer to function that perform a single character I/O operation.

Functions
char *	qIOUtil_StrChr (const char *s, int c, size_t maxlen)
	Returns a pointer to the first occurrence of character in the C string s. The terminating null-character is considered part of the C string. Therefore, it can also be located in order to retrieve a pointer to the end of a string.

size_t	qIOUtil_StrLen (const char *s, size_t maxlen)
	Returns the length of the given null-terminated byte string, that is, the number of characters in a character array whose first element is pointed to by str up to and not including the first null character. The function returns zero if str is a null pointer and returns maxlen if the null character was not found in the first maxlen bytes of str.

size_t	qIOUtil_StrlCpy (char dst, const char src, size_t maxlen)
	Copies up to (maxlen - 1) characters from the null-terminated string src to dst, null-terminating the result.

size_t	qIOUtil_StrlCat (char dst, const char src, size_t maxlen)
	appends no more than maxlen−len(dst)−1 characters pointed to by src into the array pointed to by dst and always terminates the result with a null character if maxlen is greater than zero. Both the strings dst and src must be terminated with a null character on entry the function and a byte for the terminating null should be included in maxlen.

qBool_t	qIOUtil_SwapBytes (void *pData, const size_t n)
	Invert the endianess for n bytes of the specified memory location.

qBool_t	qIOUtil_CheckEndianness (void)
	Check the system endianess.

qBool_t	qIOUtil_OutputString (qPutChar_t fcn, void pStorage, const char s, qBool_t AIP)
	API interface to write a string through fcn.

qBool_t	qIOUtil_PrintXData (qPutChar_t fcn, void pStorage, void pData, size_t n)
	API interface to write data in HEX notation through fcn.

qBool_t	qIOUtil_OutputRaw (const qIOFcn_t oFcn, void pStorage, void pData, const size_t n, qBool_t aip)
	API interface to write n RAW data through fcn.

qBool_t	qIOUtil_InputRaw (const qIOFcn_t iFcn, void pStorage, void pData, const size_t n, qBool_t aip)
	API interface to get n RAW data through fcn.

char *	qIOUtil_U32toX (qUINT32_t value, char *str, qINT8_t n)
	Converts an unsigned integer value to a null-terminated string using the 16 base and stores the result in the array given by str parameter. str should be an array long enough to contain any possible value.

qUINT32_t	qIOUtil_XtoU32 (const char *s)
	Converts the input string consisting of hexadecimal digits into an unsigned integer value. The input parameter should consist exclusively of hexadecimal digits, with optional whitespaces. The string will be processed one character at a time, until the function reaches a character which it doesn't recognize (including a null character).

qFloat64_t	qIOUtil_AtoF (const char *s)
	Parses the C string s, interpreting its content as a floating point number and returns its value as a double( `qFloat64_t`). The function first discards as many whitespace characters (as in isspace) as necessary until the first non-whitespace character is found. Then, starting from this character, takes as many characters as possible that are valid following a syntax resembling that of floating point literals, and interprets them as a numerical value. The rest of the string after the last valid character is ignored and has no effect on the behavior of this function.

char *	qIOUtil_FtoA (qFloat32_t num, char *str, qUINT8_t precision)
	Converts a float value to a formatted string.

int	qIOUtil_AtoI (const char *s)
	Parses the C-string s interpreting its content as an integral number, which is returned as a value of type int. The function first discards as many whitespace characters (as in `isspace`) as necessary until the first non-whitespace character is found. Then, starting from this character, takes an optional initial plus or minus sign followed by as many base-10 digits as possible, and interprets them as a numerical value. The string can contain additional characters after those that form the integral number, which are ignored and have no effect on the behavior of this function. If the first sequence of non-whitespace characters in s is not a valid integral number, or if no such sequence exists because either s is empty or it contains only whitespace characters, no conversion is performed and zero is returned.

char *	qIOUtil_UtoA (qUINT32_t num, char *str, qUINT8_t base)
	Converts an unsigned value to a null-terminated string using the specified base and stores the result in the array given by str parameter. The argument str should be an array long enough to contain any possible value: `"sizeof(int)*8+1"` for radix=2, i.e. 17 bytes in 16-bits platforms and 33 in 32-bits platforms.

char *	qIOUtil_ItoA (qINT32_t num, char *str, qUINT8_t base)
	Converts an integer value to a null-terminated string using the specified base and stores the result in the array given by str parameter. If base is 10 and value is negative, the resulting string is preceded with a minus sign (-). With any other base, value is always considered unsigned.

char *	qIOUtil_BtoA (const qBool_t num, char *str)
	Converts a boolean value to a null-terminated string. Input is considered true with any value different to zero (0). The argument str should be an array long enough to contain the output.

char *	qIOUtil_QBtoA (const qBool_t num, char *str)
	Converts a qBool_t value to a null-terminated string. Input is considered true with any value different to zero (0). The argument str should be an array long enough to contain the output.

Detailed Description

API for input/output utilities and safe string interfaces.

Macro Definition Documentation

◆ qIOUtil_PrintRaw

#define qIOUtil_PrintRaw	(	fcn,
		pStorage,
		Data,
		n )

Macro interface to write RAW data through fcn.

Parameters

[in]	fcn	The basic input byte function
[in]	pStorage	The storage pointer passed to fcn
[in]	Data	A pointer to the block of data
[in]	n	The number of bytes to print out.

Returns: none.

◆ qIOUtil_PrintString

#define qIOUtil_PrintString	(	fcn,
		pStorage,
		s )

Macro interface to write a string through fcn.

Parameters

[in]	fcn	The basic input byte function
[in]	pStorage	The storage pointer passed to fcn
[in]	s	The string to be written

Returns: none.

Typedef Documentation

◆ qIOFcn_t

typedef char(* qIOFcn_t) (void *arg1, const char arg2)

Pointer to function that perform a single character I/O operation.

Note: User should use bare-metal code to implement this function. Example 1: Input operation
char BSP_GetChar( void *sp, char in ) {

(void)sp;

(void)in;

return HAL_UARTReceiveByte( );

}

Example 2: Ouput operation
char BSP_GetChar( void *sp, char in ) {

(void)sp;

HAL_UARTPutByte( in );

return 0U;

}

Parameters

[in] sp The user storage pointer.

Returns: If an input operation is performed, this function should return the byte read from the input.

◆ qPutChar_t

typedef void(* qPutChar_t) (void *arg1, const char arg2)

Pointer to function that write-out a single character.

Note: User should use bare-metal code to implement this function. Example :
void BSP_PutChar( void *sp, const char c ) {

(void)sp;

HAL_UARTWriteByte( c );

}

Parameters

[in]	sp	The user storage pointer.
[in]	c	The character to write out.

Returns: none.

Function Documentation

◆ qIOUtil_AtoF()

qFloat64_t qIOUtil_AtoF ( const char * s )

Parses the C string s, interpreting its content as a floating point number and returns its value as a double( qFloat64_t). The function first discards as many whitespace characters (as in isspace) as necessary until the first non-whitespace character is found. Then, starting from this character, takes as many characters as possible that are valid following a syntax resembling that of floating point literals, and interprets them as a numerical value. The rest of the string after the last valid character is ignored and has no effect on the behavior of this function.

Parameters

[in] s The string beginning with the representation of a floating-point number.

Returns: On success, the function returns the converted floating point number as a double( qFloat64_t ) value. If no valid conversion could be performed, the function returns zero (0.0). If the converted value would be out of the range of representable values by a double( qFloat64_t ), it causes undefined behavior

◆ qIOUtil_AtoI()

int qIOUtil_AtoI ( const char * s )

Parses the C-string s interpreting its content as an integral number, which is returned as a value of type int. The function first discards as many whitespace characters (as in isspace) as necessary until the first non-whitespace character is found. Then, starting from this character, takes an optional initial plus or minus sign followed by as many base-10 digits as possible, and interprets them as a numerical value. The string can contain additional characters after those that form the integral number, which are ignored and have no effect on the behavior of this function. If the first sequence of non-whitespace characters in s is not a valid integral number, or if no such sequence exists because either s is empty or it contains only whitespace characters, no conversion is performed and zero is returned.

Parameters

[in] s The string beginning with the representation of a integer number.

Returns: On success, the function returns the converted integral number as an int value. If the converted value would be out of the range of representable values by an int, it causes undefined behavior.

◆ qIOUtil_BtoA()

char * qIOUtil_BtoA	(	const qBool_t	num,
		char *	str )

Converts a boolean value to a null-terminated string. Input is considered true with any value different to zero (0). The argument str should be an array long enough to contain the output.

Parameters

[in]	num	Value to be converted to a string.
[out]	str	Array in memory where to store the resulting null-terminated string.

Returns: A pointer to the resulting null-terminated string, same as parameter str.

◆ qIOUtil_CheckEndianness()

qBool_t qIOUtil_CheckEndianness ( void )

Check the system endianess.

Returns: qTrue if Little-Endian, otherwise returns qFalse.

◆ qIOUtil_FtoA()

char * qIOUtil_FtoA	(	qFloat32_t	num,
		char *	str,
		qUINT8_t	precision )

Converts a float value to a formatted string.

Parameters

[in]	num	Value to be converted to a string.
[out]	str	Array in memory where to store the resulting null-terminated string.
[in]	precision	Desired number of significant fractional digits in the string. ( The max allowed precision is `MAX_FTOA_PRECISION=10` )

Returns: A pointer to the resulting null-terminated string, same as parameter str.

◆ qIOUtil_InputRaw()

qBool_t qIOUtil_InputRaw	(	const qIOFcn_t	iFcn,
		void *	pStorage,
		void *	pData,
		const size_t	n,
		qBool_t	aip )

API interface to get n RAW data through fcn.

Parameters

[in]	iFcn	The basic input byte function
[in]	pStorage	The storage pointer passed to fcn
[out]	pData	A pointer to the block where the read data will be saved
[in]	n	The number of bytes to get
[in]	aip	Auto-increment the storage-pointer

Returns: qTrue on success, otherwise returns qFalse.

◆ qIOUtil_ItoA()

char * qIOUtil_ItoA	(	qINT32_t	num,
		char *	str,
		qUINT8_t	base )

Converts an integer value to a null-terminated string using the specified base and stores the result in the array given by str parameter. If base is 10 and value is negative, the resulting string is preceded with a minus sign (-). With any other base, value is always considered unsigned.

The argument str should be an array long enough to contain any possible value: (sizeof(int)*8+1) for radix=2, i.e. 17 bytes in 16-bits platforms and 33 in 32-bits platforms.

Parameters

[in]	num	Value to be converted to a string.
[out]	str	Array in memory where to store the resulting null-terminated string.
[in]	base	Numerical base used to represent the value as a string, between 2 and 36, where 10 means decimal base, 16 hexadecimal, 8 octal, and 2 binary.

Returns: A pointer to the resulting null-terminated string, same as parameter str.

◆ qIOUtil_OutputRaw()

qBool_t qIOUtil_OutputRaw	(	const qIOFcn_t	oFcn,
		void *	pStorage,
		void *	pData,
		const size_t	n,
		qBool_t	aip )

API interface to write n RAW data through fcn.

Parameters

[in]	oFcn	The basic output byte function
[in]	pStorage	The storage pointer passed to fcn
[in]	pData	A pointer to the block of data
[in]	n	The number of bytes that will be transferred to the output
[in]	aip	Auto-increment the storage-pointer

Returns: qTrue on success, otherwise returns qFalse.

◆ qIOUtil_OutputString()

qBool_t qIOUtil_OutputString	(	qPutChar_t	fcn,
		void *	pStorage,
		const char *	s,
		qBool_t	AIP )

API interface to write a string through fcn.

Parameters

[in]	fcn	The basic output byte function
[in]	pStorage	The storage pointer passed to fcn
[in]	s	The string to be written
[in]	AIP	Auto-Increment the storage-pointer

Returns: qTrue on success, otherwise returns qFalse.

◆ qIOUtil_PrintXData()

qBool_t qIOUtil_PrintXData	(	qPutChar_t	fcn,
		void *	pStorage,
		void *	pData,
		size_t	n )

API interface to write data in HEX notation through fcn.

Parameters

[in]	fcn	The basic output byte function
[in]	pStorage	The storage pointer passed to fcn
[in]	pData	A pointer to the block of data
[in]	n	The number of bytes to print out

Returns: qTrue on success, otherwise returns qFalse.

◆ qIOUtil_QBtoA()

char * qIOUtil_QBtoA	(	const qBool_t	num,
		char *	str )

Converts a qBool_t value to a null-terminated string. Input is considered true with any value different to zero (0). The argument str should be an array long enough to contain the output.

Parameters

[in]	num	Value to be converted to a string.
[out]	str	Array in memory where to store the resulting null-terminated string.

Returns: A pointer to the resulting null-terminated string, same as parameter str.

◆ qIOUtil_StrChr()

char * qIOUtil_StrChr	(	const char *	s,
		int	c,
		size_t	maxlen )

Returns a pointer to the first occurrence of character in the C string s. The terminating null-character is considered part of the C string. Therefore, it can also be located in order to retrieve a pointer to the end of a string.

Parameters

[in]	s	Pointer to the null-terminated byte string to be examined
[in]	c	Character to be located. It is passed as its int promotion, but it is internally converted back to char for the comparison.
[in]	maxlen	Maximum number of characters to examine

Returns: A pointer to the first occurrence of character in s. If the character is not found, the function returns a null pointer.

◆ qIOUtil_StrlCat()

size_t qIOUtil_StrlCat	(	char *	dst,
		const char *	src,
		size_t	maxlen )

appends no more than maxlen−len(dst)−1 characters pointed to by src into the array pointed to by dst and always terminates the result with a null character if maxlen is greater than zero. Both the strings dst and src must be terminated with a null character on entry the function and a byte for the terminating null should be included in maxlen.

Note: The behavior of this function is undefined if copying takes place between objects that overlap.

Parameters

[out]	dst	The destination string
[in]	src	The source string
[in]	maxlen	Maximum number of characters to copy

Returns: returns the number of characters it tried to copy, which is the sum of the lengths of the strings dst and src or n, whichever is smaller.

◆ qIOUtil_StrlCpy()

size_t qIOUtil_StrlCpy	(	char *	dst,
		const char *	src,
		size_t	maxlen )

Copies up to (maxlen - 1) characters from the null-terminated string src to dst, null-terminating the result.

Parameters

[out]	dst	The destination string
[in]	src	The source string
[in]	maxlen	Maximum number of characters to copy

Returns: The length of src

◆ qIOUtil_StrLen()

size_t qIOUtil_StrLen	(	const char *	s,
		size_t	maxlen )

Returns the length of the given null-terminated byte string, that is, the number of characters in a character array whose first element is pointed to by str up to and not including the first null character. The function returns zero if str is a null pointer and returns maxlen if the null character was not found in the first maxlen bytes of str.

Parameters

[in]	s	Pointer to the null-terminated byte string to be examined
[in]	maxlen	Maximum number of characters to examine

Returns: The length of the null-terminated byte string str on success, zero if str is a null pointer, maxlen if the null character was not found.

◆ qIOUtil_SwapBytes()

qBool_t qIOUtil_SwapBytes	(	void *	pData,
		const size_t	n )

Invert the endianess for n bytes of the specified memory location.

Parameters

[in,out]	pData	A pointer to block of data
[in]	n	The number of bytes to swap

Returns: qTrue on success, otherwise returns qFalse.

◆ qIOUtil_U32toX()

char * qIOUtil_U32toX	(	qUINT32_t	value,
		char *	str,
		qINT8_t	n )

Converts an unsigned integer value to a null-terminated string using the 16 base and stores the result in the array given by str parameter. str should be an array long enough to contain any possible value.

Parameters

[in]	value	Value to be converted to a string.
[out]	str	Array in memory where to store the resulting string.
[in]	n	The number of chars used to represent the value in str

Returns: A pointer to the resulting null-terminated string, same as parameter str.

◆ qIOUtil_UtoA()

char * qIOUtil_UtoA	(	qUINT32_t	num,
		char *	str,
		qUINT8_t	base )

Converts an unsigned value to a null-terminated string using the specified base and stores the result in the array given by str parameter. The argument str should be an array long enough to contain any possible value: "sizeof(int)*8+1" for radix=2, i.e. 17 bytes in 16-bits platforms and 33 in 32-bits platforms.

Parameters

[in]	num	Value to be converted to a string.
[out]	str	Array in memory where to store the resulting null-terminated string.
[in]	base	Numerical base used to represent the value as a string, between 2 and 36, where 10 means decimal base, 16 hexadecimal, 8 octal, and 2 binary.

Returns: A pointer to the resulting null-terminated string, same as parameter str.

◆ qIOUtil_XtoU32()

qUINT32_t qIOUtil_XtoU32 ( const char * s )

Converts the input string consisting of hexadecimal digits into an unsigned integer value. The input parameter should consist exclusively of hexadecimal digits, with optional whitespaces. The string will be processed one character at a time, until the function reaches a character which it doesn't recognize (including a null character).

Parameters

[in] s The hex string to be converted.

Returns: The numeric value as uint32_t.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ qIOUtil_PrintRaw

◆ qIOUtil_PrintString

Typedef Documentation

◆ qIOFcn_t

◆ qPutChar_t

Function Documentation

◆ qIOUtil_AtoF()

◆ qIOUtil_AtoI()

◆ qIOUtil_BtoA()

◆ qIOUtil_CheckEndianness()

◆ qIOUtil_FtoA()

◆ qIOUtil_InputRaw()

◆ qIOUtil_ItoA()

◆ qIOUtil_OutputRaw()

◆ qIOUtil_OutputString()

◆ qIOUtil_PrintXData()

◆ qIOUtil_QBtoA()

◆ qIOUtil_StrChr()

◆ qIOUtil_StrlCat()

◆ qIOUtil_StrlCpy()

◆ qIOUtil_StrLen()

◆ qIOUtil_SwapBytes()

◆ qIOUtil_U32toX()

◆ qIOUtil_UtoA()

◆ qIOUtil_XtoU32()