TpIntset: telepathy-glib API Reference Manual

## TpIntset TpIntset — a set of unsigned integers |

## Functions

void | (*TpIntFunc) ()
TpIntset * | tp_intset_sized_new ()
TpIntset * | tp_intset_new ()
TpIntset * | tp_intset_new_containing ()
void | tp_intset_destroy ()
void | tp_intset_clear ()
void | tp_intset_add ()
gboolean | tp_intset_remove ()
gboolean | tp_intset_is_member ()
void | tp_intset_foreach ()
GArray * | tp_intset_to_array ()
TpIntset * | tp_intset_from_array ()
gboolean | tp_intset_is_empty ()
guint | tp_intset_size ()
gboolean | tp_intset_is_equal ()
TpIntset * | tp_intset_copy ()
TpIntset * | tp_intset_intersection ()
TpIntset * | tp_intset_union ()
void | tp_intset_union_update ()
TpIntset * | tp_intset_difference ()
void | tp_intset_difference_update ()
TpIntset * | tp_intset_symmetric_difference ()
gchar * | tp_intset_dump ()
void | tp_intset_fast_iter_init ()
gboolean | tp_intset_fast_iter_next ()
#define | TP_INTSET_ITER_INIT()
void | tp_intset_iter_init ()
gboolean | tp_intset_iter_next ()
void | tp_intset_iter_reset ()

## Types and Values

| TpIntset
#define | TP_TYPE_INTSET
| TpIntsetFastIter
| TpIntsetIter

## Object Hierarchy

        GBoxed
        ├── TpIntSet
        ╰── TpIntset

## Includes

    #include <telepathy-glib/telepathy-glib.h>

## Description

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

## Functions

### TpIntFunc ()

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

A callback function acting on unsigned integers.

#### Parameters

i | The relevant integer |
userdata | Opaque user data |

### tp_intset_sized_new ()

    TpIntset *
    tp_intset_sized_new (guint size);

Allocate a new integer set.

#### Parameters

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.

#### Parameters

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.

#### Parameters

set | set |

### tp_intset_clear ()

    void
    tp_intset_clear (TpIntset *set);

Unset every integer in the set.

#### Parameters

set | set |

### tp_intset_add ()

    void
    tp_intset_add (TpIntset *set,
                   guint element);

Add an integer into a TpIntset.

#### Parameters

set | set |
element | integer to add |

### tp_intset_remove ()

    gboolean
    tp_intset_remove (TpIntset *set,
                      guint element);

Remove an integer from a TpIntset

#### Parameters

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`

#### Parameters

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.

#### Parameters

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);

#### Parameters

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]

### tp_intset_from_array ()

    TpIntset *
    tp_intset_from_array (const GArray *array);

#### Parameters

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.

#### Parameters

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);

#### Parameters

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);

#### Parameters

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);

#### Parameters

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);

#### Parameters

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);

#### Parameters

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

    void
    tp_intset_union_update (TpIntset *self,
                            const TpIntset *other);

Add each integer in `other` to `self` , analogous to the bitwise operation self |= other.

#### Parameters

self | the set to change |
other | members to add |

Since: 0.13.10

### tp_intset_difference ()

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

#### Parameters

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

    void
    tp_intset_difference_update (TpIntset *self,
                                 const TpIntset *other);

Remove each integer in `other` from `self` , analogous to the bitwise operation self &= (~other).

#### Parameters

self | the set to change |
other | members to remove |

Since: 0.13.10

### tp_intset_symmetric_difference ()

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

#### Parameters

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);

#### Parameters

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_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.

#### Parameters

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.

#### Parameters

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) }

`TP_INTSET_ITER_INIT` is deprecated and should not be used in newly-written code.

since 0.19.0. Use TpIntsetFastIter instead

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 ... */
    }

#### Parameters

set | A set of integers |

### tp_intset_iter_init ()

    void
    tp_intset_iter_init (TpIntsetIter *iter,
                         const TpIntset *set);

`tp_intset_iter_init` is deprecated and should not be used in newly-written code.

since 0.19.0. Use TpIntsetFastIter instead

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

#### Parameters

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);

`tp_intset_iter_next` is deprecated and should not be used in newly-written code.

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.

#### Parameters

iter | An iterator originally initialized with TP_INTSET_INIT(set) |

#### Returns

`TRUE` if (`iter->element` ) has been advanced

### tp_intset_iter_reset ()

    void
    tp_intset_iter_reset (TpIntsetIter *iter);

`tp_intset_iter_reset` is deprecated and should not be used in newly-written code.

since 0.19.0. Use TpIntsetFastIter instead

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

#### Parameters

iter | An integer set iterator to be reset. |

## Types and Values

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

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

### TpIntsetIter

    typedef struct {
        const TpIntset *set;
        guint element;
    } TpIntsetIter;

`TpIntsetIter` is deprecated and should not be used in newly-written code.

since 0.19.0. Use TpIntsetFastIter instead

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.

#### Members

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

## See Also

TpHandleSet