cctools
Functions
set.h File Reference

A set data structure. More...

#include "int_sizes.h"
#include "list.h"

Go to the source code of this file.

Functions

struct set * set_create (int buckets)
 Create a new set. More...
 
struct set * set_duplicate (struct set *s)
 Duplicate a set from an existing set. More...
 
struct set * set_union (struct set *s1, struct set *s2)
 Unions two sets into one set. More...
 
void set_clear (struct set *s)
 Remove all entries from a set. More...
 
void set_delete (struct set *s)
 Delete a set. More...
 
int set_size (struct set *s)
 Count the entries in a set. More...
 
int set_insert (struct set *s, const void *element)
 Insert an element to the set. More...
 
int set_insert_set (struct set *s, struct set *s2)
 Insert an existing set into the set. More...
 
int set_insert_list (struct set *s, struct list *l)
 Insert an existing list into the set. More...
 
int set_push (struct set *h, const void *element)
 Insert an element to the set. More...
 
int set_lookup (struct set *s, void *element)
 Look up a element in the set. More...
 
int set_remove (struct set *s, const void *element)
 Remove an element. More...
 
void * set_pop (struct set *s)
 Remove an arbitrary element from the set. More...
 
void set_first_element (struct set *s)
 Begin iteration over all the elements. More...
 
void * set_next_element (struct set *s)
 Continue iteration over all elements. More...
 

Detailed Description

A set data structure.

Arbitrary objects that are equal (the same location in memory) appear only once in the set. For example, as a set of filenames:

struct set *s;
s = set_create(0);
set_push(s,pathname);
set_push(s,pathname_b);
set_push(s,pathname);
assert(set_size(s) == 2);
path = set_pop(s);
assert(set_size(s) == 1);

To list all of the elements in a set, use set_first_element and set_next_element like this:

void *element;
set_first_element(s);
while(element = set_next_element(s)) {
        printf("set contains: %x\n", element);
}

Function Documentation

struct set* set_create ( int  buckets)

Create a new set.

Parameters
bucketsThe number of elements in the set. If zero, a default element will be used. Increases dynamically as needed.
Returns
A pointer to a new set.
struct set* set_duplicate ( struct set *  s)

Duplicate a set from an existing set.

NOTE: This does not duplicated the element pointers, beware of double frees.

Parameters
sThe set to be duplicated.
Returns
A pointer to a new set.
struct set* set_union ( struct set *  s1,
struct set *  s2 
)

Unions two sets into one set.

Could also be called Merge. NOTE: This does not duplicated the element pointers, beware of double frees.

Parameters
s1A pointer to the first set to be unioned.
s2A pointer to the second set to be unioned.
Returns
A pointer to a new set.
void set_clear ( struct set *  s)

Remove all entries from a set.

Note that this function will not free all of the objects contained within the set.

Parameters
sA pointer to a set.
void set_delete ( struct set *  s)

Delete a set.

Note that this function will not free all of the objects contained within the set.

Parameters
sA pointer to a set.
int set_size ( struct set *  s)

Count the entries in a set.

Returns
The number of entries in the set.
Parameters
sA pointer to a set.
int set_insert ( struct set *  s,
const void *  element 
)

Insert an element to the set.

This call will return 0 if element was already in the set. You must call set_remove to remove it. Also note that you cannot insert a null element into the set.

Parameters
sA pointer to a set.
elementA pointer to store.
Returns
One if the insert succeeded, 0 otherwise.
int set_insert_set ( struct set *  s,
struct set *  s2 
)

Insert an existing set into the set.

This call will return 1 if all elements of s2 exist or are added to the set. Also note that you cannot insert a null set into the set. NOTE: This does not duplicated the element pointers, beware of double frees.

Parameters
sA pointer to a set.
s2A pointer to a set to be inserted.
Returns
Number of items added to set.
int set_insert_list ( struct set *  s,
struct list *  l 
)

Insert an existing list into the set.

This call will return 1 if all elements of list exist or are added to the set. Also note that you cannot insert a null list into the set. NOTE: This does not duplicated the element pointers, beware of double frees.

Parameters
sA pointer to a set.
lA pointer to a list to be inserted.
Returns
Number of items added to set.
int set_push ( struct set *  h,
const void *  element 
)

Insert an element to the set.

This is equivalent to set_insert

int set_lookup ( struct set *  s,
void *  element 
)

Look up a element in the set.

Parameters
sA pointer to a set.
elementA pointer to search for.
Returns
If found, 1, otherwise 0.
int set_remove ( struct set *  s,
const void *  element 
)

Remove an element.

Parameters
sA pointer to a set.
elementA pointer to remove.
Returns
If found 1, otherwise 0.
void* set_pop ( struct set *  s)

Remove an arbitrary element from the set.

Parameters
sA pointer to a set.
Returns
The pointer removed.
void set_first_element ( struct set *  s)

Begin iteration over all the elements.

This function begins a new iteration over a set, allowing you to visit every element in the set. Next, invoke set_next_element to retrieve each element in order.

Parameters
sA pointer to a set.
void* set_next_element ( struct set *  s)

Continue iteration over all elements.

This function returns the next element in the iteration.

Parameters
sA pointer to a set.
Returns
zero if there are no more elements to visit, the next element otherwise.