## rb-history

rb-history — sequence data structure useful for implementing play orders

## Synopsis

                        RBHistory;
                        RBHistoryClass;
    RBHistory*          rb_history_new                      (gboolean truncate_on_play,
                                                             GFunc destroyer,
                                                             gpointer destroy_userdata);
    void                rb_history_set_destroy_notify       (RBHistory *hist,
                                                             GFunc destroyer,
                                                             gpointer destroy_userdata);
    void                rb_history_set_truncate_on_play     (RBHistory *hist,
                                                             gboolean truncate_on_play);
    void                rb_history_set_maximum_size         (RBHistory *hist,
                                                             guint maximum_size);
    guint               rb_history_length                   (RBHistory *hist);
    RhythmDBEntry*      rb_history_first                    (RBHistory *hist);
    RhythmDBEntry*      rb_history_previous                 (RBHistory *hist);
    RhythmDBEntry*      rb_history_current                  (RBHistory *hist);
    RhythmDBEntry*      rb_history_next                     (RBHistory *hist);
    RhythmDBEntry*      rb_history_last                     (RBHistory *hist);
    void                rb_history_go_first                 (RBHistory *hist);
    void                rb_history_go_previous              (RBHistory *hist);
    void                rb_history_go_next                  (RBHistory *hist);
    void                rb_history_go_last                  (RBHistory *hist);
    void                rb_history_set_playing              (RBHistory *hist,
                                                             RhythmDBEntry *entry);
    void                rb_history_append                   (RBHistory *hist,
                                                             RhythmDBEntry *entry);
    gint                rb_history_get_current_index        (RBHistory *hist);
    void                rb_history_insert_at_index          (RBHistory *hist,
                                                             RhythmDBEntry *entry,
                                                             guint index);
    void                rb_history_remove_entry             (RBHistory *hist,
                                                             RhythmDBEntry *entry);
    void                rb_history_clear                    (RBHistory *hist);
    GPtrArray*          rb_history_dump                     (RBHistory *hist);
    gboolean            rb_history_contains_entry           (RBHistory *hist,
                                                             RhythmDBEntry *entry);

## Object Hierarchy

      GObject
       +----RBHistory

## Properties

      "maximum-size"             guint                 : Read / Write
      "truncate-on-play"         gboolean              : Read / Write / Construct

## Description

RBHistory is a GSequence that maintains a "current" pointer and can delete an arbitrary element in amortized O(log(N)) time. It can call a deletion callback when it removes one of its entries.

All operations take amortized O(log(N)) (worst-case O(N)) time unless noted otherwise.

## Details

### RBHistory

    typedef struct _RBHistory RBHistory;

### RBHistoryClass

    typedef struct {
    	GObjectClass parent_class;
    } RBHistoryClass;

### rb_history_new ()

    RBHistory*          rb_history_new                      (gboolean truncate_on_play,
                                                             GFunc destroyer,
                                                             gpointer destroy_userdata);

`truncate_on_play` : | Whether `rb_history_set_playing()` should truncate the history
`destroyer` : | function to call when removing an entry from the history
`destroy_userdata` : | data to pass to `destroyer`
Returns : | a new RBHistory

### rb_history_set_destroy_notify ()

    void                rb_history_set_destroy_notify       (RBHistory *hist,
                                                             GFunc destroyer,
                                                             gpointer destroy_userdata);

Sets a new function to call when removing entries from the history.

`hist` : | a RBHistory
`destroyer` : | function to call when removing an entry from the history
`destroy_userdata` : | data to pass to `destroyer`

### rb_history_set_truncate_on_play ()

    void                rb_history_set_truncate_on_play     (RBHistory *hist,
                                                             gboolean truncate_on_play);

Sets the 'truncate-on-play' property.

`hist` : | a RBHistory
`truncate_on_play` : | Whether `rb_history_set_playing()` should truncate the history

### rb_history_set_maximum_size ()

    void                rb_history_set_maximum_size         (RBHistory *hist,
                                                             guint maximum_size);

Sets the maximum-size property

`hist` : | a RBHistory
`maximum_size` : | new maximum size of the history (or 0 for no limit)

### rb_history_length ()

    guint               rb_history_length                   (RBHistory *hist);

`hist` : | a RBHistory
Returns : | the number of entries in the history

