TpIntSet

TpIntSet — a set of unsigned integers

Synopsis


#include <telepathy-glib/intset.h>


                    TpIntSet;
void                (*TpIntFunc)                        (guint i,
                                                         gpointer userdata);
TpIntSet*           tp_intset_sized_new                 (guint size);
TpIntSet*           tp_intset_new                       (void);
void                tp_intset_destroy                   (TpIntSet *set);
void                tp_intset_clear                     (TpIntSet *set);
void                tp_intset_add                       (TpIntSet *set,
                                                         guint element);
gboolean            tp_intset_remove                    (TpIntSet *set,
                                                         guint element);
gboolean            tp_intset_is_member                 (const TpIntSet *set,
                                                         guint element);
void                tp_intset_foreach                   (const TpIntSet *set,
                                                         TpIntFunc func,
                                                         gpointer userdata);
GArray*             tp_intset_to_array                  (TpIntSet *set);
TpIntSet*           tp_intset_from_array                (GArray *array);
guint               tp_intset_size                      (const TpIntSet *set);
gboolean            tp_intset_is_equal                  (const TpIntSet *left,
                                                         const TpIntSet *right);
TpIntSet*           tp_intset_copy                      (const TpIntSet *orig);
TpIntSet*           tp_intset_intersection              (const TpIntSet *left,
                                                         const TpIntSet *right);
TpIntSet*           tp_intset_union                     (const TpIntSet *left,
                                                         const TpIntSet *right);
TpIntSet*           tp_intset_difference                (const TpIntSet *left,
                                                         const TpIntSet *right);
TpIntSet*           tp_intset_symmetric_difference      (const TpIntSet *left,
                                                         const TpIntSet *right);
gchar*              tp_intset_dump                      (const TpIntSet *set);
#define             TP_INTSET_ITER_INIT                 (set)
                    TpIntSetIter;
gboolean            tp_intset_iter_next                 (TpIntSetIter *iter);

Description

A TpIntSet is a set of unsigned integers, implemented as a dynamically-allocated bitfield.

Details

TpIntSet

typedef struct _TpIntSet TpIntSet;

Opaque type representing a set of unsigned integers.

TpIntFunc ()

void                (*TpIntFunc)                        (guint i,
                                                         gpointer userdata);

A callback function acting on unsigned integers.

i : The relevant integer
userdata : Opaque user data

tp_intset_sized_new ()

TpIntSet*           tp_intset_sized_new                 (guint size);

Allocate an integer set just large enough to store the given number of bits, rounded up as necessary.

The set will still expand automatically if you store larger integers; this is just an optimization to avoid wasting memory (if the set is too large) or time (if the set is too small and needs reallocation).

size : 1 more than the largest integer you expect to store
Returns : a new, empty integer set to be destroyed with tp_intset_destroy()

tp_intset_new ()

TpIntSet*           tp_intset_new                       (void);

Allocate a new integer set with a default memory allocation.

Returns : a new, empty integer set to be destroyed with tp_intset_destroy()

tp_intset_destroy ()

void                tp_intset_destroy                   (TpIntSet *set);

Free all memory used by the set.

set : set

tp_intset_clear ()

void                tp_intset_clear                     (TpIntSet *set);

Unset every integer in the set.

set : set

tp_intset_add ()

void                tp_intset_add                       (TpIntSet *set,
                                                         guint element);

Add an integer into a TpIntSet.

set : set
element : integer to add

tp_intset_remove ()

gboolean            tp_intset_remove                    (TpIntSet *set,
                                                         guint element);

Remove an integer from a TpIntSet

set : set
element : integer to add
Returns : TRUE if element was previously in set

tp_intset_is_member ()

gboolean            tp_intset_is_member                 (const TpIntSet *set,
                                                         guint element);

Tests if element is a member of set

set : set
element : integer to test
Returns : TRUE if element is in set

tp_intset_foreach ()

void                tp_intset_foreach                   (const TpIntSet *set,
                                                         TpIntFunc func,
                                                         gpointer userdata);

