DhCompletion: Devhelp Reference Manual

## DhCompletion DhCompletion — Support for automatic string completion |

## Functions

DhCompletion * | dh_completion_new ()
void | dh_completion_add_string ()
void | dh_completion_sort ()
gchar * | dh_completion_complete ()
gchar * | dh_completion_aggregate_complete ()

## Types and Values

struct | DhCompletion

## Object Hierarchy

        GObject
        ╰── DhCompletion

## Includes

    #include <devhelp/devhelp.h>

## Description

DhCompletion is a basic replacement for GCompletion. GCompletion (part of GLib) is deprecated, and doesn't use a great data structure (a simple GList). DhCompletion uses a GSequence instead, so once the data is sorted it should be faster. DhCompletion works only with UTF-8 strings, and copies the strings.

DhCompletion is add-only, strings cannot be removed. But with `dh_completion_aggregate_complete()`, a DhCompletion object can be removed from the list.

## Functions

### dh_completion_new ()

    DhCompletion *
    dh_completion_new (void);

#### Returns

a new DhCompletion object.

Since: 3.28

### dh_completion_add_string ()

    void
    dh_completion_add_string (DhCompletion *completion,
                              const gchar *str);

Adds a string to the `completion` object.

After adding all the strings you need to call `dh_completion_sort()`.

#### Parameters

completion | a DhCompletion. |
str | a string. |

Since: 3.28

### dh_completion_sort ()

    void
    dh_completion_sort (DhCompletion *completion);

Sorts all the strings. It is required to call this function after adding strings with `dh_completion_add_string()`.

#### Parameters

completion | a DhCompletion. |

Since: 3.28

### dh_completion_complete ()

    gchar *
    dh_completion_complete (DhCompletion *completion,
                            const gchar *prefix);

This function does the equivalent of:

1. Searches the data structure of `completion` to find all strings that have `prefix` as prefix.

2. From the list found at step 1, find the longest prefix that still matches all the strings in the list.

This function assumes that `prefix` and the strings contained in `completion` are in UTF-8. If all the strings are valid UTF-8, then the return value will also be valid UTF-8 (it won't return a partial multi-byte character).

#### Parameters

completion | a DhCompletion. |
prefix | the string to complete. |

#### Returns

the completed prefix, or `NULL` if a longer prefix has not been found. Free with `g_free()` when no longer needed.

[transfer full][nullable]

Since: 3.28

### dh_completion_aggregate_complete ()

    gchar *
    dh_completion_aggregate_complete (GList *completion_objects,
                                      const gchar *prefix);

The same as `dh_completion_complete()`, but aggregated for several DhCompletion objects.

#### Parameters

completion_objects | a GList of DhCompletion objects. | [element-type DhCompletion][nullable]
prefix | the string to complete. |

#### Returns

the completed prefix, or `NULL` if a longer prefix has not been found. Free with `g_free()` when no longer needed.

[transfer full][nullable]

Since: 3.28

## Types and Values

### struct DhCompletion

    struct DhCompletion;