arrayutils.h File Reference

Functions for handling character arrays. More...

#include "common.h"
#include <stdio.h>

Go to the source code of this file.

Macros
#define	QSC_ARRAYTILS_NPOS   -1LL
	The constant return value indicating that a search token was not found.

Functions
QSC_EXPORT_API size_t	qsc_arrayutils_find_string (const char *str, size_t slen, const char *token)
	Find the first instance of a token in a string.
QSC_EXPORT_API uint8_t	qsc_arrayutils_hex_to_uint8 (const char *str, size_t slen)
	Convert a hexadecimal encoded string to an 8-bit unsigned integer.
QSC_EXPORT_API void	qsc_arrayutils_uint8_to_hex (char *output, size_t otplen, uint8_t value)
	Convert an 8-bit unsigned integer to a hexadecimal string.
QSC_EXPORT_API void	qsc_arrayutils_uint16_to_hex (char *output, size_t otplen, uint16_t value)
	Convert a 16-bit unsigned integer to a hexadecimal string.
QSC_EXPORT_API void	qsc_arrayutils_uint32_to_hex (char *output, size_t otplen, uint32_t value)
	Convert a 32-bit unsigned integer to a hexadecimal string.
QSC_EXPORT_API void	qsc_arrayutils_uint64_to_hex (char *output, size_t otplen, uint64_t value)
	Convert a 64-bit unsigned integer to a hexadecimal string.
QSC_EXPORT_API uint8_t	qsc_arrayutils_string_to_uint8 (const char *str, size_t slen)
	Parse an 8-bit unsigned integer from a string.
QSC_EXPORT_API uint16_t	qsc_arrayutils_string_to_uint16 (const char *str, size_t slen)
	Parse a 16-bit unsigned integer from a string.
QSC_EXPORT_API uint32_t	qsc_arrayutils_string_to_uint32 (const char *str, size_t slen)
	Parse a 32-bit unsigned integer from a string.
QSC_EXPORT_API uint64_t	qsc_arrayutils_string_to_uint64 (const char *str, size_t slen)
	Parse a 64-bit unsigned integer from a string.
QSC_EXPORT_API bool	qsc_arrayutils_self_test (void)
	Perform a self-test of the array utilities.

Detailed Description

Functions for handling character arrays.

This header provides a collection of utility functions for performing common operations on character arrays. The functions support tasks such as:

• Searching for tokens or substrings within strings.
• Converting hexadecimal-encoded strings to their corresponding binary values.
• Converting numeric values (8-bit, 16-bit, 32-bit, and 64-bit unsigned integers) to hexadecimal string representations.
• Parsing unsigned integers from strings.

These operations are critical for data formatting, debugging, and preparing string data for cryptographic processing.

Example Usage:

#include "arrayutils.h"
#include <string.h>
 
// Example 1: Finding a token within a string.
const char* sample = "The quick brown fox jumps over the lazy dog";
size_t pos = qsc_arrayutils_find_string(sample, strlen(sample), "brown");
if (pos != QSC_ARRAYTILS_NPOS)
{
    // Token "brown" found at position 'pos'.
}
 
// Example 2: Converting a 32-bit unsigned integer to a hexadecimal string.
uint32_t number = 305419896; // 0x12345678
char hex_output[9] = {0};
qsc_arrayutils_uint32_to_hex(hex_output, sizeof(hex_output), number);
// hex_output now holds the string "12345678".

Reference Links:

• Hexadecimal Number System

Macro Definition Documentation

QSC_ARRAYTILS_NPOS

#define QSC_ARRAYTILS_NPOS   -1LL

The constant return value indicating that a search token was not found.

This value is returned by qsc_arrayutils_find_string when the token cannot be located.

Function Documentation

qsc_arrayutils_find_string()

QSC_EXPORT_API size_t qsc_arrayutils_find_string	(	const char *	str,
		size_t	slen,
		const char *	token )

Find the first instance of a token in a string.

Searches for the first occurrence of a given token within a string and returns the zero-based character position. If the token is not found, the function returns QSC_ARRAYTILS_NPOS.

Parameters

str	[const char*] Pointer to the constant character string to be searched.
slen	[size_t] The length of the string in bytes (excluding the null terminator).
token	[const char*] Pointer to the constant token string to search for.

Returns

[size_t] The zero-based position of the token if found; otherwise QSC_ARRAYTILS_NPOS.

See also

strstr

qsc_arrayutils_hex_to_uint8()

QSC_EXPORT_API uint8_t qsc_arrayutils_hex_to_uint8	(	const char *	str,
		size_t	slen )

Convert a hexadecimal encoded string to an 8-bit unsigned integer.

Reads up to two hexadecimal characters from the input string and converts them into the corresponding uint8_t value.

