qTypeGeneric

Type-generic utilities. More...

Functions
void	qTypeGeneric_Swap (void *const x, void *const y, size_t n)
	Swaps the data pointed by x and y.
void	qTypeGeneric_Sort (void *const pbase, size_t n, size_t size, qTypeGeneric_CompareFcn_t cmp, void *arg)
	Sorts the given array pointed to by pbase in ascending order. The array contains n elements of size bytes. Function pointed to by cmp is used for object comparison.
void	qTypeGeneric_Reverse (void *const pbase, const size_t size, const size_t init, const size_t end)
	Reverse the given array pointed to by pbase. Operation takes place on the portion of the array that starts at position init to position end.
void	qTypeGeneric_Rotate (void *const pbase, const size_t size, const size_t n, const int k)
	Rotates k elements of the array pointed to by pbase. The array contains n elements of size bytes. Rotation direction is determined by the sign of k, the means a positive value performs a right-rotation and a negative value a left-rotation.
void *	qTypeGeneric_Set (void *const pbase, const size_t size, const size_t n, const void *const ref)
	Set the data pointed by ref to every element of the array pointed by pbase. The array contains n elements of size bytes.
void *	qTypeGeneric_LSearch (const void *key, const void *pbase, const size_t n, const size_t size, qTypeGeneric_CompareFcn_t compar, void *arg)
	Performs a linear search over an array of n elements pointed to by pbase for an element that matches the object pointed to by key. The size of each element is specified by size. The array contents should be sorted in ascending order according to the compar comparison function. This routine should take two arguments pointing to the key and to an array element, in that order, and should return an integer less than, equal to, or greater than zero if the key object is respectively less than, matching, or greater than the array element.
void *	qTypeGeneric_BSearch (const void *key, const void *pbase, const size_t n, const size_t size, qTypeGeneric_CompareFcn_t compar, void *arg)
	Performs a binary search over an array of n elements pointed to by pbase for an element that matches the object pointed to by key. The size of each element is specified by size. The array contents should be sorted in ascending order according to the compar comparison function. This routine should take two arguments pointing to the key and to an array element, in that order, and should return an integer less than, equal to, or greater than zero if the key object is respectively less than, matching, or greater than the array element.
int	qTypeGeneric_ForEach (void *pbase, const size_t size, const size_t n, qTypeGeneric_ForEachFcn_t f, const bool dir, void *arg)
	Iterates n elements of the array pointed to by pbase. The size of each element is specified by size. Every element should be handled by function f. The iteration loop can be aborted by returning 1.

Detailed Description

Type-generic utilities.

Function Documentation

qTypeGeneric_BSearch()

void * qTypeGeneric_BSearch	(	const void *	key,
		const void *	pbase,
		const size_t	n,
		const size_t	size,
		qTypeGeneric_CompareFcn_t	compar,
		void *	arg )

Performs a binary search over an array of n elements pointed to by pbase for an element that matches the object pointed to by key. The size of each element is specified by size. The array contents should be sorted in ascending order according to the compar comparison function. This routine should take two arguments pointing to the key and to an array element, in that order, and should return an integer less than, equal to, or greater than zero if the key object is respectively less than, matching, or greater than the array element.

Parameters

[in]	key	This is the pointer to the object that serves as key for the search, type-casted as a void*.
[in]	pbase	This is the pointer to the first object of the array where the search is performed, type-casted as a void*.
[in]	n	This is the number of elements in the array pointed by base.
[in]	size	This is the size in bytes of each element in the array.
[in]	compar	This is the function that compares two elements. The signature of the comparison function should be equivalent to the following: int compar( const void *a, const void *b, void *arg ); Comparison function which returns ​a negative integer value if the first argument is less than the second, a positive integer value if the first argument is greater than the second and zero if the arguments are equivalent. key is passed as the first argument, an element from the array as the second. The function must not modify the objects passed to it and must return consistent results when called for the same objects, regardless of their positions in the array.
[in]	arg	Additional information (e.g., collating sequence), passed to compar as the third argument

Returns

This function returns a pointer to an entry in the array that matches the search key. If key is not found, a NULL pointer is returned.

qTypeGeneric_ForEach()

int qTypeGeneric_ForEach	(	void *	pbase,
		const size_t	size,
		const size_t	n,
		qTypeGeneric_ForEachFcn_t	f,
		const bool	dir,
		void *	arg )

Iterates n elements of the array pointed to by pbase. The size of each element is specified by size. Every element should be handled by function f. The iteration loop can be aborted by returning 1.

Parameters

[in]	pbase	This is the pointer to the first object of the array type-casted as a void*.
[in]	n	This is the number of elements in the array pointed by pbase.
[in]	size	This is the size in bytes of each element in the array.
[in]	f	The function that will handle each element of the array The signature of this handling function should be equivalent to the following: int iterFcn( int i, void *element, void *arg ); The argument i is used to keep track of the iteration in which the loop is. i < 0 Loop its a about to start (pre-loop invocation). The element argument at this stage its passed as NULL and should not be dereferenced. [ 0 <= i < n ] Loop its iterating and the element argument is pointing to the array at index i. i == n Loop has ended (pos-loop invocation). The element argument at this stage its passed as NULL and should not be dereferenced.
[in]	dir	Pass true to iterate the array backwards.
[in]	arg	Additional information (e.g., collating sequence), passed to f as the third argument

