GcalRangeTree: GNOME Calendar Reference Manual

## GcalRangeTree GcalRangeTree — Augmented AVL tree to handle ranges |

## Stability Level

Stable, unless otherwise indicated

## Functions

gboolean | (*GcalRangeTraverseFunc) ()
GcalRangeTree * | gcal_range_tree_new ()
GcalRangeTree * | gcal_range_tree_copy ()
GcalRangeTree * | gcal_range_tree_ref ()
void | gcal_range_tree_unref ()
void | gcal_range_tree_add_range ()
void | gcal_range_tree_remove_range ()
void | gcal_range_tree_traverse ()
GPtrArray * | gcal_range_tree_get_data_at_range ()
guint64 | gcal_range_tree_count_entries_at_range ()

## Object Hierarchy

        GBoxed
        ╰── GcalRangeTree

## Description

GcalRangeTree is an augmented AVL tree implemented to be able to handle ranges rather than point values. This tree is used by `GcalWeekGrid` to store events according to their start and end minutes, and thus all the data structure was optimized to handle a limited subset of values.

In the future, we may need to extend support for broader range values, and move away from guint16 in function params.

### Ranges

Conforming to the overall standard of iCal and Calendar, the start of a range is inclusive but the end of the range is always exclusive.

## Functions

### GcalRangeTraverseFunc ()

    gboolean
    (*GcalRangeTraverseFunc) (guint16 start,
                              guint16 end,
                              gpointer data,
                              gpointer user_data);

Function type to be called when traversing a GcalRangeTree.

#### Parameters

start | start of range of the entry |
end | end of range of the entry |
data | the data of the entry. | [nullable]
user_data | user data passed to the function. | [closure]

#### Returns

`TRUE` to stop traversing, `FALSE` to continue traversing

### gcal_range_tree_new ()

    GcalRangeTree *
    gcal_range_tree_new (void);

Creates a new range tree

#### Returns

a newly created GcalRangeTree. Free with `gcal_range_tree_unref()` when done.

[transfer full]

### gcal_range_tree_copy ()

    GcalRangeTree *
    gcal_range_tree_copy (GcalRangeTree *self);

Copies `self` into a new range tree.

#### Parameters

self | a GcalRangeTree |

#### Returns

a newly created GcalRangeTree. Free with `gcal_range_tree_unref()` when done.

[transfer full]

### gcal_range_tree_ref ()

    GcalRangeTree *
    gcal_range_tree_ref (GcalRangeTree *self);

Increases the reference count of `self` .

#### Parameters

self | a GcalRangeTree |

#### Returns

pointer to the just-referenced tree.

[transfer full]

### gcal_range_tree_unref ()

    void
    gcal_range_tree_unref (GcalRangeTree *self);

Decreases the reference count of `self` , and frees it when if the reference count reaches zero.

#### Parameters

self | a GcalRangeTree |

### gcal_range_tree_add_range ()

    void
    gcal_range_tree_add_range (GcalRangeTree *self,
                               guint16 start,
                               guint16 end,
                               gpointer data);

Adds the range into `self` , and attach `data` do it. It is possible to have multiple entries in the same interval, in which case the interval will have a reference counting like behavior.

#### Parameters

self | a GcalRangeTree |
start | start of the interval |
end | end of the interval |
data | user data |

### gcal_range_tree_remove_range ()

    void
    gcal_range_tree_remove_range (GcalRangeTree *self,
                                  guint16 start,
                                  guint16 end,
                                  gpointer data);

Removes (or decreases the reference count) of the given interval.

#### Parameters

self | a GcalRangeTree |
start | the start of the range |
end | the end of the range |
data | user data |

### gcal_range_tree_traverse ()

    void
    gcal_range_tree_traverse (GcalRangeTree *self,
                              GTraverseType type,
                              GcalRangeTraverseFunc func,
                              gpointer user_data);

Traverse `self` calling `func` according to the `type` specified.

#### Parameters

self | a GcalRangeTree |
type | the type of traverse to perform |
func | the function to call on each traverse iteration |
user_data | user data for `func` |

### gcal_range_tree_get_data_at_range ()

    GPtrArray *
    gcal_range_tree_get_data_at_range (GcalRangeTree *self,
                                       guint16 start,
                                       guint16 end);

Retrieves the data of every node between `start` and `end` .

#### Parameters

self | a GcalRangeTree |
start | inclusive start of the range |
end | exclusive end of the range |

#### Returns

a GPtrArray. Unref with `g_ptr_array_unref()` when finished.

[transfer full]

### gcal_range_tree_count_entries_at_range ()

    guint64
    gcal_range_tree_count_entries_at_range
                                   (GcalRangeTree *self,
                                    guint16 start,
                                    guint16 end);

Counts the number of entries available in the given range.

#### Parameters

self | a GcalRangeTree |
start | start of the range |
end | end of the range |

#### Returns

the number of entries in the given range

## Types and Values