Parameters

str	[const char*] Pointer to the constant hexadecimal string.
slen	[size_t] The length of the string in bytes (excluding the null terminator).

Returns

[uint8_t] The resulting 8-bit unsigned integer.

qsc_arrayutils_self_test()

QSC_EXPORT_API bool qsc_arrayutils_self_test

(

void

)

Perform a self-test of the array utilities.

Runs a series of tests to validate the correctness of the functions in this module.

Returns

[bool] true if all tests pass; otherwise false.

qsc_arrayutils_string_to_uint16()

QSC_EXPORT_API uint16_t qsc_arrayutils_string_to_uint16	(	const char *	str,
		size_t	slen )

Parse a 16-bit unsigned integer from a string.

Reads the input string and converts it to a uint16_t value.

Parameters

str	[const char*] Pointer to the constant character string containing the number.
slen	[size_t] The length of the string in bytes (excluding the null terminator).

Returns

[uint16_t] The parsed 16-bit unsigned integer, or zero if parsing fails.

qsc_arrayutils_string_to_uint32()

QSC_EXPORT_API uint32_t qsc_arrayutils_string_to_uint32	(	const char *	str,
		size_t	slen )

Parse a 32-bit unsigned integer from a string.

Reads the input string and converts it to a uint32_t value.

Parameters

str	[const char*] Pointer to the constant character string containing the number.
slen	[size_t] The length of the string in bytes (excluding the null terminator).

Returns

[uint32_t] The parsed 32-bit unsigned integer, or zero if parsing fails.

qsc_arrayutils_string_to_uint64()

QSC_EXPORT_API uint64_t qsc_arrayutils_string_to_uint64	(	const char *	str,
		size_t	slen )

Parse a 64-bit unsigned integer from a string.

Reads the input string and converts it to a uint64_t value.

Parameters

str	[const char*] Pointer to the constant character string containing the number.
slen	[size_t] The length of the string in bytes (excluding the null terminator).

Returns

[uint64_t] The parsed 64-bit unsigned integer, or zero if parsing fails.

qsc_arrayutils_string_to_uint8()

QSC_EXPORT_API uint8_t qsc_arrayutils_string_to_uint8	(	const char *	str,
		size_t	slen )

Parse an 8-bit unsigned integer from a string.

Reads the input string and converts it to a uint8_t value.

Parameters

str	[const char*] Pointer to the constant character string containing the number.
slen	[size_t] The length of the string in bytes (excluding the null terminator).

Returns

[uint8_t] The parsed 8-bit unsigned integer, or zero if parsing fails.

qsc_arrayutils_uint16_to_hex()

QSC_EXPORT_API void qsc_arrayutils_uint16_to_hex	(	char *	output,
		size_t	otplen,
		uint16_t	value )

Convert a 16-bit unsigned integer to a hexadecimal string.

Converts the given uint16_t value into a four-digit hexadecimal representation, writing the result to the provided output buffer.

Parameters

output	[char*] Pointer to the output character array.
otplen	[size_t] The length of the output buffer in bytes.
value	[uint16_t] The 16-bit unsigned integer to convert.

qsc_arrayutils_uint32_to_hex()

QSC_EXPORT_API void qsc_arrayutils_uint32_to_hex	(	char *	output,
		size_t	otplen,
		uint32_t	value )

Convert a 32-bit unsigned integer to a hexadecimal string.

Converts the given uint32_t value into an eight-digit hexadecimal representation, writing the result to the provided output buffer.

Parameters

output	[char*] Pointer to the output character array.
otplen	[size_t] The length of the output buffer in bytes.
value	[uint32_t] The 32-bit unsigned integer to convert.

qsc_arrayutils_uint64_to_hex()

QSC_EXPORT_API void qsc_arrayutils_uint64_to_hex	(	char *	output,
		size_t	otplen,
		uint64_t	value )

Convert a 64-bit unsigned integer to a hexadecimal string.

Converts the given uint64_t value into a sixteen-digit hexadecimal representation, writing the result to the provided output buffer.

Parameters

output	[char*] Pointer to the output character array.
otplen	[size_t] The length of the output buffer in bytes.
value	[uint64_t] The 64-bit unsigned integer to convert.

qsc_arrayutils_uint8_to_hex()

QSC_EXPORT_API void qsc_arrayutils_uint8_to_hex	(	char *	output,
		size_t	otplen,
		uint8_t	value )

Convert an 8-bit unsigned integer to a hexadecimal string.

Converts the given uint8_t value into a two-digit hexadecimal representation, writing the result to the provided output buffer.

Parameters

output	[char*] Pointer to the output character array.
otplen	[size_t] The length of the output buffer in bytes.
value	[uint8_t] The 8-bit unsigned integer to convert.