hb-set: HarfBuzz Manual

## hb-set hb-set — Objects representing a set of integers |

## Functions

hb_set_t * | hb_set_create ()
hb_bool_t | hb_set_allocation_successful ()
hb_set_t * | hb_set_copy ()
hb_set_t * | hb_set_get_empty ()
hb_set_t * | hb_set_reference ()
void | hb_set_destroy ()
hb_bool_t | hb_set_set_user_data ()
void * | hb_set_get_user_data ()
void | hb_set_clear ()
void | hb_set_set ()
hb_bool_t | hb_set_has ()
void | hb_set_add ()
void | hb_set_add_range ()
void | hb_set_add_sorted_array ()
void | hb_set_del ()
void | hb_set_del_range ()
hb_codepoint_t | hb_set_get_max ()
hb_codepoint_t | hb_set_get_min ()
unsigned int | hb_set_get_population ()
hb_bool_t | hb_set_is_empty ()
unsigned int | hb_set_hash ()
void | hb_set_subtract ()
void | hb_set_intersect ()
void | hb_set_union ()
void | hb_set_symmetric_difference ()
void | hb_set_invert ()
hb_bool_t | hb_set_is_inverted ()
hb_bool_t | hb_set_is_equal ()
hb_bool_t | hb_set_intersects ()
hb_bool_t | hb_set_is_subset ()
hb_bool_t | hb_set_next ()
hb_bool_t | hb_set_next_range ()
unsigned int | hb_set_next_many ()
hb_bool_t | hb_set_previous ()
hb_bool_t | hb_set_previous_range ()

## Types and Values

#define | HB_SET_VALUE_INVALID
typedef | hb_set_t

## Includes

    #include <hb.h>

## Description

Set objects represent a mathematical set of integer values. They are used in non-shaping APIs to query certain sets of characters or glyphs, or other integer values.

## Functions

### hb_set_create ()

    hb_set_t *
    hb_set_create (void);

Creates a new, initially empty set.

#### Returns

The new hb_set_t.

[transfer full]

Since: 0.9.2

### hb_set_allocation_successful ()

    hb_bool_t
    hb_set_allocation_successful (const hb_set_t *set);

Tests whether memory allocation for a set was successful.

#### Parameters

set | A set |

#### Returns

`true` if allocation succeeded, `false` otherwise

Since: 0.9.2

### hb_set_copy ()

    hb_set_t *
    hb_set_copy (const hb_set_t *set);

Allocate a copy of `set` .

#### Parameters

set | A set |

#### Returns

Newly-allocated set.

[transfer full]

Since: 2.8.2

### hb_set_get_empty ()

    hb_set_t *
    hb_set_get_empty (void);

Fetches the singleton empty hb_set_t.

#### Returns

The empty hb_set_t.

[transfer full]

Since: 0.9.2

### hb_set_reference ()

    hb_set_t *
    hb_set_reference (hb_set_t *set);

Increases the reference count on a set.

[skip]

#### Parameters

set | A set |

#### Returns

The set.

[transfer full]

Since: 0.9.2

### hb_set_destroy ()

    void
    hb_set_destroy (hb_set_t *set);

Decreases the reference count on a set. When the reference count reaches zero, the set is destroyed, freeing all memory.

[skip]

#### Parameters

set | A set |

Since: 0.9.2

### hb_set_set_user_data ()

    hb_bool_t
    hb_set_set_user_data (hb_set_t *set,
                          hb_user_data_key_t *key,
                          void *data,
                          hb_destroy_func_t destroy,
                          hb_bool_t replace);

Attaches a user-data key/data pair to the specified set.

[skip]

#### Parameters

set | A set |
key | The user-data key to set |
data | A pointer to the user data to set |
destroy | A callback to call when `data` is not needed anymore. | [nullable]
replace | Whether to replace an existing data with the same key |

#### Returns

`true` if success, `false` otherwise

Since: 0.9.2

### hb_set_get_user_data ()

    void *
    hb_set_get_user_data (const hb_set_t *set,
                          hb_user_data_key_t *key);

Fetches the user data associated with the specified key, attached to the specified set.

[skip]

#### Parameters

set | A set |
key | The user-data key to query |

#### Returns

A pointer to the user data.

[transfer none]

Since: 0.9.2

### hb_set_clear ()

    void
    hb_set_clear (hb_set_t *set);

Clears out the contents of a set.

#### Parameters

set | A set |

Since: 0.9.2

### hb_set_set ()

    void
    hb_set_set (hb_set_t *set,
                const hb_set_t *other);

Makes the contents of `set` equal to the contents of `other` .

#### Parameters

