<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<refentry id="ZeitgeistResultSet">
<refmeta>
<refentrytitle role="top_of_page" id="ZeitgeistResultSet.top_of_page">ZeitgeistResultSet</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  ZEITGEIST-2.0 Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ZeitgeistResultSet</refname>
<refpurpose>Cursor-like interface for results sets</refpurpose>
</refnamediv>

<refsynopsisdiv id="ZeitgeistResultSet.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis><link linkend="guint"><returnvalue>guint</returnvalue></link>               <link linkend="zeitgeist-result-set-size">zeitgeist_result_set_size</link>           (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);
<link linkend="guint"><returnvalue>guint</returnvalue></link>               <link linkend="zeitgeist-result-set-estimated-matches">zeitgeist_result_set_estimated_matches</link>
                                                        (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);
<link linkend="ZeitgeistEvent"><returnvalue>ZeitgeistEvent</returnvalue></link> *    <link linkend="zeitgeist-result-set-next-value">zeitgeist_result_set_next_value</link>     (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);
<link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            <link linkend="zeitgeist-result-set-has-next">zeitgeist_result_set_has_next</link>       (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);
<link linkend="guint"><returnvalue>guint</returnvalue></link>               <link linkend="zeitgeist-result-set-tell">zeitgeist_result_set_tell</link>           (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="zeitgeist-result-set-reset">zeitgeist_result_set_reset</link>          (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);
<link linkend="ZeitgeistResultSet"><returnvalue>ZeitgeistResultSet</returnvalue></link> * <link linkend="zeitgeist-result-set-iterator">zeitgeist_result_set_iterator</link>      (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);
                    <link linkend="ZeitgeistResultSet-struct">ZeitgeistResultSet</link>;
struct              <link linkend="ZeitgeistResultSetIface">ZeitgeistResultSetIface</link>;
</synopsis>
</refsynopsisdiv>
<refsect1 id="ZeitgeistResultSet.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GInterface">GInterface</link>
   +----ZeitgeistResultSet
</synopsis>
</refsect1>
<refsect1 id="ZeitgeistResultSet.prerequisites" role="prerequisites">
<title role="prerequisites.title">Prerequisites</title>
<para>
ZeitgeistResultSet requires
 <link linkend="GObject">GObject</link>.</para>
</refsect1>
<refsect1 id="ZeitgeistResultSet.implementations" role="implementations">
<title role="implementations.title">Known Implementations</title>
<para>
ZeitgeistResultSet is implemented by
 <link linkend="ZeitgeistSimpleResultSet">ZeitgeistSimpleResultSet</link>.</para>
</refsect1>

<refsect1 id="ZeitgeistResultSet.description" role="desc">
<title role="desc.title">Description</title>
<para>
<para>include: zeitgeist.h</para><para>Interface for results returned by <link linkend="zeitgeist-log-find-events"><function>zeitgeist_log_find_events()</function></link>, <link linkend="zeitgeist-log-get-events"><function>zeitgeist_log_get_events()</function></link>, and <link linkend="zeitgeist-index-search"><function>zeitgeist_index_search()</function></link>.</para><para>This interface utilizes a cursor-like metaphor. You advance the cursor by calling <link linkend="zeitgeist-result-set-next"><function>zeitgeist_result_set_next()</function></link> or adjust it manually by calling <link linkend="zeitgeist-result-set-seek"><function>zeitgeist_result_set_seek()</function></link>.</para><para>Calling <link linkend="zeitgeist-result-set-next"><function>zeitgeist_result_set_next()</function></link> will also return the event at the current cursor position. You may retrieve the current event without advancing the cursor by calling <link linkend="zeitgeist-result-set-peek"><function>zeitgeist_result_set_peek()</function></link>.</para>
</para>
</refsect1>
<refsect1 id="ZeitgeistResultSet.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="zeitgeist-result-set-size" role="function">
<title>zeitgeist_result_set_size ()</title>
<indexterm zone="zeitgeist-result-set-size"><primary>zeitgeist_result_set_size</primary></indexterm>
<programlisting><link linkend="guint"><returnvalue>guint</returnvalue></link>               zeitgeist_result_set_size           (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);</programlisting>
<para>
Get the number of <link linkend="ZeitgeistEvent"><type>ZeitgeistEvent</type></link>&lt;!-- --&gt;s held in a <link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link>. Unlike the number obtained from <link linkend="zeitgeist-result-set-estimated-matches"><function>zeitgeist_result_set_estimated_matches()</function></link> the size of the result set is always equal to the number of times you can call <link linkend="zeitgeist-result-set-next"><function>zeitgeist_result_set_next()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> instance</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>The number of events held in the result set</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-result-set-estimated-matches" role="function">
<title>zeitgeist_result_set_estimated_matches ()</title>
<indexterm zone="zeitgeist-result-set-estimated-matches"><primary>zeitgeist_result_set_estimated_matches</primary></indexterm>
<programlisting><link linkend="guint"><returnvalue>guint</returnvalue></link>               zeitgeist_result_set_estimated_matches
                                                        (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);</programlisting>
<para>
Get the total number of matches that would have been for the query that generated the result set had it not been restricted in size. For FTS the number of matches is estimated.
</para>
<para>
<para>For <link linkend="zeitgeist-log-find-events"><function>zeitgeist_log_find_events()</function></link> and <link linkend="zeitgeist-log-get-events"><function>zeitgeist_log_get_events()</function></link> this will always be the same as <link linkend="zeitgeist-result-set-size"><function>zeitgeist_result_set_size()</function></link>. For cases like <link linkend="zeitgeist-index-search"><function>zeitgeist_index_search()</function></link> where you specify a subset of the hits to retrieve the estimated match count will often be bigger than the result set size.</para>
</para><variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> instance</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>The number of events that matched the query</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-result-set-next-value" role="function">
<title>zeitgeist_result_set_next_value ()</title>
<indexterm zone="zeitgeist-result-set-next-value"><primary>zeitgeist_result_set_next_value</primary></indexterm>
<programlisting><link linkend="ZeitgeistEvent"><returnvalue>ZeitgeistEvent</returnvalue></link> *    zeitgeist_result_set_next_value     (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);</programlisting>
<para>
Get the current event from the result set and advance the cursor. To ensure that calls to this method will succeed you can call <link linkend="zeitgeist-result-set-has-next"><function>zeitgeist_result_set_has_next()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> instance</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>The <link linkend="ZeitgeistEvent"><type>ZeitgeistEvent</type></link> at the current cursor position, or NULL if there are no events left.</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-result-set-has-next" role="function">
<title>zeitgeist_result_set_has_next ()</title>
<indexterm zone="zeitgeist-result-set-has-next"><primary>zeitgeist_result_set_has_next</primary></indexterm>
<programlisting><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>            zeitgeist_result_set_has_next       (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);</programlisting>
<para>
Check if a call to <link linkend="zeitgeist-result-set-next"><function>zeitgeist_result_set_next()</function></link> will succeed.
</para><variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> instance</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>TRUE if and only if more events can be retrieved by calling <link linkend="zeitgeist-result-set-next"><function>zeitgeist_result_set_next()</function></link></simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-result-set-tell" role="function">
<title>zeitgeist_result_set_tell ()</title>
<indexterm zone="zeitgeist-result-set-tell"><primary>zeitgeist_result_set_tell</primary></indexterm>
<programlisting><link linkend="guint"><returnvalue>guint</returnvalue></link>               zeitgeist_result_set_tell           (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);</programlisting>
<para>
Get the current position of the cursor.
</para><variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> instance</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>The current position of the cursor</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-result-set-reset" role="function">
<title>zeitgeist_result_set_reset ()</title>
<indexterm zone="zeitgeist-result-set-reset"><primary>zeitgeist_result_set_reset</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                zeitgeist_result_set_reset          (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);</programlisting>
<para>
Resets the result set to start iterating it again from scratch.
</para><variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> instance</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-result-set-iterator" role="function">
<title>zeitgeist_result_set_iterator ()</title>
<indexterm zone="zeitgeist-result-set-iterator"><primary>zeitgeist_result_set_iterator</primary></indexterm>
<programlisting><link linkend="ZeitgeistResultSet"><returnvalue>ZeitgeistResultSet</returnvalue></link> * zeitgeist_result_set_iterator      (<parameter><link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *self</parameter>);</programlisting>
<para>
Do not use this method! It is only for use by Vala.
</para><variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> instance</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="ZeitgeistResultSet-struct" role="struct">
<title>ZeitgeistResultSet</title>
<indexterm zone="ZeitgeistResultSet-struct"><primary>ZeitgeistResultSet</primary></indexterm>
<programlisting>typedef struct _ZeitgeistResultSet ZeitgeistResultSet;</programlisting>
<para>
Cursor-like interface for results sets
</para>
<para>
<para>include: zeitgeist.h</para><para>Interface for results returned by <link linkend="zeitgeist-log-find-events"><function>zeitgeist_log_find_events()</function></link>, <link linkend="zeitgeist-log-get-events"><function>zeitgeist_log_get_events()</function></link>, and <link linkend="zeitgeist-index-search"><function>zeitgeist_index_search()</function></link>.</para><para>This interface utilizes a cursor-like metaphor. You advance the cursor by calling <link linkend="zeitgeist-result-set-next"><function>zeitgeist_result_set_next()</function></link> or adjust it manually by calling <link linkend="zeitgeist-result-set-seek"><function>zeitgeist_result_set_seek()</function></link>.</para><para>Calling <link linkend="zeitgeist-result-set-next"><function>zeitgeist_result_set_next()</function></link> will also return the event at the current cursor position. You may retrieve the current event without advancing the cursor by calling <link linkend="zeitgeist-result-set-peek"><function>zeitgeist_result_set_peek()</function></link>.</para>
</para></refsect2>
<refsect2 id="ZeitgeistResultSetIface" role="struct">
<title>struct ZeitgeistResultSetIface</title>
<indexterm zone="ZeitgeistResultSetIface"><primary>ZeitgeistResultSetIface</primary></indexterm>
<programlisting>struct ZeitgeistResultSetIface {
	GTypeInterface parent_iface;
	guint (*size) (ZeitgeistResultSet* self);
	guint (*estimated_matches) (ZeitgeistResultSet* self);
	ZeitgeistEvent* (*next_value) (ZeitgeistResultSet* self);
	gboolean (*has_next) (ZeitgeistResultSet* self);
	guint (*tell) (ZeitgeistResultSet* self);
	void (*reset) (ZeitgeistResultSet* self);
};
</programlisting>
<para>
Interface for creating <link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> implementations.
</para><variablelist role="struct">
<varlistentry><term><link linkend="GTypeInterface"><type>GTypeInterface</type></link>&#160;<structfield id="ZeitgeistResultSetIface.parent-iface">parent_iface</structfield>;</term>
<listitem><simpara>the parent interface structure</simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="ZeitgeistResultSetIface.size">size</structfield>&#160;()</term>
<listitem><simpara>virtual method called by <link linkend="zeitgeist-result-set-size"><function><link linkend="zeitgeist-result-set-size"><function>zeitgeist_result_set_size()</function></link></function></link></simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="ZeitgeistResultSetIface.estimated-matches">estimated_matches</structfield>&#160;()</term>
<listitem><simpara>virtual method called by <link linkend="zeitgeist-result-set-estimated-matches"><function><link linkend="zeitgeist-result-set-estimated-matches"><function>zeitgeist_result_set_estimated_matches()</function></link></function></link></simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="ZeitgeistResultSetIface.next-value">next_value</structfield>&#160;()</term>
<listitem><simpara>virtual method called by <link linkend="zeitgeist-result-set-next-value"><function><link linkend="zeitgeist-result-set-next-value"><function>zeitgeist_result_set_next_value()</function></link></function></link></simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="ZeitgeistResultSetIface.has-next">has_next</structfield>&#160;()</term>
<listitem><simpara>virtual method called by <link linkend="zeitgeist-result-set-has-next"><function><link linkend="zeitgeist-result-set-has-next"><function>zeitgeist_result_set_has_next()</function></link></function></link></simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="ZeitgeistResultSetIface.tell">tell</structfield>&#160;()</term>
<listitem><simpara>virtual method called by <link linkend="zeitgeist-result-set-tell"><function><link linkend="zeitgeist-result-set-tell"><function>zeitgeist_result_set_tell()</function></link></function></link></simpara></listitem>
</varlistentry>
<varlistentry><term><structfield id="ZeitgeistResultSetIface.reset">reset</structfield>&#160;()</term>
<listitem><simpara>virtual method called by <link linkend="zeitgeist-result-set-reset"><function><link linkend="zeitgeist-result-set-reset"><function>zeitgeist_result_set_reset()</function></link></function></link></simpara></listitem>
</varlistentry>
</variablelist></refsect2>

</refsect1>

</refentry>
