set.h File Reference

Set of values. More...

Data Structures

struct _SetIterator

Definition of a SetIterator. More...

Defines

#define SET_NULL ((void *) 0)

A null SetValue.

Typedefs

typedef struct _Set Set

Represents a set of values.

typedef struct _SetIterator SetIterator

An object used to iterate over a set.

typedef struct _SetEntry SetEntry

Internal structure representing an entry in the set.

typedef void * SetValue

A value stored in a Set.

typedef unsigned long(* SetHashFunc )(SetValue value)

Hash function.

typedef int(* SetEqualFunc )(SetValue value1, SetValue value2)

Equality function.

typedef void(* SetFreeFunc )(SetValue value)

Function used to free values stored in a set.

Functions

Set * set_new (SetHashFunc hash_func, SetEqualFunc equal_func)

Create a new set.

void set_free (Set *set)

Destroy a set.

void set_register_free_function (Set *set, SetFreeFunc free_func)

Register a function to be called when values are removed from the set.

int set_insert (Set *set, SetValue data)

Add a value to a set.

int set_remove (Set *set, SetValue data)

Remove a value from a set.

int set_query (Set *set, SetValue data)

Query if a particular value is in a set.

int set_num_entries (Set *set)

Retrieve the number of entries in a set.

SetValue * set_to_array (Set *set)

Create an array containing all entries in a set.

Set * set_union (Set *set1, Set *set2)

Perform a union of two sets.

Set * set_intersection (Set *set1, Set *set2)

Perform an intersection of two sets.

void set_iterate (Set *set, SetIterator *iter)

Initialise a SetIterator structure to iterate over the values in a set.

int set_iter_has_more (SetIterator *iterator)

Determine if there are more values in the set to iterate over.

SetValue set_iter_next (SetIterator *iterator)

Using a set iterator, retrieve the next value from the set.

Detailed Description

Set of values.

A set stores a collection of values. Each value can only exist once in the set.

To create a new set, use set_new. To destroy a set, use set_free.

To add a value to a set, use set_insert. To remove a value from a set, use set_remove.

To find the number of entries in a set, use set_num_entries.

To query if a particular value is in a set, use set_query.

To iterate over all values in a set, use set_iterate to initialise a SetIterator structure, with set_iter_next and set_iter_has_more to read each value in turn.

Two sets can be combined (union) using set_union, while the intersection of two sets can be generated using set_intersection.

Typedef Documentation

typedef struct _Set Set

Represents a set of values.

Created using the set_new function and destroyed using the set_free function.

typedef int(* SetEqualFunc)(SetValue value1, SetValue value2)

Equality function.

Compares two values to determine if they are equivalent.

typedef void(* SetFreeFunc)(SetValue value)

Function used to free values stored in a set.

See set_register_free_function.

typedef unsigned long(* SetHashFunc)(SetValue value)

Hash function.

Generates a hash key for values to be stored in a set.

typedef struct _SetIterator SetIterator

An object used to iterate over a set.

See also:: set_iterate

Function Documentation

void set_free ( Set * set )

Destroy a set.

Parameters:

set

The set to destroy.

int set_insert	(	Set *	set,
		SetValue	data
	)

Add a value to a set.

Parameters:

	set	The set.
	data	The value to add to the set.

Returns:: Non-zero (true) if the value was added to the set, zero (false) if it already exists in the set, or if it was not possible to allocate memory for the new entry.

Set* set_intersection	(	Set *	set1,
		Set *	set2
	)

Perform an intersection of two sets.

Parameters:

	set1	The first set.
	set2	The second set.

Returns:: A new set containing all values which are in both set, or NULL if it was not possible to allocate memory for the new set.

int set_iter_has_more ( SetIterator * iterator )

Determine if there are more values in the set to iterate over.

Parameters:

iterator

The set iterator object.

Returns:: Zero if there are no more values in the set to iterate over, non-zero if there are more values to be read.

SetValue set_iter_next ( SetIterator * iterator )