set | A set |
other | Another set |

Since: 0.9.2

### hb_set_has ()

    hb_bool_t
    hb_set_has (const hb_set_t *set,
                hb_codepoint_t codepoint);

Tests whether `codepoint` belongs to `set` .

#### Parameters

set | A set |
codepoint | The element to query |

#### Returns

`true` if `codepoint` is in `set` , `false` otherwise

Since: 0.9.2

### hb_set_add ()

    void
    hb_set_add (hb_set_t *set,
                hb_codepoint_t codepoint);

Adds `codepoint` to `set` .

#### Parameters

set | A set |
codepoint | The element to add to `set` |

Since: 0.9.2

### hb_set_add_range ()

    void
    hb_set_add_range (hb_set_t *set,
                      hb_codepoint_t first,
                      hb_codepoint_t last);

Adds all of the elements from `first` to `last` (inclusive) to `set` .

#### Parameters

set | A set |
first | The first element to add to `set` |
last | The final element to add to `set` |

Since: 0.9.7

### hb_set_add_sorted_array ()

    void
    hb_set_add_sorted_array (hb_set_t *set,
                             const hb_codepoint_t *sorted_codepoints,
                             unsigned int num_codepoints);

Adds `num_codepoints` codepoints to a set at once. The codepoints array must be in increasing order, with size at least `num_codepoints` .

#### Parameters

set | A set |
sorted_codepoints | Array of codepoints to add. | [array length=num_codepoints]
num_codepoints | Length of `sorted_codepoints` |

Since: 4.1.0

### hb_set_del ()

    void
    hb_set_del (hb_set_t *set,
                hb_codepoint_t codepoint);

Removes `codepoint` from `set` .

#### Parameters

set | A set |
codepoint | Removes `codepoint` from `set` |

Since: 0.9.2

### hb_set_del_range ()

    void
    hb_set_del_range (hb_set_t *set,
                      hb_codepoint_t first,
                      hb_codepoint_t last);

Removes all of the elements from `first` to `last` (inclusive) from `set` .

If `last` is HB_SET_VALUE_INVALID, then all values greater than or equal to `first` are removed.

#### Parameters

set | A set |
first | The first element to remove from `set` |
last | The final element to remove from `set` |

Since: 0.9.7

### hb_set_get_max ()

    hb_codepoint_t
    hb_set_get_max (const hb_set_t *set);

Finds the largest element in the set.

#### Parameters

set | A set |

#### Returns

maximum of `set` , or HB_SET_VALUE_INVALID if `set` is empty.

Since: 0.9.7

### hb_set_get_min ()

    hb_codepoint_t
    hb_set_get_min (const hb_set_t *set);

Finds the smallest element in the set.

#### Parameters

set | A set |

#### Returns

minimum of `set` , or HB_SET_VALUE_INVALID if `set` is empty.

Since: 0.9.7

### hb_set_get_population ()

    unsigned int
    hb_set_get_population (const hb_set_t *set);

Returns the number of elements in the set.

#### Parameters

set | A set |

#### Returns

The population of `set`

Since: 0.9.7

### hb_set_is_empty ()

    hb_bool_t
    hb_set_is_empty (const hb_set_t *set);

Tests whether a set is empty (contains no elements).

#### Parameters

set | a set. |

#### Returns

`true` if `set` is empty

Since: 0.9.7

### hb_set_hash ()

    unsigned int
    hb_set_hash (const hb_set_t *set);

Creates a hash representing `set` .

#### Parameters

set | A set |

#### Returns

A hash of `set` .

Since: 4.4.0

### hb_set_subtract ()

    void
    hb_set_subtract (hb_set_t *set,
                     const hb_set_t *other);

Subtracts the contents of `other` from `set` .

#### Parameters

set | A set |
other | Another set |

Since: 0.9.2

### hb_set_intersect ()

    void
    hb_set_intersect (hb_set_t *set,
                      const hb_set_t *other);

Makes `set` the intersection of `set` and `other` .

#### Parameters

set | A set |
other | Another set |

Since: 0.9.2

### hb_set_union ()

    void
    hb_set_union (hb_set_t *set,
                  const hb_set_t *other);

Makes `set` the union of `set` and `other` .

#### Parameters

set | A set |
other | Another set |

Since: 0.9.2

### hb_set_symmetric_difference ()

    void
    hb_set_symmetric_difference (hb_set_t *set,
                                 const hb_set_t *other);

Makes `set` the symmetric difference of `set` and `other` .

#### Parameters

set | A set |
other | Another set |

Since: 0.9.2

### hb_set_invert ()

    void
    hb_set_invert (hb_set_t *set);

