## Automatic String Completion

Automatic String Completion — support for automatic completion using a group of target strings.

## Synopsis

    #include <glib.h>

                GCompletion;
    GCompletion* g_completion_new               (GCompletionFunc func);
    gchar*      (*GCompletionFunc)              (gpointer);
    void        g_completion_add_items          (GCompletion *cmp,
                                                 GList *items);
    void        g_completion_remove_items       (GCompletion *cmp,
                                                 GList *items);
    void        g_completion_clear_items        (GCompletion *cmp);
    GList*      g_completion_complete           (GCompletion *cmp,
                                                 const gchar *prefix,
                                                 gchar **new_prefix);
    GList*      g_completion_complete_utf8      (GCompletion *cmp,
                                                 const gchar *prefix,
                                                 gchar **new_prefix);
    void        g_completion_set_compare        (GCompletion *cmp,
                                                 GCompletionStrncmpFunc strncmp_func);
    gint        (*GCompletionStrncmpFunc)       (const gchar *s1,
                                                 const gchar *s2,
                                                 gsize n);
    void        g_completion_free               (GCompletion *cmp);

## Description

GCompletion provides support for automatic completion of a string using any group of target strings. It is typically used for file name completion as is common in many UNIX shells.

A GCompletion is created using `g_completion_new()`. Target items are added and removed with `g_completion_add_items()`, `g_completion_remove_items()` and `g_completion_clear_items()`. A completion attempt is requested with `g_completion_complete()` or `g_completion_complete_utf8()`. When no longer needed, the GCompletion is freed with `g_completion_free()`.

Items in the completion can be simple strings (e.g. filenames), or pointers to arbitrary data structures. If data structures are used you must provide a GCompletionFunc in `g_completion_new()`, which retrieves the item's string from the data structure. You can change the way in which strings are compared by setting a different GCompletionStrncmpFunc in `g_completion_set_compare()`.

## Details

### GCompletion

    typedef struct {
      GList* items;
      GCompletionFunc func;

      gchar* prefix;
      GList* cache;
      GCompletionStrncmpFunc strncmp_func;
    } GCompletion;

The data structure used for automatic completion.

GList *`items`; | list of target items (strings or data structures).
GCompletionFunc `func`; | function which is called to get the string associated with a target item. It is `NULL` if the target items are strings.
gchar *`prefix`; | the last prefix passed to `g_completion_complete()` or `g_completion_complete_utf8()`.
GList *`cache`; | the list of items which begin with `prefix`.
GCompletionStrncmpFunc `strncmp_func`; | The function to use when comparing strings. Use `g_completion_set_compare()` to modify this function.

### g_completion_new ()

    GCompletion* g_completion_new               (GCompletionFunc func);

Creates a new GCompletion.

`func` : | the function to be called to return the string representing an item in the GCompletion, or `NULL` if strings are going to be used as the GCompletion items.
Returns : | the new GCompletion.

### GCompletionFunc ()

    gchar*      (*GCompletionFunc)              (gpointer);

Specifies the type of the function passed to `g_completion_new()`. It should return the string corresponding to the given target item. This is used when you use data structures as GCompletion items.

`Param1` : | the completion item.
Returns : | the string corresponding to the item.

### g_completion_add_items ()

    void        g_completion_add_items          (GCompletion *cmp,
                                                 GList *items);

Adds items to the GCompletion.

`cmp` : | the GCompletion.
`items` : | the list of items to add.

### g_completion_remove_items ()

    void        g_completion_remove_items       (GCompletion *cmp,
                                                 GList *items);

Removes items from a GCompletion.

`cmp` : | the GCompletion.
`items` : | the items to remove.

### g_completion_clear_items ()

    void        g_completion_clear_items        (GCompletion *cmp);

Removes all items from the GCompletion.

`cmp` : | the GCompletion.

### g_completion_complete ()

    GList*      g_completion_complete           (GCompletion *cmp,
                                                 const gchar *prefix,
                                                 gchar **new_prefix);

Attempts to complete the string `prefix` using the GCompletion target items.

`cmp` : | the GCompletion.
`prefix` : | the prefix string, typically typed by the user, which is compared with each of the items.
`new_prefix` : | if non-`NULL`, returns the longest prefix which is common to all items that matched `prefix`, or `NULL` if no items matched `prefix`. This string should be freed when no longer needed.
Returns : | the list of items whose strings begin with `prefix`. This should not be changed.

### g_completion_complete_utf8 ()

    GList*      g_completion_complete_utf8      (GCompletion *cmp,
                                                 const gchar *prefix,
                                                 gchar **new_prefix);

Attempts to complete the string `prefix` using the GCompletion target items. In contrast to `g_completion_complete()`, this function returns the largest common prefix that is a valid UTF-8 string, omitting a possible common partial character.

You should use this function instead of `g_completion_complete()` if your items are UTF-8 strings.

`cmp` : | the GCompletion
`prefix` : | the prefix string, typically used by the user, which is compared with each of the items
`new_prefix` : | if non-`NULL`, returns the longest prefix which is common to all items that matched `prefix`, or `NULL` if no items matched `prefix`. This string should be freed when no longer needed.
Returns : | the list of items whose strings begin with `prefix`. This should not be changed.

Since 2.4

### g_completion_set_compare ()

    void        g_completion_set_compare        (GCompletion *cmp,
                                                 GCompletionStrncmpFunc strncmp_func);

Sets the function to use for string comparisons. The default string comparison function is `strncmp()`.

`cmp` : | a GCompletion.
`strncmp_func` : | the string comparison function.

### GCompletionStrncmpFunc ()

    gint        (*GCompletionStrncmpFunc)       (const gchar *s1,
                                                 const gchar *s2,
                                                 gsize n);

Specifies the type of the function passed to `g_completion_set_compare()`. This is used when you use strings as GCompletion items.

`s1` : | string to compare with `s2`.
`s2` : | string to compare with `s1`.
`n` : | maximal number of bytes to compare.
Returns : | an integer less than, equal to, or greater than zero if the first `n` bytes of `s1` is found, respectively, to be less than, to match, or to be greater than the first `n` bytes of `s2`.

### g_completion_free ()

    void        g_completion_free               (GCompletion *cmp);

Frees all memory used by the GCompletion.

`cmp` : | the GCompletion.