## TpIntset TpIntset — a set of unsigned integers |

## Synopsis

    #include <telepathy-glib/intset.h>

                        TpIntset;
    #define             TP_TYPE_INTSET
    void                (*TpIntFunc)                        (guint i,
                                                             gpointer userdata);
    TpIntset *          tp_intset_sized_new                 (guint size);
    TpIntset *          tp_intset_new                       (void);
    TpIntset *          tp_intset_new_containing            (guint element);
    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                  (const TpIntset *set);
    TpIntset *          tp_intset_from_array                (const GArray *array);
    gboolean            tp_intset_is_empty                  (const TpIntset *set);
    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);
                        TpIntsetFastIter;
    void                tp_intset_fast_iter_init            (TpIntsetFastIter *iter,
                                                             const TpIntset *set);
    gboolean            tp_intset_fast_iter_next            (TpIntsetFastIter *iter,
                                                             guint *output);
    #define             TP_INTSET_ITER_INIT                 (set)
                        TpIntsetIter;
    #define             tp_intset_iter_init                 (iter,
                                                             set)
    gboolean            tp_intset_iter_next                 (TpIntsetIter *iter);
    #define             tp_intset_iter_reset                (iter)

## Description

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

## Details

### TpIntset

    typedef struct _TpIntset TpIntset;

Opaque type representing a set of unsigned integers.

Before 0.11.16, this type was called TpIntSet, which is now a backwards compatibility typedef.

### TP_TYPE_INTSET

    #define TP_TYPE_INTSET (tp_intset_get_type ())

The boxed type of a TpIntset.

Since 0.11.3

### 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 a new integer set.

`size` : | ignored (it was previously 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.

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

### tp_intset_new_containing ()

    TpIntset *          tp_intset_new_containing            (guint element);

Allocate a new integer set containing the given integer.

`element` : | integer to add to a new set
Returns : | a new integer set containing `element`, to be destroyed with `tp_intset_destroy()` `since` 0.7.26

### 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`, in order.

`set` : | set
`func` : | `TpIntFunc` to use to iterate the set. [scope call]
`userdata` : | user data to pass to each call of `func`

### tp_intset_to_array ()

    GArray *            tp_intset_to_array                  (const TpIntset *set);

`set` : | set to convert
Returns : | a GArray of guint (which must be freed by the caller) containing the same integers as `set`. [element-type uint][transfer full uint]

### tp_intset_from_array ()

    TpIntset *          tp_intset_from_array                (const GArray *array);

`array` : | An array of guint. [element-type uint]
Returns : | A set containing the same integers as `array`.

### tp_intset_is_empty ()

    gboolean            tp_intset_is_empty                  (const TpIntset *set);

Return the same thing as `(tp_intset_size (set) == 0)`, but calculated more efficiently.

`set` : | a set of integers
Returns : | `TRUE` if `set` is empty

Since 0.11.6

### 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

### TpIntsetFastIter

    typedef struct {
    } TpIntsetFastIter;

An opaque structure representing iteration in undefined order over a set of integers. Must be initialized with `tp_intset_fast_iter_init()`.

Before 0.11.16, this type was called TpIntSetFastIter, which is now a backwards compatibility typedef.

Usage is similar to GHashTableIter:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    TpIntsetFastIter iter;
    guint element;

    tp_intset_fast_iter_init (&iter, intset);

    while (tp_intset_fast_iter_next (&iter, &element))
    {
      printf ("%u is in the intset\n", element);
    }

Since 0.11.6

### tp_intset_fast_iter_init ()

    void                tp_intset_fast_iter_init            (TpIntsetFastIter *iter,
                                                             const TpIntset *set);

Initialize `iter` to iterate over `set` in arbitrary order. `iter` will become invalid if `set` is modified.

`iter` : | an iterator
`set` : | a set

Since 0.11.6

### tp_intset_fast_iter_next ()

    gboolean            tp_intset_fast_iter_next            (TpIntsetFastIter *iter,
                                                             guint *output);

Advances `iter` and retrieves the integer it now points to. Iteration is not necessarily in numerical order.

`iter` : | an iterator
`output` : | a location to store a new integer, in arbitrary order
Returns : | `FALSE` if the end of the set has been reached

Since 0.11.6

### 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:

    1
    2
    3
    4
    5
    6
    void
    do_something (const TpIntset *intset)
    {
      TpIntsetIter iter = TP_INTSET_ITER_INIT (intset);
      /* ... do something with iter ... */
    }

Since 0.11.6, consider using TpIntsetFastIter if iteration in numerical order is not required.

`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()`.

Since 0.11.6, consider using TpIntsetFastIter if iteration in numerical order is not required.

Before 0.11.16, this type was called TpIntSetIter, which is now a backwards compatibility typedef.

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_init()

    #define tp_intset_iter_init(iter, set) tp_intset_iter_init_inline (iter, set)

Reset the iterator `iter` to the beginning and make it iterate over `set`.

`iter` : | An integer set iterator to be initialized.
`set` : | An integer set to be used by that iterator

### 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:

    1
    2
    3
    4
    5
    TpIntsetIter iter = TP_INTSET_INIT (intset);
    while (tp_intset_iter_next (&iter))
    {
      printf ("%u is in the intset\n", iter.element);
    }

Since 0.11.6, consider using TpIntsetFastIter if iteration in numerical order is not required.

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

### tp_intset_iter_reset()

    #define tp_intset_iter_reset(iter) tp_intset_iter_reset_inline (iter)

Reset the iterator `iter` to the beginning. It must already be associated with a set.

`iter` : | An integer set iterator to be reset.

## See Also

TpHandleSet