The Set Library  0.2.1
Typedefs
set.h File Reference

Documentation for Set Library (CDSL) More...

#include <stddef.h>
Include dependency graph for set.h:
This graph shows which files directly or indirectly include this file:

Typedefs

typedef struct set_t set_t
 represents a set.

Functions

set creating/destroying functions:
set_tset_new (int, int(const void *, const void *), unsigned(const void *))
void set_free (set_t **)
 destroys a set.
data/information retrieving functions:
size_t set_length (set_t *)
 returns the length of a set.
int set_member (set_t *, const void *)
 inspects if a set contains a member.
void set_put (set_t *, const void *)
 puts a member to a set.
void * set_remove (set_t *, const void *)
 removes a member from a set.
set handling functions:
void set_map (set_t *, void(const void *, void *), void *)
void ** set_toarray (set_t *, void *)
 converts a set to an array.
set operation functions:
set_tset_union (set_t *, set_t *)
 returns a union set of two sets.
set_tset_inter (set_t *, set_t *)
 returns an intersection of two sets.
set_tset_minus (set_t *, set_t *)
 returns a difference set of two sets
set_tset_diff (set_t *, set_t *)
 returns a symmetric difference of two sets.

Detailed Description

Documentation for Set Library (CDSL)

Header for Set Library (CDSL)


Function Documentation

set_t* set_diff ( set_t s,
set_t t 
)

returns a symmetric difference of two sets.

set_diff() returns a symmetric difference of two sets, that is a set with members only one of two operand sets has. A symmetric difference set is identical to the union set of (s - t) and (t - s). See set_union() for more detailed explanation commonly applied to the set operation functions.

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: foreign data structure given for s or t

Parameters:
[in]soperand of set difference operation
[in]toperand of set difference operation
Returns:
symmetric difference set
Todo:
Improvements are possible and planned:
  • the code can be modified so that the operation is performed on each pair of corresponding buckets when two given sets have the same number of buckets.

Here is the call graph for this function:

void set_free ( set_t **  pset)

destroys a set.

set_free() destroys a set by deallocating the storage for it and set a given pointer to a null pointer. As always, set_free() does not deallocate any storage for members in the set, which must be done by a user.

Possible exceptions: assert_exceptfail

Unchecked errors: pointer to foreign data structure given for pset

Parameters:
[in,out]psetpointer to set to destroy
Returns:
nothing
set_t* set_inter ( set_t s,
set_t t 
)

returns an intersection of two sets.

set_inter() returns an intersection of two sets, that is a set with only members that both have in common. See set_union() for more detailed explanation commonly applied to the set operation functions.

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: foreign data structure given for s or t

Parameters:
[in]soperand of set intersection operation
[in]toperand of set intersection operation
Returns:
intersection set
Todo:
Improvements are possible and planned:
  • the code can be modified so that the operation is performed on each pair of corresponding buckets when two given sets have the same number of buckets.

Here is the call graph for this function:

Here is the caller graph for this function:

size_t set_length ( set_t set)

returns the length of a set.

set_length() returns the length of a set which is the number of members in a set.

Possible exceptions: assert_exceptfail

Unchecked errors: foreign data structure given for set

Parameters:
[in]setset whose length to be returned
Returns:
length of set
int set_member ( set_t set,
const void *  member 
)

inspects if a set contains a member.

set_member() inspects a set to see if it contains a member.

Possible exceptions: assert_exceptfail

Unchecked errors: foreign data structure given for set

Parameters:
[in]setset to inspect
[in]membermember to find in a set
Returns:
found/not found indicator
Return values:
0member not found
1member found

Here is the caller graph for this function:

set_t* set_minus ( set_t s,
set_t t 
)

returns a difference set of two sets

set_minus() returns a difference of two sets, that is a set with members that t has but does not. See set_union() for more detailed explanation commonly applied to the set operation functions.

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: foreign data structure given for s or t

Parameters:
[in]soperand of set difference operation
[in]toperand of set difference operation
Returns:
difference set, s - t
Todo:
Improvements are possible and planned:
  • the code can be modified so that the operation is performed on each pair of corresponding buckets when two given sets have the same number of buckets.

Here is the call graph for this function:

void set_put ( set_t set,
const void *  member 
)

puts a member to a set.

set_put() inserts a member to a set. If it fails to find a member matched to a given member, it inserts the member to a set after proper storage allocation. If it finds a matched one, it replaces an existing member with a new one. Because they has different representations even if they compare equal by a user-defined comparison function, replacing the old one with the new one makes sense.

Note that a member is a pointer. If members are, say, integers in an application, objects to contain them are necessary to put them into a set.

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: foreign data structure given for set

Parameters:
[in,out]setset to which member inserted
[in]membermember to insert
Returns:
nothing

Here is the caller graph for this function:

void* set_remove ( set_t set,
const void *  member 
)

removes a member from a set.

set_remove() gets rid of a member from a set. Note that set_remove() does not deallocate any storage for the member to remove, which must be done by a user.

Possible exceptions: assert_exceptfail

Unchecked errors: foreign data structure given for set

Parameters:
[in,out]setset from whcih member removed
[in]membermember to remove
Returns:
previous member or null pointer
Return values:
non-nullprevious member
NULLmember not found
Warning:
If the stored member is a null pointer, an ambiguous situation may occur.
void** set_toarray ( set_t set,
void *  end 
)

converts a set to an array.

set_toarray() converts members stored in a set to an array. The last element of the constructed array is assigned by end, which is a null pointer in most cases. Do not forget deallocate the array when it is unnecessary.

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: foreign data structure given for set

Warning:
The size of an array generated from an empty set cannot be zero, since there is always an end-mark value.
As in set_map(), the order in which an array is created for each member is unspecified.
Parameters:
[in]setset for which array generated
[in]endend-mark to save in last element of array
Returns:
array generated from set
set_t* set_union ( set_t s,
set_t t 
)

returns a union set of two sets.

set_union() creates a union set of two sets and returns it. One of those may be a null pointer, in which case it is considered an empty set. For every operation, its result constitutes a distinct set from the operand sets, which means the set operations always allocate storage for their results even when one of the operands is empty.

Note that the inferface of the Set Library does not assume the concept of a universe, which is the set of all possible members. Thus, a set operation like the complement is not defined and not implemented.

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: foreign data structure given for s or t

Warning:
To create a union of two sets, they have to share the same comparison and hashing functions.
Parameters:
[in]soperand of set union operation
[in]toperand of set union operation
Returns:
union set
Todo:
Improvements are possible and planned:
  • the code can be modified so that the operation is performed on each pair of corresponding buckets when two given sets have the same number of buckets.

Here is the call graph for this function:

 All Files Functions Typedefs