Automatic String Completion: GLib Reference Manual

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

## Functions

GCompletion * | g_completion_new ()
gchar * | (*GCompletionFunc) ()
void | g_completion_add_items ()
void | g_completion_remove_items ()
void | g_completion_clear_items ()
GList * | g_completion_complete ()
GList * | g_completion_complete_utf8 ()
void | g_completion_set_compare ()
gint | (*GCompletionStrncmpFunc) ()
void | g_completion_free ()

## Types and Values

struct | GCompletion

## Includes

    #include <glib.h>

## 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.

## Functions

### g_completion_new ()

    GCompletion *
    g_completion_new (GCompletionFunc func);

`g_completion_new` is deprecated and should not be used in newly-written code.

Creates a new GCompletion.

#### Parameters

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.

#### Parameters

Param1 | the completion item. |

#### Returns

the string corresponding to the item.

### g_completion_add_items ()

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

`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.

#### Parameters

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

`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.

#### Parameters

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

### g_completion_clear_items ()

    void
    g_completion_clear_items (GCompletion *cmp);

`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.

#### Parameters

cmp | the GCompletion. |

### g_completion_complete ()

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

`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.

#### Parameters

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

`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.

#### Parameters

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

`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()`.

#### Parameters

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.

#### Parameters

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

`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.

#### Parameters

cmp | the GCompletion. |

## Types and Values

### struct GCompletion

    struct GCompletion {
      GList* items;
      GCompletionFunc func;

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

The data structure used for automatic completion.

#### Members

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. |