ModelAbstractSortedList

ModelAbstractSortedList — a basis for creating name-based ModelList implementations

Synopsis

                    ModelAbstractSortedList;
                    ModelAbstractSortedListClass;
void                model_abstract_sorted_list_merge    (ModelAbstractSortedList *sorted,
                                                         const gchar *mode,
                                                         const gconstpointer *keys,
                                                         gulong n_keys);

Description

ModelAbstractSortedList provides a basis for creating ModelList implementations where it is easier to view the data set as a dictionary than a list. It is an abstract class -- it must be subclassed to be used.

The list is kept in sorted form for efficiency.

The canonical example here is a list of files in a directory. The interface to the kernel is defined in terms of names -- not positions in a list. Operations to update the model are easier performed on the basis of those names. This class keeps track of all of the details for you.

There is only one method on this class: model_abstract_sorted_list_merge(), but it is essential for subclasses to implement a number of virtual functions as described in ModelAbstractSortedListClass.

The ModelList virtual functions for model_list_n_children() and model_list_get_child() are implemented by this class.

Details

ModelAbstractSortedList

typedef struct {
  ModelList parent_instance;
} ModelAbstractSortedList;

This is an opaque structure; it may not be accessed directly.

ModelAbstractSortedListClass

typedef struct {
  ModelListClass parent_class;

  gint (*compare)     (ModelAbstractSortedList *list,
                       gconstpointer            a,
                       gconstpointer            b);

  void (*warning)     (ModelAbstractSortedList *list,
                       gulong                   index,
                       gconstpointer            key,
                       gchar                    mode,
                       gulong                   current_index,
                       ModelObject             *value);

  void (*create_item) (ModelAbstractSortedList  *list,
                       gulong                    index,
                       gconstpointer             key,
                       gpointer                 *new_key,
                       ModelObject             **new_object);

  void (*free_key)    (ModelAbstractSortedList *list,
                       gpointer                 key);
} ModelAbstractSortedListClass;

The class structure for ModelAbstractSortedList. All virtual functions must be implemented by each subclass.

ModelListClass `parent_class`;
`compare` ()	Compares two keys. This function defines the sort order of the list.
`warning` ()	This function is called when there is unexpected state during a call to `model_abstract_sorted_list_merge()`. `index` is the index of the item in the list that was passed in to the function. `key` is the key at that index. `mode` is the mode specified for that key. For mode 'I', `current_index` specifies the current index of the already-existing item in the list and `value` is the value of that item. For the other two modes, `current_index` and `value` will be 0 and `NULL`, respectively.
`create_item` ()	This function is called to create an item for a given key before inserting it into the list during a call to `model_abstract_sorted_list_merge()`. The function is also responsible for allocating the permanent copy of the key that will be used by the list. `index` is the index of the item in the list that was passed in to the function. `key` is the key at that index. This function is responsible for setting the value of `new_key` and `new_object` to the values that will be inserted.
`free_key` ()	This function frees a key that was allocated by the `create_item` function.

model_abstract_sorted_list_merge ()

void                model_abstract_sorted_list_merge    (ModelAbstractSortedList *sorted,
                                                         const gchar *mode,
                                                         const gconstpointer *keys,
                                                         gulong n_keys);

Modifies the list by performing insertions, replacements and deletions.

keys (of length n_keys) is an array of pointers to the keys to insert, replace or delete. It must be sorted. keys is not modified in any way, and the values in keys are not used in any way except for being passed in to the 'compare' and 'create_item' functions specified in the ModelAbstractSortedListClass.

mode is a string. It must either be a single character in length or the same length as keys. If it is the length of keys then each character in mode corresponds, respectively, with each item in keys. If mode is a single character, then that character is used for all of the keys.

Each character of mode may be only 'i', 'I', 'r', 'R', 'd', or 'D'. The lowercase letters correspond to the operations "insert", "replace" and "delete". The uppercase letters correspond to the same operations, but with warnings issued in case of an unexpected state. A warning is issued in the case of inserting an item when that item already exists or replacing or deleting an item when that item does not exist. The warnings are issued by calling the warning virtual function defined in the ModelAbstractSortedListClass.

`sorted` :	a ModelAbstractSortedList
`mode` :	the mode string
`keys` :	an array of keys to add or remove
`n_keys` :	the length of `keys`

			Data Model API (libmodel)
Top \| Description