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

Collaboration diagram for I/O Utils:

Typedefs
using	qOS::util::putChar_t
	Pointer to function that write-out a single character.

using	qOS::util::ioFcn_t
	Pointer to function that perform a single character I/O operation.

Functions
char *	qOS::util::strchr (const char *s, int c, size_t maxlen) noexcept
	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	qOS::util::strlen (const char *s, size_t maxlen) noexcept
	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	qOS::util::strcpy (char dst, const char src, size_t maxlen) noexcept
	Copies up to (maxlen - 1) characters from the null-terminated string src to dst, null-terminating the result.

size_t	qOS::util::strcat (char dst, const char src, size_t maxlen) noexcept
	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.

bool	qOS::util::swapBytes (void *pData, const size_t n) noexcept
	Invert the endianess for n bytes of the specified memory location.

bool	qOS::util::checkEndianness (void) noexcept
	Check the system endianess.

bool	qOS::util::outputString (util::putChar_t fcn, const char s, void pStorage=nullptr, bool aip=false) noexcept
	API interface to write a string through fcn.

bool	qOS::util::printXData (util::putChar_t fcn, void pData, size_t n, bool eol=true, void pStorage=nullptr) noexcept
	API interface to write data in HEX notation through fcn.

bool	qOS::util::outputRAW (const ioFcn_t fcn, void pData, const size_t n, void pStorage=nullptr, bool aip=false) noexcept
	API interface to write n RAW data through fcn.

bool	qOS::util::inputRAW (const ioFcn_t fcn, void pData, const size_t n, void pStorage=nullptr, bool aip=false) noexcept
	API interface to get n RAW data through fcn.

uint32_t	qOS::util::hexStringToUnsigned (const char *s) noexcept
	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).

float64_t	qOS::util::stringToFloat (const char *s) noexcept
	Parses the C string s, interpreting its content as a floating point number and returns its value as a float( `float32_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 *	qOS::util::floatToString (float64_t num, char *str, uint8_t precision=10U) noexcept
	Converts a float value to a formatted string.

int	qOS::util::stringToInt (const char *s) noexcept
	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 *	qOS::util::unsignedToString (unsigned_t num, char *str, uint8_t base=10U) noexcept
	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 *	qOS::util::integerToString (signed_t num, char *str, uint8_t base=10U) noexcept
	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 *	qOS::util::boolToString (const bool num, char *str) noexcept
	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.

Detailed Description

API for input/output utilities and safe string interfaces.

Typedef Documentation

◆ ioFcn_t

using qOS::util::ioFcn_t

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, const 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.
[in]	in	The byte to write out.

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

◆ putChar_t

using qOS::util::putChar_t

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

◆ boolToString()

char * qOS::util::boolToString	(	const bool	num,
		char *	str )

noexcept

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.

◆ checkEndianness()

bool qOS::util::checkEndianness ( void )

noexcept

Check the system endianess.

Returns: true if Little-Endian, otherwise returns false.

◆ floatToString()

char * qOS::util::floatToString	(	float64_t	num,
		char *	str,
		uint8_t	precision = 10U )

noexcept

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. (default = 10u )

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

◆ hexStringToUnsigned()

uint32_t qOS::util::hexStringToUnsigned ( const char * s )

noexcept

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.

◆ inputRAW()

bool qOS::util::inputRAW	(	const ioFcn_t	fcn,
		void *	pData,
		const size_t	n,
		void *	pStorage = nullptr,
		bool	aip = false )

noexcept

API interface to get n RAW data through fcn.

Parameters

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

Returns: true on success, otherwise returns false.

◆ integerToString()

char * qOS::util::integerToString	(	signed_t	num,
		char *	str,
		uint8_t	base = 10U )

noexcept

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.

◆ outputRAW()

bool qOS::util::outputRAW	(	const ioFcn_t	fcn,
		void *	pData,
		const size_t	n,
		void *	pStorage = nullptr,
		bool	aip = false )

noexcept

API interface to write n RAW data through fcn.

Parameters

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

Returns: true on success, otherwise returns false.

◆ outputString()

bool qOS::util::outputString	(	util::putChar_t	fcn,
		const char *	s,
		void *	pStorage = nullptr,
		bool	aip = false )

noexcept

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: true on success, otherwise returns false.

◆ printXData()

bool qOS::util::printXData	(	util::putChar_t	fcn,
		void *	pData,
		size_t	n,
		bool	eol = true,
		void *	pStorage = nullptr )

noexcept

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
[in]	eol	`true` to enable the EOL(End-Of-Line) termination.

Returns: true on success, otherwise returns false.

◆ strcat()

size_t qOS::util::strcat	(	char *	dst,
		const char *	src,
		size_t	maxlen )

noexcept

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.

◆ strchr()

char * qOS::util::strchr	(	const char *	s,
		int	c,
		size_t	maxlen )

noexcept

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.

◆ strcpy()

size_t qOS::util::strcpy	(	char *	dst,
		const char *	src,
		size_t	maxlen )

noexcept

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

◆ stringToFloat()

float64_t qOS::util::stringToFloat ( const char * s )

noexcept

Parses the C string s, interpreting its content as a floating point number and returns its value as a float( float32_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 float( qFloat32_t ) value. If no valid conversion could be performed, the function returns zero (0.0f). If the converted value would be out of the range of representable values by a float( qFloat32_t ), it causes undefined behavior

◆ stringToInt()

int qOS::util::stringToInt ( const char * s )

noexcept

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.

◆ strlen()

size_t qOS::util::strlen	(	const char *	s,
		size_t	maxlen )

noexcept

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.

◆ swapBytes()

bool qOS::util::swapBytes	(	void *	pData,
		const size_t	n )

noexcept

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: true on success, otherwise returns false.

◆ unsignedToString()

char * qOS::util::unsignedToString	(	unsigned_t	num,
		char *	str,
		uint8_t	base = 10U )

noexcept

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.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ioFcn_t

◆ putChar_t

Function Documentation

◆ boolToString()

◆ checkEndianness()

◆ floatToString()

◆ hexStringToUnsigned()

◆ inputRAW()

◆ integerToString()

◆ outputRAW()

◆ outputString()

◆ printXData()

◆ strcat()

◆ strchr()

◆ strcpy()

◆ stringToFloat()

◆ stringToInt()

◆ strlen()

◆ swapBytes()

◆ unsignedToString()