Using a set iterator, retrieve the next value from the set.

Parameters:

iterator

The set iterator.

Returns:: The next value from the set, or SET_NULL if no more values are available.

void set_iterate	(	Set *	set,
		SetIterator *	iter
	)

Initialise a SetIterator structure to iterate over the values in a set.

Parameters:

	set	The set to iterate over.
	iter	Pointer to an iterator structure to initialise.

Set* set_new	(	SetHashFunc	hash_func,
		SetEqualFunc	equal_func
	)

Create a new set.

Parameters:

	hash_func	Hash function used on values in the set.
	equal_func	Compares two values in the set to determine if they are equal.

Returns:: A new set, or NULL if it was not possible to allocate the memory for the set.

int set_num_entries ( Set * set )

Retrieve the number of entries in a set.

Parameters:

set

The set.

Returns:: A count of the number of entries in the set.

int set_query	(	Set *	set,
		SetValue	data
	)

Query if a particular value is in a set.

Parameters:

	set	The set.
	data	The value to query for.

Returns:: Zero if the value is not in the set, non-zero if the value is in the set.

void set_register_free_function	(	Set *	set,
		SetFreeFunc	free_func
	)

Register a function to be called when values are removed from the set.

Parameters:

	set	The set.
	free_func	Function to call when values are removed from the set.

int set_remove	(	Set *	set,
		SetValue	data
	)

Remove a value from a set.

Parameters:

	set	The set.
	data	The value to remove from the set.

Returns:: Non-zero (true) if the value was found and removed from the set, zero (false) if the value was not found in the set.

SetValue* set_to_array ( Set * set )

Create an array containing all entries in a set.

Parameters:

set

The set.

Returns:: An array containing all entries in the set, or NULL if it was not possible to allocate memory for the array.

Set* set_union	(	Set *	set1,
		Set *	set2
	)

Perform a union of two sets.

Parameters:

	set1	The first set.
	set2	The second set.

Returns:: A new set containing all values which are in the first or second sets, or NULL if it was not possible to allocate memory for the new set.


Data Structures
struct	_SetIterator
	Definition of a SetIterator. More...
Defines
#define	SET_NULL ((void *) 0)
	A null SetValue.
Typedefs
typedef struct _Set	Set
	Represents a set of values.
typedef struct _SetIterator	SetIterator
	An object used to iterate over a set.
typedef struct _SetEntry	SetEntry
	Internal structure representing an entry in the set.
typedef void *	SetValue
	A value stored in a Set.
typedef unsigned long(*	SetHashFunc )(SetValue value)
	Hash function.
typedef int(*	SetEqualFunc )(SetValue value1, SetValue value2)
	Equality function.
typedef void(*	SetFreeFunc )(SetValue value)
	Function used to free values stored in a set.
Functions
Set *	set_new (SetHashFunc hash_func, SetEqualFunc equal_func)
	Create a new set.
void	set_free (Set *set)
	Destroy a set.
void	set_register_free_function (Set *set, SetFreeFunc free_func)
	Register a function to be called when values are removed from the set.
int	set_insert (Set *set, SetValue data)
	Add a value to a set.
int	set_remove (Set *set, SetValue data)
	Remove a value from a set.
int	set_query (Set *set, SetValue data)
	Query if a particular value is in a set.
int	set_num_entries (Set *set)
	Retrieve the number of entries in a set.
SetValue *	set_to_array (Set *set)
	Create an array containing all entries in a set.
Set *	set_union (Set set1, Set set2)
	Perform a union of two sets.
Set *	set_intersection (Set set1, Set set2)
	Perform an intersection of two sets.
void	set_iterate (Set set, SetIterator iter)
	Initialise a SetIterator structure to iterate over the values in a set.
int	set_iter_has_more (SetIterator *iterator)
	Determine if there are more values in the set to iterate over.
SetValue	set_iter_next (SetIterator *iterator)
	Using a set iterator, retrieve the next value from the set.