GLib Reference Manual: Automatic String Completion

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.