## DeeIndex DeeIndex — An inverted index interface for smart access to a DeeModel |

## Synopsis

    #include <dee.h>

    struct              DeeIndex;
    struct              DeeIndexClass;
    gboolean            (*DeeIndexIterFunc)                 (const gchar *key,
                                                             DeeResultSet *rows,
                                                             gpointer userdata);
    enum                DeeTermMatchFlag;
    void                dee_index_foreach                   (DeeIndex *self,
                                                             const gchar *start_term,
                                                             DeeIndexIterFunc func,
                                                             gpointer userdata);
    DeeAnalyzer *       dee_index_get_analyzer              (DeeIndex *self);
    DeeModel *          dee_index_get_model                 (DeeIndex *self);
    guint               dee_index_get_n_rows                (DeeIndex *self);
    guint               dee_index_get_n_rows_for_term       (DeeIndex *self,
                                                             const gchar *term);
    guint               dee_index_get_n_terms               (DeeIndex *self);
    DeeModelReader *    dee_index_get_reader                (DeeIndex *self);
    guint               dee_index_get_supported_term_match_flags
                                                            (DeeIndex *self);
    DeeResultSet *      dee_index_lookup                    (DeeIndex *self,
                                                             const gchar *term,
                                                             DeeTermMatchFlag flags);
    DeeModelIter *      dee_index_lookup_one                (DeeIndex *self,
                                                             const gchar *term);

## Object Hierarchy

      GObject
       +----DeeIndex
             +----DeeHashIndex
             +----DeeTreeIndex

## Properties

      "analyzer"                 DeeAnalyzer*          : Read / Write / Construct Only
      "model"                    DeeModel*             : Read / Write / Construct Only
      "reader"                   gpointer              : Write / Construct Only

## Description

DeeIndex is an interface for doing key based access to a DeeModel. A key in the index is known as a term and each term is mapped to a set of matching DeeModelIters.

The terms are calculated by means of a DeeAnalyzer which extracts a set of terms from a given row in the model adding these terms to a DeeTermList. There is a suite of analyzers shipped with Dee, which you can browse in the Analyzers section.

## Details

### struct DeeIndex

    struct DeeIndex;

All fields in the DeeIndex structure are private and should never be accessed directly

### struct DeeIndexClass

    struct DeeIndexClass {
      GObjectClass     parent_class;

      DeeResultSet*  (* lookup)             (DeeIndex         *self,
                                             const gchar      *term,
                                             DeeTermMatchFlag  flags);

      void           (* foreach)            (DeeIndex          *self,
                                             const gchar       *start_term,
                                             DeeIndexIterFunc   func,
                                             gpointer           userdata);

      guint          (* get_n_terms)        (DeeIndex     *self);

      guint          (* get_n_rows)         (DeeIndex     *self);

      guint          (* get_n_rows_for_term)(DeeIndex     *self,
                                             const gchar       *term);

      guint          (*get_supported_term_match_flags) (DeeIndex *self);
    };

### DeeIndexIterFunc ()

    gboolean            (*DeeIndexIterFunc)                 (const gchar *key,
                                                             DeeResultSet *rows,
                                                             gpointer userdata);

The signature of the function passed to `dee_index_foreach()`.

Be cautious if you plan on modifying the rows in the model via the DeeModelIters you find. Your code may have to be reentrant since the index may change in reaction to the changes in the model. It's not impossible to do this in a non-broken manner, but it may likely require you calling `dee_model_freeze_signals()` and `dee_model_thaw_signals()` at strategic points.

`key` : | A key in the index being traversed
`rows` : | A DeeResultSet. Do not free or modify.
`userdata` : | The pointer passed to `dee_index_foreach()`. [closure]
Returns : | `FALSE` if iteration should stop, `TRUE` if it should continue

### enum DeeTermMatchFlag

    typedef enum {
      DEE_TERM_MATCH_EXACT = 1 << 0,
      DEE_TERM_MATCH_PREFIX = 1 << 1
    } DeeTermMatchFlag;

Flags passed to `dee_index_lookup()` to control how matching is done. Note that it is not required that index backends support more than just DEE_TERM_MATCH_EXACT.

You can query for the supported flags with `dee_index_get_supported_term_match_flags()`.