Inverts the contents of `set` .

#### Parameters

set | A set |

Since: 3.0.0

### hb_set_is_inverted ()

    hb_bool_t
    hb_set_is_inverted (const hb_set_t *set);

Returns whether the set is inverted.

#### Parameters

set | A set |

#### Returns

`true` if the set is inverted, `false` otherwise

Since: 7.0.0

### hb_set_is_equal ()

    hb_bool_t
    hb_set_is_equal (const hb_set_t *set,
                     const hb_set_t *other);

Tests whether `set` and `other` are equal (contain the same elements).

#### Parameters

set | A set |
other | Another set |

#### Returns

`true` if the two sets are equal, `false` otherwise.

Since: 0.9.7

### hb_set_intersects ()

    hb_bool_t
    hb_set_intersects (const hb_set_t *set,
                       const hb_set_t *other);

Tests whether `set` and `other` have any elements in common.

#### Parameters

set | A set |
other | Another set |

#### Returns

`true` if the two sets intersect, `false` otherwise.

Since: 14.4.0

### hb_set_is_subset ()

    hb_bool_t
    hb_set_is_subset (const hb_set_t *set,
                      const hb_set_t *larger_set);

Tests whether `set` is a subset of `larger_set` .

#### Parameters

set | A set |
larger_set | Another set |

#### Returns

`true` if the `set` is a subset of (or equal to) `larger_set` , `false` otherwise.

Since: 1.8.1

### hb_set_next ()

    hb_bool_t
    hb_set_next (const hb_set_t *set,
                 hb_codepoint_t *codepoint);

Fetches the next element in `set` that is greater than current value of `codepoint` .

Set `codepoint` to HB_SET_VALUE_INVALID to get started.

#### Parameters

set | A set |
codepoint | Input = Code point to query Output = Code point retrieved. | [inout]

#### Returns

`true` if there was a next value, `false` otherwise

Since: 0.9.2

### hb_set_next_range ()

    hb_bool_t
    hb_set_next_range (const hb_set_t *set,
                       hb_codepoint_t *first,
                       hb_codepoint_t *last);

Fetches the next consecutive range of elements in `set` that are greater than current value of `last` .

Set `last` to HB_SET_VALUE_INVALID to get started.

#### Parameters

set | A set |
first | The first code point in the range. | [out]
last | Input = The current last code point in the range Output = The last code point in the range. | [inout]

#### Returns

`true` if there was a next range, `false` otherwise

Since: 0.9.7

### hb_set_next_many ()

    unsigned int
    hb_set_next_many (const hb_set_t *set,
                      hb_codepoint_t codepoint,
                      hb_codepoint_t *out,
                      unsigned int size);

Finds the next element in `set` that is greater than `codepoint` . Writes out codepoints to `out` , until either the set runs out of elements, or `size` codepoints are written, whichever comes first.

#### Parameters

set | A set |
codepoint | Outputting codepoints starting after this one. Use HB_SET_VALUE_INVALID to get started. |
out | An array of codepoints to write to. | [array length=size]
size | The maximum number of codepoints to write out. |

#### Returns

the number of values written.

Since: 4.2.0

### hb_set_previous ()

    hb_bool_t
    hb_set_previous (const hb_set_t *set,
                     hb_codepoint_t *codepoint);

Fetches the previous element in `set` that is lower than current value of `codepoint` .

Set `codepoint` to HB_SET_VALUE_INVALID to get started.

#### Parameters

set | A set |
codepoint | Input = Code point to query Output = Code point retrieved. | [inout]

#### Returns

`true` if there was a previous value, `false` otherwise

Since: 1.8.0

### hb_set_previous_range ()

    hb_bool_t
    hb_set_previous_range (const hb_set_t *set,
                           hb_codepoint_t *first,
                           hb_codepoint_t *last);

Fetches the previous consecutive range of elements in `set` that are greater than current value of `last` .

Set `first` to HB_SET_VALUE_INVALID to get started.

#### Parameters

set | A set |
first | Input = The current first code point in the range Output = The first code point in the range. | [inout]
last | The last code point in the range. | [out]

#### Returns

`true` if there was a previous range, `false` otherwise

Since: 1.8.0

## Types and Values

### HB_SET_VALUE_INVALID

    #define HB_SET_VALUE_INVALID HB_CODEPOINT_INVALID

Unset hb_set_t value.

Since: 0.9.21

### hb_set_t

    typedef struct hb_set_t hb_set_t;

Data type for holding a set of integers. hb_set_t's are used to gather and contain glyph IDs, Unicode code points, and various other collections of discrete values.