GListStore: GIO Reference Manual

## GListStore GListStore — A simple implementation of GListModel |

## Functions

GListStore * | g_list_store_new ()
void | g_list_store_insert ()
guint | g_list_store_insert_sorted ()
void | g_list_store_append ()
void | g_list_store_remove ()
void | g_list_store_remove_all ()
void | g_list_store_splice ()
void | g_list_store_sort ()
gboolean | g_list_store_find ()
gboolean | g_list_store_find_with_equal_func ()
gboolean | g_list_store_find_with_equal_func_full ()

## Properties

GType * | item-type | Read / Write / Construct Only
guint | n-items | Read

## Types and Values

| GListStore

## Object Hierarchy

        GObject
        ╰── GListStore

## Implemented Interfaces

GListStore implements GListModel.

## Includes

    #include <gio/gio.h>

## Description

GListStore is a simple implementation of GListModel that stores all items in memory.

It provides insertions, deletions, and lookups in logarithmic time with a fast path for the common case of iterating the list linearly.

## Functions

### g_list_store_new ()

    GListStore *
    g_list_store_new (GType item_type);

Creates a new GListStore with items of type `item_type` . `item_type` must be a subclass of GObject.

#### Parameters

item_type | the GType of items in the list |

#### Returns

a new GListStore

Since: 2.44

### g_list_store_insert ()

    void
    g_list_store_insert (GListStore *store,
                         guint position,
                         gpointer item);

Inserts `item` into `store` at `position` . `item` must be of type “item-type” or derived from it. `position` must be smaller than the length of the list, or equal to it to append.

This function takes a ref on `item` .

Use `g_list_store_splice()` to insert multiple items at the same time efficiently.

#### Parameters

store | a GListStore |
position | the position at which to insert the new item |
item | the new item. | [type GObject]

Since: 2.44

### g_list_store_insert_sorted ()

    guint
    g_list_store_insert_sorted (GListStore *store,
                                gpointer item,
                                GCompareDataFunc compare_func,
                                gpointer user_data);

Inserts `item` into `store` at a position to be determined by the `compare_func` .

The list must already be sorted before calling this function or the result is undefined. Usually you would approach this by only ever inserting items by way of this function.

This function takes a ref on `item` .

#### Parameters

store | a GListStore |
item | the new item. | [type GObject]
compare_func | pairwise comparison function for sorting. | [scope call][closure user_data]
user_data | user data for `compare_func` |

#### Returns

the position at which `item` was inserted

Since: 2.44

### g_list_store_append ()

    void
    g_list_store_append (GListStore *store,
                         gpointer item);

Appends `item` to `store` . `item` must be of type “item-type”.

This function takes a ref on `item` .

Use `g_list_store_splice()` to append multiple items at the same time efficiently.

#### Parameters

store | a GListStore |
item | the new item. | [type GObject]

Since: 2.44

### g_list_store_remove ()

    void
    g_list_store_remove (GListStore *store,
                         guint position);

Removes the item from `store` that is at `position` . `position` must be smaller than the current length of the list.

Use `g_list_store_splice()` to remove multiple items at the same time efficiently.

#### Parameters

store | a GListStore |
position | the position of the item that is to be removed |

Since: 2.44

### g_list_store_remove_all ()

    void
    g_list_store_remove_all (GListStore *store);

Removes all items from `store` .

#### Parameters

store | a GListStore |

Since: 2.44

### g_list_store_splice ()

    void
    g_list_store_splice (GListStore *store,
                         guint position,
                         guint n_removals,
                         gpointer *additions,
                         guint n_additions);

Changes `store` by removing `n_removals` items and adding `n_additions` items to it. `additions` must contain `n_additions` items of type “item-type”. `NULL` is not permitted.

This function is more efficient than `g_list_store_insert()` and `g_list_store_remove()`, because it only emits “items-changed” once for the change.

This function takes a ref on each item in `additions` .

The parameters `position` and `n_removals` must be correct (ie: `position` + `n_removals` must be less than or equal to the length of the list at the time this function is called).

#### Parameters

store | a GListStore |
position | the position at which to make the change |
n_removals | the number of items to remove |
additions | the items to add. | [array length=n_additions][element-type GObject]
n_additions | the number of items to add |

Since: 2.44

### g_list_store_sort ()

    void
    g_list_store_sort (GListStore *store,
                       GCompareDataFunc compare_func,
                       gpointer user_data);

Sort the items in `store` according to `compare_func` .

#### Parameters

store | a GListStore |
compare_func | pairwise comparison function for sorting. | [scope call][closure user_data]
user_data | user data for `compare_func` |

Since: 2.46

### g_list_store_find ()

    gboolean
    g_list_store_find (GListStore *store,
                       gpointer item,
                       guint *position);

Looks up the given `item` in the list store by looping over the items until the first occurrence of `item` . If `item` was not found, then `position` will not be set, and this method will return `FALSE`.

If you need to compare the two items with a custom comparison function, use `g_list_store_find_with_equal_func()` with a custom GEqualFunc instead.

#### Parameters

store | a GListStore |
item | an item. | [type GObject]
position | the first position of `item` , if it was found. | [out][optional]

#### Returns

Whether `store` contains `item` . If it was found, `position` will be set to the position where `item` occurred for the first time.

Since: 2.64

### g_list_store_find_with_equal_func ()

    gboolean
    g_list_store_find_with_equal_func (GListStore *store,
                                       gpointer item,
                                       GEqualFunc equal_func,
                                       guint *position);

Looks up the given `item` in the list store by looping over the items and comparing them with `equal_func` until the first occurrence of `item` which matches. If `item` was not found, then `position` will not be set, and this method will return `FALSE`.

`item` is always passed as second parameter to `equal_func` .

Since GLib 2.76 it is possible to pass `NULL` for `item` .

#### Parameters

store | a GListStore |
item | an item. | [type GObject][nullable]
equal_func | A custom equality check function. | [scope call]
position | the first position of `item` , if it was found. | [out][optional]

#### Returns

Whether `store` contains `item` . If it was found, `position` will be set to the position where `item` occurred for the first time.

Since: 2.64

### g_list_store_find_with_equal_func_full ()

    gboolean
    g_list_store_find_with_equal_func_full
                                   (GListStore *store,
                                    gpointer item,
                                    GEqualFuncFull equal_func,
                                    gpointer user_data,
                                    guint *position);

Like `g_list_store_find_with_equal_func()` but with an additional `user_data` that is passed to `equal_func` .

`item` is always passed as second parameter to `equal_func` .

Since GLib 2.76 it is possible to pass `NULL` for `item` .

#### Parameters

store | a GListStore |
item | an item. | [type GObject][nullable]
equal_func | A custom equality check function. | [scope call][closure user_data]
user_data | user data for `equal_func` |
position | the first position of `item` , if it was found. | [out][optional]

#### Returns

Whether `store` contains `item` . If it was found, `position` will be set to the position where `item` occurred for the first time.

Since: 2.74

## Types and Values

### GListStore

    typedef struct _GListStore GListStore;

GListStore is an opaque data structure and can only be accessed using the following functions.

## Property Details

### The `“item-type”` property

      “item-type”                GType *

The type of items contained in this list store. Items must be subclasses of GObject.

Owner: GListStore

Flags: Read / Write / Construct Only

Allowed values: GObject

Since: 2.44

### The `“n-items”` property

      “n-items”                  guint

The number of items contained in this list store.

Owner: GListStore

Flags: Read

Default value: 0

Since: 2.74