Call func(element, userdata) for each element of set.

set : set
func : TpIntFunc to use to iterate the set
userdata : user data to pass to each call of func

tp_intset_to_array ()

GArray*             tp_intset_to_array                  (TpIntSet *set);

set : set to convert
Returns : a GArray of guint (which must be freed by the caller) containing the same integers as set.

tp_intset_from_array ()

TpIntSet*           tp_intset_from_array                (GArray *array);

array : An array of guint
Returns : A set containing the same integers as array.

tp_intset_size ()

guint               tp_intset_size                      (const TpIntSet *set);

set : A set of integers
Returns : The number of integers in set

tp_intset_is_equal ()

gboolean            tp_intset_is_equal                  (const TpIntSet *left,
                                                         const TpIntSet *right);

left : A set of integers
right : A set of integers
Returns : TRUE if left and right contain the same bits

tp_intset_copy ()

TpIntSet*           tp_intset_copy                      (const TpIntSet *orig);

orig : A set of integers
Returns : A set containing the same integers as orig, to be freed with tp_intset_destroy() by the caller

tp_intset_intersection ()

TpIntSet*           tp_intset_intersection              (const TpIntSet *left,
                                                         const TpIntSet *right);

left : The left operand
right : The right operand
Returns : The set of those integers which are in both left and right (analogous to the bitwise operation left & right), to be freed with tp_intset_destroy() by the caller

tp_intset_union ()

TpIntSet*           tp_intset_union                     (const TpIntSet *left,
                                                         const TpIntSet *right);

left : The left operand
right : The right operand
Returns : The set of those integers which are in either left or right (analogous to the bitwise operation left | right), to be freed with tp_intset_destroy() by the caller

tp_intset_difference ()

TpIntSet*           tp_intset_difference                (const TpIntSet *left,
                                                         const TpIntSet *right);

left : The left operand
right : The right operand
Returns : The set of those integers which are in left and not in right (analogous to the bitwise operation left & (~right)), to be freed with tp_intset_destroy() by the caller

tp_intset_symmetric_difference ()

TpIntSet*           tp_intset_symmetric_difference      (const TpIntSet *left,
                                                         const TpIntSet *right);

left : The left operand
right : The right operand
Returns : The set of those integers which are in either left or right but not both (analogous to the bitwise operation left ^ right), to be freed with tp_intset_destroy() by the caller

tp_intset_dump ()

gchar*              tp_intset_dump                      (const TpIntSet *set);

set : An integer set
Returns : a string which the caller must free with g_free, listing the numbers in set in a human-readable format

TP_INTSET_ITER_INIT()

#define TP_INTSET_ITER_INIT(set) { (set), (guint)(-1) }

A suitable static initializer for a TpIntSetIter, to be used as follows: 

void
do_something (const TpIntSet *intset)
{
  TpIntSetIter iter = TP_INTSET_ITER_INIT (intset);
  /* ... do something with iter ... */
}

set : A set of integers

TpIntSetIter

typedef struct {
    const TpIntSet *set;
    guint element;
} TpIntSetIter;

A structure representing iteration over a set of integers. Must be initialized with either TP_INTSET_ITER_INIT() or tp_intset_iter_init().

const TpIntSet *set; The set iterated over.
guint element; Must be (guint)(-1) before iteration starts. Set to the next element in the set by tp_intset_iter_next(); undefined after tp_intset_iter_next() returns FALSE.

tp_intset_iter_next ()

gboolean            tp_intset_iter_next                 (TpIntSetIter *iter);

If there are integers in (iter->set) higher than (iter->element), set (iter->element) to the next one and return TRUE. Otherwise return FALSE.

Usage: 

TpIntSetIter iter = TP_INT_SET_INIT (intset);
while (tp_intset_iter_next (&iter;))
{
  printf ("%u is in the intset\n", iter.element);
}

iter : An iterator originally initialized with TP_INT_SET_INITIALIZER(set)
Returns : TRUE if (iter->element) has been advanced

See Also

TpHandleSet