### rb_history_first ()

    RhythmDBEntry*      rb_history_first                    (RBHistory *hist);

`hist` : | a RBHistory
Returns : | the first entry in the history

### rb_history_previous ()

    RhythmDBEntry*      rb_history_previous                 (RBHistory *hist);

`hist` : | a RBHistory
Returns : | the RhythmDBEntry before the current position

### rb_history_current ()

    RhythmDBEntry*      rb_history_current                  (RBHistory *hist);

`hist` : | a RBHistory
Returns : | the current RhythmDBEntry, or NULL if there is no current position

### rb_history_next ()

    RhythmDBEntry*      rb_history_next                     (RBHistory *hist);

`hist` : | a RBHistory
Returns : | the RhythmDBEntry after the current position

### rb_history_last ()

    RhythmDBEntry*      rb_history_last                     (RBHistory *hist);

`hist` : | a RBHistory
Returns : | the last RhythmDBEntry in the history

### rb_history_go_first ()

    void                rb_history_go_first                 (RBHistory *hist);

Moves the current position to the first entry in the history

`hist` : | a RBHistory

### rb_history_go_previous ()

    void                rb_history_go_previous              (RBHistory *hist);

Moves the current position to the previous entry. If the current position is already at the start of the history, nothing happens.

`hist` : | a RBHistory

### rb_history_go_next ()

    void                rb_history_go_next                  (RBHistory *hist);

Moves the current position to the next entry. If the current position is already at the end of the history, nothing happens.

`hist` : | a RBHistory

### rb_history_go_last ()

    void                rb_history_go_last                  (RBHistory *hist);

Moves the current position to the last entry in the history

`hist` : | a RBHistory

### rb_history_set_playing ()

    void                rb_history_set_playing              (RBHistory *hist,
                                                             RhythmDBEntry *entry);

Updates the current position to point to the specified entry. If the truncate-on-play property is set, this will remove all entries after that.

`hist` : | a RBHistory
`entry` : | the new playing RhythmDBEntry

### rb_history_append ()

    void                rb_history_append                   (RBHistory *hist,
                                                             RhythmDBEntry *entry);

Adds a new entry to the end of the history list. If a size limit is set, an entry may be removed from the start to keep the history list within the limit.

`hist` : | a RBHistory
`entry` : | a RhythmDBEntry to append

### rb_history_get_current_index ()

    gint                rb_history_get_current_index        (RBHistory *hist);

Gets the index of the current entry. This is guaranteed to be < the history's size, so if the history is empty, it returns -1.

`hist` : | a RBHistory
Returns : | index of the current entry

### rb_history_insert_at_index ()

    void                rb_history_insert_at_index          (RBHistory *hist,
                                                             RhythmDBEntry *entry,
                                                             guint index);

Inserts `entry` at `index` within the history list. 0<=`index`<=size

`hist` : | a RBHistory
`entry` : | a RhythmDBEntry to insert
`index` : | position at which to insert `entry`

### rb_history_remove_entry ()

    void                rb_history_remove_entry             (RBHistory *hist,
                                                             RhythmDBEntry *entry);

Removes the specified entry from the history list.

`hist` : | a RBHistory
`entry` : | the RhythmDBEntry to remove

### rb_history_clear ()

    void                rb_history_clear                    (RBHistory *hist);

Empties the history list.

`hist` : | a RBHistory

### rb_history_dump ()

    GPtrArray*          rb_history_dump                     (RBHistory *hist);

Constructs a copy of the whole history in order. Caller must free the result. The caller does not own any references on the entries in the returned array. Takes O(Nlog(N)) time.

`hist` : | a RBHistory
Returns : | a copy of the history list

### rb_history_contains_entry ()

    gboolean            rb_history_contains_entry           (RBHistory *hist,
                                                             RhythmDBEntry *entry);

`hist` : | a RBHistory
`entry` : | a RhythmDBEntry to check for
Returns : | TRUE if the entry is present in the history list.

## Property Details

### The `"maximum-size"` property

      "maximum-size"             guint                 : Read / Write

Maximum number of entries to store in the history. If 0, no limit is applied.

Default value: 0

### The `"truncate-on-play"` property

      "truncate-on-play"         gboolean              : Read / Write / Construct

If set, `rb_history_set_playing()` truncates the rest of the history

Default value: FALSE