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

GCompletion is implemented with a simple GList, while DhCompletion uses a (sorted) GSequence instead (or a GList of DhCompletion objects with `dh_completion_aggregate_complete()`). So DhCompletion should scale better with more data, and DhCompletion should be more appropriate if the same data is used several times (on the other hand if the data is used only once, GCompletion 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 GList.

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