#include <stdio.h>
#include <stdlib.h>
#include "set.h"

Functions
Set	SETinit (int(match)(const void key1, const void key2), void(destroy)(void *data))

void	SETdestroy (Set set)

int	SETinsert (Set set, const void *data)

int	SETremove (Set set, void **data)

Set	SETunion (Set set1, Set set2)

Set	SETintersection (Set set1, Set set2)

Set	SETdifference (Set set1, Set set2)

int	SETis_member (Set set, const void *data)

int	SETis_subset (const Set set1, const Set set2)

int	SETis_equal (Set set1, Set set2)

int	SETsize (Set set)

void	SETsort (Set set, int(cmp)(const void key1, const void *key2))

void	SETtraverse (Set set, void(callback)(const void data), int direction)

Function Documentation

void SETdestroy ( Set set )

Destroy the set.

The set is destroyed - that is, all the memory occupied by the nodes is deallocated. The user-defined callback function destroy, given as an argument to SETinit(), is responsible for freeing dynamically allocated node data, when this function is called. When all nodes and data have been deallocated - the set header is deallocated, too.

Parameters

[in] set - a reference to current set.

Returns: Nothing.

See Also: SETinit()

Definition at line 43 of file set.c.

Set SETdifference	(	Set	set1,
		Set	set2
	)

Build the difference of two given sets

Parameters

set1	- one of the given sets, taking part, together with set2, in building the difference.
set2	- the other set, that makes up the difference - together with set1.

Returns: A new set - equal to the difference of set1 and set2 - i.e. mathematically speaking, containing all the elements only present in set1.

Definition at line 140 of file set.c.

Set SETinit	(	int()(const void key1, const void *key2)	match,
		void()(void data)	destroy
	)

Initialize the set

Parameters

[in]	match	- a reference to a user-defined function that receives references to node data - and search key data - via its parameters key1 and key2. Hence this callback function can make the actual matching of search key and node data and determine if search data is present in the set. This callback function shall return 1 - in case of a hit - or 0 otherwise.
[in]	destroy	- A reference to a user-made function, reponsible for freeing node data, when the set is deleted. If destroy is NULL - then node data will be left untouched when the set is destroyed.

Returns: A reference - to a new, empty set - if dynamic memory allocation for the ADT was successful - or NULL otherwise. Take really good care of this return value, since it will be needed as a parameter in subsequent calls - to the majority of other set handling functions in this function interface - i.e. a sort of "handle" to the set.

See Also: SETdestroy()

Definition at line 30 of file set.c.

int SETinsert	(	Set	set,
		const void *	data
	)

Insert data into the set.

Parameters

[in]	set	- a reference to current set.
[in]	data	- reference to data to be inserted into the set.

Returns: Value 0 - if insertion was successful.
Value 1 - if insertion was rejected - i.e. if data is already present in the set.
Value -1 - otherwise, if another sort of error occurred.

Definition at line 49 of file set.c.

Set SETintersection	(	Set	set1,
		Set	set2
	)

Build the intersection of two given sets.

Parameters

set1	- one of the given sets, taking part of building the intersection.
set2	- the other set, that comprises the intersection together with set1.

Returns: A new set - equal to the intersection of set1 and set2 - i.e. mathematically speaking, containing all the elements common to set1 and set2.

Definition at line 112 of file set.c.

int SETis_equal	(	Set	set1,
		Set	set2
	)

Determine whether one set is equal to another

Parameters

set1	- a reference to one of the sets - tested for equality.
set2	- a reference to the other.

Returns: Value 1 - if set1 is equal to set2 - or 0 otherwise.

Definition at line 196 of file set.c.

int SETis_member	(	Set	set,
		const void *	data
	)

Determine whether a data member exists in a given set

Parameters

set	- a reference to current set.
data	- a reference to element key data.

Returns: Value 1 - if data is member of set - or 0 ohterwise.

Definition at line 168 of file set.c.

int SETis_subset	(	const Set	set1,
		const Set	set2
	)

Determine whether one set is a subset of another

Parameters

set1	- a reference to the set, tested for being a subset of set2.
set2	- a reference to the set that might contain set1 as a subset.

Returns: Value 1 - if set1 is a subset of set2 - or 0 otherwise.

Definition at line 177 of file set.c.

int SETremove	(	Set	set,
		void **	data
	)

Search and remove data - by an in/out parameter

When called, the 2nd parameter of this function, data, should reference a pointer, that points to the search key data. After the call - this (external) pointer referenced by parameter data, has been redirected to point to data of the removed node - if the call was succesful. The caller is responsible for the future of this memory - deallocating it, if needed, for example.

Parameters

[in]	set	- reference to current set.
[in,out]	data	- reference to an external pointer, that initially shall point to the search key data - when this function is called. After the call, this referenced (external) pointer, has been redirected - to point to node data of the removed node - if the call was successful. The caller is responsible for the future of this memory - deallocating it, for example.

Returns: Value 0 – if the call was OK - that is, node found and removed.
Value 1 – node not found.
Value -1 – otherwise (implies fatal error).

Definition at line 60 of file set.c.

int SETsize ( Set set )

Get the size of a set

Parameters

set	- a reference to current set.

Returns: The size - i.e. number of elements in the set.

Definition at line 207 of file set.c.

void SETsort	(	Set	set,
		int()(const void key1, const void *key2)	cmp
	)

Sort a set

Parameters

[in]	set	- reference to current set.
[in]	cmp	- reference to a user-defined callback function responsible for comparing element data. This callback function should return a value of -1 if data referenced by key1 is less than data referenced by key2 - or 0 if they are equal - or 1 otherwise. This will produce an ascending sort order. If a descending order is what you want - just swap the return values -1 and 1 for the comparisons made above.

Returns: Nothing.

Definition at line 213 of file set.c.

void SETtraverse	(	Set	set,
		void()(const void data)	callback,
		int	direction
	)

Traverse all elements of the set

Parameters

[in]	set	- reference to current set.
[in]	callback	- reference to user-defined callback function, that gets read access to node data via its parameter data - to do whatever is relevant. Print data, for example.
[in]	direction	- direction of traversal. Set to SET_FWD for forward traversal - and SET_BWD for traversing backwards.

Returns: Nothing.

Definition at line 219 of file set.c.

Set SETunion	(	Set	set1,
		Set	set2
	)

Build the union of two given sets.

Parameters

set1	- one of the given sets, taking part of building the union.
set2	- the other set, that comprises the union together with set1.

Returns: A new set - equal to the union of set1 and set2 - i.e. mathematically speaking, containing all the elements either in set1 and set2 - or in both.

Definition at line 66 of file set.c.

Functions

Function Documentation