DeeIndex

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

Synopsis

#include <dee.h>

gboolean            (*DeeIndexIterFunc)                 (const gchar *key,
                                                         DeeResultSet *rows,
                                                         gpointer userdata);
void                (*DeeAnalyzerFunc)                  (DeeModel *model,
                                                         DeeModelIter *iter,
                                                         DeeTermList *out_terms,
                                                         gpointer userdata);
struct              DeeAnalyzer;
enum                DeeTermMatchFlag;
struct              DeeIndex;
struct              DeeIndexClass;
DeeResultSet *         dee_index_lookup                 (DeeIndex *self,
                                                         const gchar *term,
                                                         DeeTermMatchFlag flags);
void                dee_index_foreach                   (DeeIndex *self,
                                                         const gchar *start_term,
                                                         DeeIndexIterFunc func,
                                                         gpointer userdata);
DeeModel *             dee_index_get_model              (DeeIndex *self);
DeeAnalyzer *          dee_index_get_analyzer           (DeeIndex *self);
guint               dee_index_get_n_terms               (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_supported_term_match_flags
                                                        (DeeIndex *self);
                    DeeIndexPrivate;

Object Hierarchy

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

Properties

  "analyzer"                 gpointer              : Read / Write / Construct Only
  "model"                    DeeModel*             : Read / 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

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

Returns :

FALSE if iteration should stop, TRUE if it should continue

DeeAnalyzerFunc ()

void                (*DeeAnalyzerFunc)                  (DeeModel *model,
                                                         DeeModelIter *iter,
                                                         DeeTermList *out_terms,
                                                         gpointer userdata);

The signature of the function used to build a DeeTermList for a given row in a DeeModel.

model :

The model being indexed

iter :

The row to extract terms for

out_terms :

A DeeTermList to store the extracted terms in

userdata :

The userdata member of the DeeAnalyzer instance

struct DeeAnalyzer

struct DeeAnalyzer {
  DeeAnalyzerFunc analyze;
  gpointer        userdata;
  GDestroyNotify  destroy;
};

Structure encapsulating the logic used to extract terms from a model. This library ships with a few simple default analyzers. See for example dee_analyzer_new_for_key_column() and dee_analyzer_new_for_full_text_column().

You can access the analyzer used by a DeeIndex via the "analyzer" property.

DeeAnalyzerFunc analyze;

gpointer userdata;

Arbitrary data to pass to analyze

GDestroyNotify destroy;

If non-NULL this function will be invoked on userdata when the DeeIndex is finalized

enum DeeTermMatchFlag

typedef enum
{
  DEE_TERM_MATCH_EXACT = 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

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


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_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

userdata :

Arbitrary data to pass back to func

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_analyzer ()

DeeAnalyzer *          dee_index_get_analyzer           (DeeIndex *self);

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

self :

The index to get the analyzer for

Returns :

The DeeAnalyzer used to extract terms with. [transfer none]

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_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_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

DeeIndexPrivate

typedef struct _DeeIndexPrivate DeeIndexPrivate;

Ignore this structure.

Property Details

The "analyzer" property

  "analyzer"                 gpointer              : Read / Write / Construct Only

The DeeAnalyzer used to extract terms from rows in the model


The "model" property

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

The DeeModel being indexed