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

Setset_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.
SetValueset_to_array (Set *set)
 Create an array containing all entries in a set.
Setset_union (Set *set1, Set *set2)
 Perform a union of two sets.
Setset_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.


Generated on Sun Sep 14 03:08:02 2008 for C Algorithms by  doxygen 1.5.5