Returns

This function returns 1 if the iteration loop is aborted otherwise returns 0.

qTypeGeneric_LSearch()

void * qTypeGeneric_LSearch	(	const void *	key,
		const void *	pbase,
		const size_t	n,
		const size_t	size,
		qTypeGeneric_CompareFcn_t	compar,
		void *	arg )

Performs a linear search over an array of n elements pointed to by pbase for an element that matches the object pointed to by key. The size of each element is specified by size. The array contents should be sorted in ascending order according to the compar comparison function. This routine should take two arguments pointing to the key and to an array element, in that order, and should return an integer less than, equal to, or greater than zero if the key object is respectively less than, matching, or greater than the array element.

Parameters

[in]	key	This is the pointer to the object that serves as key for the search, type-casted as a void*.
[in]	pbase	This is the pointer to the first object of the array where the search is performed, type-casted as a void*.
[in]	n	This is the number of elements in the array pointed by pbase.
[in]	size	This is the size in bytes of each element in the array.
[in]	compar	This is the function that compares two elements. The signature of the comparison function should be equivalent to the following: int compar( const void *a, const void *b, void *arg ); Comparison function which returns ​a negative integer value if the first argument is less than the second, a positive integer value if the first argument is greater than the second and zero if the arguments are equivalent. key is passed as the first argument, an element from the array as the second. The function must not modify the objects passed to it and must return consistent results when called for the same objects, regardless of their positions in the array.
[in]	arg	Additional information (e.g., collating sequence), passed to compar as the third argument

Returns

This function returns a pointer to an entry in the array that matches the search key. If key is not found, a NULL pointer is returned.

qTypeGeneric_Reverse()

void qTypeGeneric_Reverse	(	void *const	pbase,
		const size_t	size,
		const size_t	init,
		const size_t	end )

Reverse the given array pointed to by pbase. Operation takes place on the portion of the array that starts at position init to position end.

Parameters

[in,out]	pbase	Pointer to the array to reverse.
[in]	size	Size of each element in the array in bytes
[in]	init	Position of the first element.
[in]	end	Position of the last element.

Returns

none.

qTypeGeneric_Rotate()

void qTypeGeneric_Rotate	(	void *const	pbase,
		const size_t	size,
		const size_t	n,
		const int	k )

Rotates k elements of the array pointed to by pbase. The array contains n elements of size bytes. Rotation direction is determined by the sign of k, the means a positive value performs a right-rotation and a negative value a left-rotation.

Parameters

[in,out]	pbase	Pointer to the array to reverse.
[in]	size	Size of each element in the array in bytes
[in]	n	Number of elements in the array.
[in]	k	Positions to rotate.

Returns

none.

qTypeGeneric_Set()

void * qTypeGeneric_Set	(	void *const	pbase,
		const size_t	size,
		const size_t	n,
		const void *const	ref )

Set the data pointed by ref to every element of the array pointed by pbase. The array contains n elements of size bytes.

Parameters

[in,out]	pbase	Pointer to the array to reverse.
[in]	size	Size of each element in the array in bytes
[in]	n	Number of elements in the array.
[in]	ref	Pointer to the value to be set.

Returns

This function returns a pointer to the memory area pbase

qTypeGeneric_Sort()

void qTypeGeneric_Sort	(	void *const	pbase,
		size_t	n,
		size_t	size,
		qTypeGeneric_CompareFcn_t	cmp,
		void *	arg )

Sorts the given array pointed to by pbase in ascending order. The array contains n elements of size bytes. Function pointed to by cmp is used for object comparison.

Remarks

This algorithm uses a non-recursive variant of the quicksort algorithm.

Parameters

[in,out]	pbase	Pointer to the array to sort.
[in]	n	Number of elements in the array.
[in]	size	size of each element in the array in bytes
[in]	cmp	Comparison function which returns ​a negative integer value if the first argument is less than the second, a positive integer value if the first argument is greater than the second and zero if the arguments are equivalent. The signature of the comparison function should be equivalent to the following: int cmp( const void *a, const void *b, void *arg ); The function must not modify the objects passed to it and must return consistent results when called for the same objects, regardless of their positions in the array.
[in]	arg	Additional information (e.g., collating sequence), passed to cmp as the third argument

Returns

none.

qTypeGeneric_Swap()

void qTypeGeneric_Swap	(	void *const	x,
		void *const	y,
		size_t	n )

Swaps the data pointed by x and y.

Parameters

[in,out]	x	Pointer to data to be swapped.
[in,out]	y	Pointer to data to be swapped.
[in]	n	The size of the data to be swapped.

Returns

none.