`DEE_TERM_MATCH_EXACT` | Match terms byte for byte as specified in the query string
`DEE_TERM_MATCH_PREFIX` | Match if the indexed term begins with the byte string being queried by. This is also sometimes known as truncated- or wildcard queries

### dee_index_foreach ()

    void                dee_index_foreach                   (DeeIndex *self,
                                                             const gchar *start_term,
                                                             DeeIndexIterFunc func,
                                                             gpointer userdata);

Iterate over an index optionally starting from some given term. Note that unordered indexes (like DeeHashIndex) has undefined behaviour with this method.

`self` : | The index to iterate over
`start_term` : | The term to start from or `NULL` to iterate over all terms
`func` : | Called for each term in the index. [scope call]
`userdata` : | Arbitrary data to pass back to `func`. [closure]

### dee_index_get_analyzer ()

    DeeAnalyzer *       dee_index_get_analyzer              (DeeIndex *self);

Get the analyzer being used to analyze terms extracted with the DeeModelReader used by this index.

`self` : | The index to get the analyzer for
Returns : | The DeeAnalyzer used to analyze terms with. [transfer none]

### dee_index_get_model ()

    DeeModel *          dee_index_get_model                 (DeeIndex *self);

Get the model being indexed by this index

`self` : | The index to get the model for
Returns : | The DeeModel being indexed by this index. [transfer none]

### dee_index_get_n_rows ()

    guint               dee_index_get_n_rows                (DeeIndex *self);

Get the number of indexed rows. A row is only indexed if it has at least one term associated with it. If the analyzer has returned 0 terms then the row is omitted from the index.

`self` : | The index to get the number of rows for
Returns : | The number of rows in the index. Note that this may less than or equal to `dee_model_get_n_rows()`.

### dee_index_get_n_rows_for_term ()

    guint               dee_index_get_n_rows_for_term       (DeeIndex *self,
                                                             const gchar *term);

Get the number of rows that matches a given term

`self` : | The index to inspect
`term` : | The term to look for
Returns : | The number of rows in the index registered for the given term

### dee_index_get_n_terms ()

    guint               dee_index_get_n_terms               (DeeIndex *self);

Get the number of terms in the index

`self` : | The index to get the number of terms for
Returns : | The number of unique terms in the index

### dee_index_get_reader ()

    DeeModelReader *    dee_index_get_reader                (DeeIndex *self);

Get the reader being used to extract terms from rows in the model

`self` : | The index to get the reader for
Returns : | The DeeModelReader used to extract terms with. [transfer none]

### dee_index_get_supported_term_match_flags ()

    guint               dee_index_get_supported_term_match_flags
                                                            (DeeIndex *self);

Get the DeeTermMatchFlag supported by this DeeIndex instance

`self` : | The index to inspect
Returns : | A bit mask of the acceptedd DeeTermMatchFlags

### dee_index_lookup ()

    DeeResultSet *      dee_index_lookup                    (DeeIndex *self,
                                                             const gchar *term,
                                                             DeeTermMatchFlag flags);

`self` : | The index to perform the lookup in
`term` : | The term to look up on
`flags` : | A bitmask of DeeTermMatchFlag to control how matching is done
Returns : | A DeeResultSet. Free with `g_object_unref()`. [transfer full]

### dee_index_lookup_one ()

    DeeModelIter *      dee_index_lookup_one                (DeeIndex *self,
                                                             const gchar *term);

Convenience function in for cases where you have a priori guarantee that a `dee_index_lookup()` call will return exactly 0 or 1 row. If the lookup returns more than 1 row a warning will be printed on standard error and `NULL` will be returned.

The typical use case for this function is if you need something akin to a primary key in a relational database.

`self` : | The index to do the lookup in
`term` : | The exact term to match
Returns : | A DeeModelIter pointing to the matching row or `NULL` in case no rows matches `term`. [transfer none]

## Property Details

### The `"analyzer"` property

      "analyzer"                 DeeAnalyzer*          : Read / Write / Construct Only

The DeeAnalyzer used to analyze terms extracted by the model reader

Type: DeeAnalyzer

### The `"model"` property

      "model"                    DeeModel*             : Read / Write / Construct Only

The DeeModel being indexed

### The `"reader"` property

      "reader"                   gpointer              : Write / Construct Only

The DeeModelReader used to extract terms from rows in the model

Type: DeeModelReader