## ZeitgeistResultSet ZeitgeistResultSet — Cursor-like interface for results sets |

## Synopsis

    #include <zeitgeist.h>

    struct              ZeitgeistResultSetIface;
                        ZeitgeistResultSet;
    guint               zeitgeist_result_set_size           (ZeitgeistResultSet *self);
    guint               zeitgeist_result_set_estimated_matches
                                                            (ZeitgeistResultSet *self);
    ZeitgeistEvent *    zeitgeist_result_set_next           (ZeitgeistResultSet *self);
    gboolean            zeitgeist_result_set_has_next       (ZeitgeistResultSet *self);
    ZeitgeistEvent *    zeitgeist_result_set_peek           (ZeitgeistResultSet *self);
    void                zeitgeist_result_set_seek           (ZeitgeistResultSet *self,
                                                             guint pos);
    guint               zeitgeist_result_set_tell           (ZeitgeistResultSet *self);

## Object Hierarchy

      GInterface
       +----ZeitgeistResultSet

## Prerequisites

ZeitgeistResultSet requires GObject.

## Description

Interface for results returned by `zeitgeist_log_find_events()`, `zeitgeist_log_get_events()`, and `zeitgeist_index_search()`.

This interface utilizes a cursor-like metaphor. You advance the cursor by calling `zeitgeist_result_set_next()` or adjust it manually by calling `zeitgeist_result_set_seek()`.

Calling `zeitgeist_result_set_next()` will also return the event at the current cursor position. You may retrieve the current event without advancing the cursor by calling `zeitgeist_result_set_peek()`.

## Details

### struct ZeitgeistResultSetIface

    struct ZeitgeistResultSetIface {
      GTypeInterface g_iface;

      guint           (*size)              (ZeitgeistResultSet *self);

      guint           (*estimated_matches) (ZeitgeistResultSet *self);

      ZeitgeistEvent* (*next)              (ZeitgeistResultSet *self);

      gboolean        (*has_next)          (ZeitgeistResultSet *self);

      ZeitgeistEvent* (*peek)              (ZeitgeistResultSet *self);

      void            (*seek)              (ZeitgeistResultSet *self,
                                            guint               pos);

      guint           (*tell)              (ZeitgeistResultSet *self);
    };

### ZeitgeistResultSet

    typedef struct _ZeitgeistResultSet ZeitgeistResultSet;

### zeitgeist_result_set_size ()

    guint               zeitgeist_result_set_size           (ZeitgeistResultSet *self);

Get the number of ZeitgeistEvents held in a ZeitgeistResultSet. Unlike the number obtained from `zeitgeist_result_set_estimated_matches()` the size of the result set is always equal to the number of times you can call `zeitgeist_result_set_next()`.

`self` : | The ZeitgeistResultSet to get the size of
Returns : | The number of events held in the result set

### zeitgeist_result_set_estimated_matches ()

    guint               zeitgeist_result_set_estimated_matches
                                                            (ZeitgeistResultSet *self);

Get an estimated total number of matches that would have been for the query that generated the result set had it not been restricted in size.

For `zeitgeist_log_find_events()` and `zeitgeist_log_get_events()` this will always be the same as `zeitgeist_result_set_size()`. For cases like `zeitgeist_index_search()` where you specify a subset of the hits to retrieve the estimated match count will often be bigger than the result set size.

`self` : | The ZeitgeistResultSet to get the number of estimated matches on
Returns : | The number of events that matched the query

### zeitgeist_result_set_next ()

    ZeitgeistEvent *    zeitgeist_result_set_next           (ZeitgeistResultSet *self);

Get the current event from the result set and advance the cursor. To ensure that calls to this method will succeed you can call `zeitgeist_result_set_has_next()`.

To retrieve the current event without advancing the cursor call `zeitgeist_result_set_peek()` in stead of this method.

`self` : | The ZeitgeistResultSet to get an event from
Returns : | The ZeitgeistEvent at the current cursor position

### zeitgeist_result_set_has_next ()

    gboolean            zeitgeist_result_set_has_next       (ZeitgeistResultSet *self);

Check if a call to `zeitgeist_result_set_next()` will succeed.

`self` : | The ZeitgeistResultSet to check
Returns : | `TRUE` if and only if more events can be retrieved by calling `zeitgeist_result_set_next()`

### zeitgeist_result_set_peek ()

    ZeitgeistEvent *    zeitgeist_result_set_peek           (ZeitgeistResultSet *self);

Get the event at the current cursor position.

To retrieve the current event and advance the cursor position call `zeitgeist_result_set_next()` in stead of this method.

`self` : | The ZeitgeistResultSet to get an event from
Returns : | The ZeitgeistEvent at the current cursor position

### zeitgeist_result_set_seek ()

    void                zeitgeist_result_set_seek           (ZeitgeistResultSet *self,
                                                             guint pos);

Set the cursor position. Following calls to `zeitgeist_result_set_peek()` or `zeitgeist_result_set_next()` will read the event at position `pos`.

`self` : | The ZeitgeistResultSet to seek in
`pos` : | The position to seek to

### zeitgeist_result_set_tell ()

    guint               zeitgeist_result_set_tell           (ZeitgeistResultSet *self);

Get the current position of the cursor.

`self` : | The ZeitgeistResultSet to check the cursor position for
Returns : | The current position of the cursor