DeeTermList

## DeeTermList DeeTermList — A simple collection type representing a list of indexed terms for a row in a DeeIndex |

## Synopsis

    #include <dee.h>

    struct              DeeTermList;
    struct              DeeTermListClass;
    DeeTermList *       dee_term_list_add_term              (DeeTermList *self,
                                                             const gchar *term);
    DeeTermList *       dee_term_list_clear                 (DeeTermList *self);
    DeeTermList *       dee_term_list_clone                 (DeeTermList *self);
    const gchar *       dee_term_list_get_term              (DeeTermList *self,
                                                             guint n);
    guint               dee_term_list_num_terms             (DeeTermList *self);

## Object Hierarchy

      GObject
       +----DeeTermList

## Description

DeeTermList is a simple list type containing the indexed terms of a row in a DeeModel as recorded in a DeeIndex. The terms are extracted from the model by using a DeeAnalyzer.

The default implementation of DeeTermList stores all terms in a string pool and reuses terms from that string pool for the entire lifetime of the term list. That is, even if you call `dee_term_list_clear()` on it. This behaviour will save a lot of reallocations and `g_strdup()`s provided there is reuse in the terms over time.

## Details

### struct DeeTermList

    struct DeeTermList;

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

### struct DeeTermListClass

    struct DeeTermListClass {
      GObjectClass     parent_class;

      const gchar*   (* get_term)           (DeeTermList     *self,
                                             guint            n);

      DeeTermList*   (* add_term)           (DeeTermList     *self,
                                             const gchar     *term);

      guint          (* num_terms)          (DeeTermList     *self);

      DeeTermList*   (* clear)              (DeeTermList     *self);

      DeeTermList*   (* clone)              (DeeTermList     *self);
    };

### dee_term_list_add_term ()

    DeeTermList *       dee_term_list_add_term              (DeeTermList *self,
                                                             const gchar *term);

Add a term to the termlist. Note that it is possible to add a term multiple times. The effect of this is determined by the DeeModelIndex consuming the DeeTermList.

`self` : | The term list to add a term to
`term` : | The term to add
Returns : | Always returns `self`. [transfer none]

### dee_term_list_clear ()

    DeeTermList *       dee_term_list_clear                 (DeeTermList *self);

Remove all terms from a term list making it ready for reuse. Note that term list implementations will often have optimized memory allocation schemes so reuse is often more efficient than allocating a new term list each time you need it.

`self` : | The term list to clear
Returns : | Always returns `self`. [transfer none]

### dee_term_list_clone ()

    DeeTermList *       dee_term_list_clone                 (DeeTermList *self);

Create a copy of `self` that shares the underlying string pool and containing a list of terms as currently set in `self`.

Subsequently freeing the original and keeping the clone around is not a problem. The clone works as a standalone term list. The only gotcha may be threading issues because of concurrent access to the shared string pool.

Creating a clone very efficient since only very little memory allocation is required. It's advised that you use a clone instead a new instance whenever you work over a common corpus of strings.

It is also worth noting that terms obtained from the original term list and a clone can be compared directly as pointers (fx. with `g_direct_equal()`). This is because they share the underlying string pool.

`self` : | The term list to clone
Returns : | A newly allocated term list. Free with `g_object_unref()`. [transfer full]

### dee_term_list_get_term ()

    const gchar *       dee_term_list_get_term              (DeeTermList *self,
                                                             guint n);

Get the n'th term in the list.

Note that in the default implementation it is guaranteed that the returned string is valid for the entire lifetime of the DeeTermList.

`self` : | The term list to get the `n`th term from
`n` : | The (zero based) offset into the term list
Returns : | The `n`th string held in the term list

### dee_term_list_num_terms ()

    guint               dee_term_list_num_terms             (DeeTermList *self);

`self` : | The term list to check the number of terms in
Returns : | The number of terms in the term list