## Model Readers Model Readers — Extracting strings from DeeModels |

## Synopsis

    #include <dee.h>

                        DeeFilter;
                        DeeModelReader;
    gchar *             (*DeeModelReaderFunc)               (DeeModel *model,
                                                             DeeModelIter *iter,
                                                             gpointer userdata);
    void                dee_model_reader_destroy            (DeeModelReader *reader);
    void                dee_model_reader_new                (DeeModelReaderFunc reader_func,
                                                             gpointer userdata,
                                                             GDestroyNotify destroy,
                                                             DeeModelReader *out_reader);
    void                dee_model_reader_new_for_int32_column
                                                            (guint column,
                                                             DeeModelReader *out_reader);
    void                dee_model_reader_new_for_string_column
                                                            (guint column,
                                                             DeeModelReader *out_reader);
    void                dee_model_reader_new_for_uint32_column
                                                            (guint column,
                                                             DeeModelReader *out_reader);
    gchar *             dee_model_reader_read               (DeeModelReader *self,
                                                             DeeModel *model,
                                                             DeeModelIter *iter);

## Description

The purpose of a DeeModelReader is to extract string from a DeeModel. These strings are usually passed through a DeeAnalyzer on into a DeeIndex.

Most readers will extract a value of a given type from a given column, but it must be noted that this is not a requirement. The strings may be built from several columns.

## Details

### DeeFilter

    typedef struct {
      DeeFilterMapFunc   map_func;
      DeeFilterMapNotify map_notify;
      GDestroyNotify     destroy;
      gpointer           userdata;
    } DeeFilter;

Structure encapsulating the mapping logic used to construct a DeeFilterModel

### DeeModelReader

    typedef struct {
      DeeModelReaderFunc reader_func;
      gpointer           userdata;
      GDestroyNotify     destroy;
    } DeeModelReader;

Structure encapsulating the information needed to read strings from a model. Used for example by DeeIndex.

DeeModelReaderFunc `reader_func`; | The DeeModelReaderFunc used to extract string from a model. [scope notified]
gpointer `userdata`; | user data to pass to `reader_func`. [closure]
GDestroyNotify `destroy`; | Called when the reader is destroyed

### DeeModelReaderFunc ()

    gchar *             (*DeeModelReaderFunc)               (DeeModel *model,
                                                             DeeModelIter *iter,
                                                             gpointer userdata);

Extracts a string from a row in a model.

`model` : | The model being indexed
`iter` : | The row to extract terms for
`userdata` : | The data set when registering the reader. [closure]
Returns : | A newly allocated string with the row data to be indexed. Free with `g_free()`.

### dee_model_reader_destroy ()

    void                dee_model_reader_destroy            (DeeModelReader *reader);

Release resources associated with `reader`, but does not free the DeeModelReader structure itself.

This will call the `destroy()` function registered with the reader if it is set.

`reader` : | The reader to destroy

### dee_model_reader_new ()

    void                dee_model_reader_new                (DeeModelReaderFunc reader_func,
                                                             gpointer userdata,
                                                             GDestroyNotify destroy,
                                                             DeeModelReader *out_reader);

Create a new DeeModelReader with the given parameters. This call will zero the `out_reader` struct.

`reader_func` : | The DeeModelReaderFunc to use for the reader. [scope notified]
`userdata` : | The user data to pass to `reader_func`. [closure][allow-none]
`destroy` : | The GDestroyNotify to call on `userdata` when disposing of the reader. [allow-none]
`out_reader` : | A pointer to an uninitialized DeeModelReader struct. [out]

### dee_model_reader_new_for_int32_column ()

    void                dee_model_reader_new_for_int32_column
                                                            (guint column,
                                                             DeeModelReader *out_reader);

A DeeModelReader reading a `gint32` from a DeeModel at a given column

`column` : | The column index to read a `gint32` from
`out_reader` : | A pointer to a DeeModelReader instance which will have all fields initialized appropriately. [out]

### dee_model_reader_new_for_string_column ()

    void                dee_model_reader_new_for_string_column
                                                            (guint column,
                                                             DeeModelReader *out_reader);

A DeeModelReader reading a string from a DeeModel at a given column

`column` : | The column index to read a string from
`out_reader` : | A pointer to a DeeModelReader instance which will have all fields initialized appropriately. [out]

### dee_model_reader_new_for_uint32_column ()

    void                dee_model_reader_new_for_uint32_column
                                                            (guint column,
                                                             DeeModelReader *out_reader);

A DeeModelReader reading a `guint32` from a DeeModel at a given column

`column` : | The column index to read a `guint32` from
`out_reader` : | A pointer to a DeeModelReader instance which will have all fields initialized appropriately. [out]

### dee_model_reader_read ()

    gchar *             dee_model_reader_read               (DeeModelReader *self,
                                                             DeeModel *model,
                                                             DeeModelIter *iter);

Read data from a row in a DeeModel and extract a string representation from it.

Note that generally a DeeModelReader need not be confined to reading from one specific column, although in practice most are.

`self` : | The DeeModelReader used to read `model`
`model` : | The DeeModel to read a string from
`iter` : | The row to read a string from
Returns : | A newly allocated string. Free with `g_free()`.