common.h File Reference

Go to the source code of this file.

Macros
#define	CSTL_MAX_T(T, A, B)   (((T)A >= (T)B) ? (T)A : (T)B)
	Return the maximum of two values.

Typedefs
typedef int	cstl_compare_func_t(const void *obj1, const void *obj2, void *priv)
	Function type for comparing (in)equality of two objects.
typedef int	cstl_visit_func_t(void *obj, void *priv)
	Type for visit callbacks from objects supporting foreach.
typedef int	cstl_const_visit_func_t(const void *obj, void *priv)
	Type for const visit callbacks from objects supporting foreach.
typedef void	cstl_xtor_func_t(void *obj, void *priv)
	Type for functions called to construct, clear, or destroy an object.
typedef void	cstl_swap_func_t(void *a, void *b, void *t, size_t len)
	Type of function called to swap two objects.

Enumerations
enum	cstl_sort_algorithm_t {   CSTL_SORT_ALGORITHM_QUICK , CSTL_SORT_ALGORITHM_QUICK_R , CSTL_SORT_ALGORITHM_QUICK_M , CSTL_SORT_ALGORITHM_HEAP ,   CSTL_SORT_ALGORITHM_DEFAULT = CSTL_SORT_ALGORITHM_QUICK_M }
	Enumeration indicating the desired sort algorithm. More...

Functions
static void	cstl_swap (void *const x, void *const y, void *const t, const size_t sz)
	Swap values at two memory locations via use of a third.
int	cstl_fls (unsigned long)
	Find the last (highest order) bit set.

Macro Definition Documentation

CSTL_MAX_T

#define CSTL_MAX_T	(		T,
			A,
			B
	)		(((T)A >= (T)B) ? (T)A : (T)B)

Return the maximum of two values.

Parameters

[in]	T	The type of the values
[in]	A	An input to the comparison
[in]	B	An(other) input to the comparison

Returns

The value of the maximum of the two inputs

Definition at line 180 of file common.h.

Typedef Documentation

cstl_compare_func_t

typedef int cstl_compare_func_t(const void *obj1, const void *obj2, void *priv)

Function type for comparing (in)equality of two objects.

Parameters

[in]	obj1	A pointer to an object
[in]	obj2	A pointer to an object
[in]	priv	A pointer to private data belonging to the callee

Return values

<0	obj1 compares as less than obj2
0	obj1 compares as equal to obj2
>0	obj1 compares as greater than obj2

Definition at line 49 of file common.h.

cstl_const_visit_func_t

typedef int cstl_const_visit_func_t(const void *obj, void *priv)

Type for const visit callbacks from objects supporting foreach.

Parameters

[in]	obj	A pointer to the object being visited
[in]	priv	A pointer to private data belonging to the callee

For functions supporting the foreach functionality, this type of function will be used when the callee is not allowed to modify the object being passed to the function.

Return values

0	The foreach function should visit the next object
Nonzero	The foreach function should stop visiting objects

Definition at line 80 of file common.h.

cstl_swap_func_t

typedef void cstl_swap_func_t(void *a, void *b, void *t, size_t len)

Type of function called to swap two objects.

Parameters

[in,out]	a	A pointer to an object to be swapped with b
[in,out]	b	A pointer to an object to be swapped with a
[in]	t	A pointer to temporary/scratch space
[in]	len	The number of bytes pointed to by t, which is equal to the number of bytes pointed to by a and b, as well.

The library deals with void pointers, and therefore cannot swap objects any more efficiently than by copying them with the aid of scratch memory to avoid overwriting data. The use of void pointers also means that the library can't know what members are within the objects and update them if necessary when they are moved to a new location. In places where this occurs, the API allows callers to specify a swap function to handle these issues. The callee is free to ignore the t and len parameters.

See also

cstl_swap()

Definition at line 118 of file common.h.

cstl_visit_func_t

typedef int cstl_visit_func_t(void *obj, void *priv)

Type for visit callbacks from objects supporting foreach.

Parameters

[in]	obj	A pointer to the object being visited
[in]	priv	A pointer to private data belonging to the callee

For functions supporting the foreach functionality, this type of function will be used when the callee is allowed to modify the object being passed to the function.

Return values

0	The foreach function should visit the next object
Nonzero	The foreach function should stop visiting objects

Definition at line 65 of file common.h.

cstl_xtor_func_t

typedef void cstl_xtor_func_t(void *obj, void *priv)

Type for functions called to construct, clear, or destroy an object.

Parameters

[in]	obj	A pointer to the object being visited
[in]	priv	A pointer to private data belonging to the callee

Exactly how the callee should react to a call of this type is context-specific. For construction, generally, the object has been allocated, and the purpose of the call is to initialize the object. The clear/destroy distinction is not always clear and depends very much on the context. In some cases, it simply means that the memory is no longer meant to hold the particular object, and the callee should clear/free any data held by the object. In other cases, it may mean to free the object itself (or both).

Definition at line 97 of file common.h.

Enumeration Type Documentation

cstl_sort_algorithm_t

enum cstl_sort_algorithm_t

Enumeration indicating the desired sort algorithm.

Enumerator
CSTL_SORT_ALGORITHM_QUICK	Quicksort.
CSTL_SORT_ALGORITHM_QUICK_R	Randomized quicksort.
CSTL_SORT_ALGORITHM_QUICK_M	Median-of-three quicksort.
CSTL_SORT_ALGORITHM_HEAP	Heapsort.
CSTL_SORT_ALGORITHM_DEFAULT	Unspecified default algorithm.

Definition at line 23 of file common.h.

Function Documentation

cstl_fls()

int cstl_fls

(

unsigned long

x

)

Find the last (highest order) bit set.

Returns

Zero-based index of the highest order set bit

Return values

-1	No bits are set, i.e. the input value is zero

Definition at line 7 of file common.c.

cstl_swap()

static void cstl_swap ( void *const  x, void *const  y, void *const  t, const size_t  sz  )

inlinestatic

Swap values at two memory locations via use of a third.

Parameters

[in,out]	x	A pointer to the first value to be swapped
[in,out]	y	A pointer to the second value to be swapped
[out]	t	Scratch space that may be used to facilitate the swap
[in]	sz	The number of bytes pointed to by x, y, and t

The values pointed to by x and y are swapped as if by memcpy(). The space at t may be used as a temporary/scratch space to facilitate the swap. The space pointed to by x, y, and t must be at least sz bytes in length.

Definition at line 137 of file common.h.