## Automatic String Completion

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

## Synopsis

    #include <glib.h>

    struct              GCompletion;
    GCompletion *       g_completion_new                    (GCompletionFunc func);
    gchar *             (*GCompletionFunc)                  (gpointer Param1);
    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()`.

GCompletion has been marked as deprecated, since this API is rarely used and not very actively maintained.

## Details

### struct GCompletion

    struct GCompletion {
      GList* items;
      GCompletionFunc func;

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

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 Param1);

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);

### Warning

`g_completion_add_items` has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

Adds items to the GCompletion.

`cmp` : | the GCompletion.
`items` : | the list of items to add. [transfer none]

### g_completion_remove_items ()

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

### Warning

`g_completion_remove_items` has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

Removes items from a GCompletion. The items are not freed, so if the memory was dynamically allocated, free `items` with `g_list_free_full()` after calling this function.

`cmp` : | the GCompletion.
`items` : | the items to remove. [transfer none]

### g_completion_clear_items ()

    void                g_completion_clear_items            (GCompletion *cmp);

### Warning

`g_completion_clear_items` has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

Removes all items from the GCompletion. The items are not freed, so if the memory was dynamically allocated, it should be freed after calling this function.

`cmp` : | the GCompletion.

### g_completion_complete ()

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

### Warning

`g_completion_complete` has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

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. [transfer none]

### g_completion_complete_utf8 ()

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

### Warning

`g_completion_complete_utf8` has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

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. [element-type utf8][transfer none]

Since 2.4

### g_completion_set_compare ()

    void                g_completion_set_compare            (GCompletion *cmp,
                                                             GCompletionStrncmpFunc strncmp_func);

### Warning

`g_completion_set_compare` has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

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);

### Warning

`g_completion_free` has been deprecated since version 2.26 and should not be used in newly-written code. Rarely used API

Frees all memory used by the GCompletion. The items are not freed, so if the memory was dynamically allocated, it should be freed after calling this function.

`cmp` : | the GCompletion.