## RBHistory

RBHistory — sequence data structure useful for implementing play orders

## Functions

RBHistory * | rb_history_new ()
void | rb_history_set_destroy_notify ()
void | rb_history_set_truncate_on_play ()
void | rb_history_set_maximum_size ()
guint | rb_history_length ()
RhythmDBEntry * | rb_history_first ()
RhythmDBEntry * | rb_history_previous ()
RhythmDBEntry * | rb_history_current ()
RhythmDBEntry * | rb_history_next ()
RhythmDBEntry * | rb_history_last ()
void | rb_history_go_first ()
void | rb_history_go_previous ()
void | rb_history_go_next ()
void | rb_history_go_last ()
void | rb_history_set_playing ()
void | rb_history_append ()
gint | rb_history_get_current_index ()
void | rb_history_insert_at_index ()
void | rb_history_remove_entry ()
void | rb_history_clear ()
GPtrArray * | rb_history_dump ()
gboolean | rb_history_contains_entry ()

## Properties

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

## Types and Values

struct | RBHistory
struct | RBHistoryClass

## Object Hierarchy

        GObject
        ╰── RBHistory

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

## Functions

### rb_history_new ()

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

Creates a new history instance.

#### Parameters

truncate_on_play | Whether `rb_history_set_playing()` should truncate the history |
destroyer | function to call when removing an entry from the history. | [scope async]
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.

#### Parameters

hist | a RBHistory |
destroyer | function to call when removing an entry from the history. | [scope async]
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.

#### Parameters

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

#### Parameters

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

Returns the number of entries in the history.

#### Parameters

hist | a RBHistory |

#### Returns

number of entries

### rb_history_first ()

    RhythmDBEntry *
    rb_history_first (RBHistory *hist);

Returns the first entry in the history.

#### Parameters

hist | a RBHistory |

#### Returns

first entry.

[transfer none]

### rb_history_previous ()

    RhythmDBEntry *
    rb_history_previous (RBHistory *hist);

Returns the RhythmDBEntry before the current position.

#### Parameters

hist | a RBHistory |

#### Returns

previous entry.

[transfer none]

### rb_history_current ()

    RhythmDBEntry *
    rb_history_current (RBHistory *hist);

Returns the current RhythmDBEntry, or NULL if there is no current position

#### Parameters

hist | a RBHistory |

#### Returns

current entry or NULL.

[transfer none]

### rb_history_next ()

    RhythmDBEntry *
    rb_history_next (RBHistory *hist);

Returns the RhythmDBEntry after the current position

#### Parameters

hist | a RBHistory |

#### Returns

next entry.

[transfer none]

### rb_history_last ()

    RhythmDBEntry *
    rb_history_last (RBHistory *hist);

Returns the last RhythmDBEntry in the history

#### Parameters

hist | a RBHistory |

#### Returns

last entry.

[transfer none]

### rb_history_go_first ()

    void
    rb_history_go_first (RBHistory *hist);

Moves the current position to the first entry in the history

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

### rb_history_clear ()

    void
    rb_history_clear (RBHistory *hist);

Empties the history list.

#### Parameters

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.

#### Parameters

hist | a RBHistory |

#### Returns

a copy of the history list.

[element-type RB.RhythmDBEntry][transfer container]

### rb_history_contains_entry ()

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

Returns `TRUE` if the entry is present in the history list.

#### Parameters

hist | a RBHistory |
entry | a RhythmDBEntry to check for |

#### Returns

`TRUE` if found

## Types and Values

### struct RBHistory

    struct RBHistory;

### struct RBHistoryClass

    struct RBHistoryClass {
    	GObjectClass parent_class;
    };

## Property Details

### The `“maximum-size”` property

      “maximum-size”             guint

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

Flags: Read / Write

Default value: 0

### The `“truncate-on-play”` property

      “truncate-on-play”         gboolean

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

Flags: Read / Write / Construct

Default value: FALSE