Automatic String Completion

Automatic String Completion — Поддержка для автоматического завершения используя группу целевых строк.

Краткое описание


#include <glib.h>


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

Описание

GCompletion обеспечивает поддержку автоматического завершения строки используя любую группу целевых строк. Это обычно используется для завершения имён файлов как в обычных оболочках UNIX.

GCompletion создаётся используя g_completion_new(). Целевые элементы добавляются и удаляются с помощью g_completion_add_items(), g_completion_remove_items() и g_completion_clear_items(). Попытка завершения запрашивается с помощью g_completion_complete() или g_completion_complete_utf8(). GCompletion освобождается с помощью g_completion_free() когда больше не нужна.

Завершающими элементами могут быть просто строки (например имена файлов), или указателями на произвольные структуры данных. Если используются структуры данных вы должны обеспечить GCompletionFunc в g_completion_new(), которая находит элементы строк в структуре данных. Вы можете изменять способ сравнения строк устанавливая разные GCompletionStrncmpFunc в g_completion_set_compare().

Детали

GCompletion

typedef struct {
  GList* items;
  GCompletionFunc func;
 
  gchar* prefix;
  GList* cache;
  GCompletionStrncmpFunc strncmp_func;
} GCompletion;

Структура данных используемая для автоматического завершения.

GList *items; список целевых элементов (строки или структуры данных).
GCompletionFunc func; функция вызываемая для получения строки связанной с целевым элементом. Может быть NULL если целевые элементы являются строками.
gchar *prefix; последний префикс помещаемый в g_completion_complete() или g_completion_complete_utf8().
GList *cache; список элементов который начинается с prefix.
GCompletionStrncmpFunc strncmp_func; функция используемая для сравнения строк. Используйте g_completion_set_compare() для изменения этой функции.

g_completion_new ()

GCompletion* g_completion_new               (GCompletionFunc func);

Создаёт новую GCompletion.

func : функция вызываемая для возврата строки представляющей элемент в GCompletion, или NULL если строки будут использоваться как элементы GCompletion.
Возвращает : новая структура GCompletion.

GCompletionFunc ()

gchar*      (*GCompletionFunc)              (gpointer );

Определяет тип функции помещаемой в g_completion_new(). Она должна возвращать строку соответствующую полученному целевому элементу. Используется когда вы используете структуры данных как элементы GCompletion.

Param1 : завершающий элемент.
Возвращает : строка соответствующая элементу.

g_completion_add_items ()

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

Добавляет элементы в GCompletion.

cmp : GCompletion.
items : список добавляемых элементов.

g_completion_remove_items ()

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

Удаляет элементы из GCompletion.

cmp : GCompletion.
items : элементы для удаления.

g_completion_clear_items ()

void        g_completion_clear_items        (GCompletion *cmp);

Удаляет все элементы для удаления GCompletion.

cmp : GCompletion.

g_completion_complete ()

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

Пытается завершить строку prefix используя целевые элементы GCompletion.

cmp : GCompletion.
prefix : строковый префикс, обычно печатается пользователем, который сравнивается с каждым элементом структуры.
new_prefix : если не-NULL, возвращает самый длинный префикс который является основой для всех элементов соответствующих prefix, или NULL если нет элементов соответствующих prefix. Эта строка должна освобождаться когда больше не нужна.
Возвращает : список элементов строки которых начинаются с prefix. Не должно изменяться.

g_completion_complete_utf8 ()

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

Пытается завершить строку prefix используя целевые элементы GCompletion. В отличие от g_completion_complete(), эта функция возвращает самый длинный prefix который является допустимой строкой UTF-8, опуская возможные общие части символа.

Вы должны использовать эту функцию вместо g_completion_complete() если ваши элементы являются строками UTF-8.

cmp : the GCompletion
prefix : строка префикс, обычно используется пользователем, которая сравнивается с каждым элементом
new_prefix : если не-NULL, возвращает самый длинный префикс который является основой для всех элементов соответствующих prefix, или NULL если нет элементов соответствующих prefix. Эта строка должна освобождаться когда больше не нужна.
Возвращает : список элементов строки которых начинаются с prefix. Не должен меняться.

Начиная с версии 2.4

g_completion_set_compare ()

void        g_completion_set_compare        (GCompletion *cmp,
                                             GCompletionStrncmpFunc strncmp_func);

Устанавливает функцию используемую для сравнения строк. По умолчанию строки сравниваются функцией strncmp().

cmp : GCompletion.
strncmp_func : функция сравнения строк.

GCompletionStrncmpFunc ()

gint        (*GCompletionStrncmpFunc)       (const gchar *s1,
                                             const gchar *s2,
                                             gsize n);

Определяет тип функции помещаемой в g_completion_set_compare(). Используется когда вы используете строки как элементы GCompletion.

s1 : строка для сравнения с s2.
s2 : строка для сравнения с s1.
n : максимальное количество байт для сравнения.
Возвращает : целочисленное меньше, равное, или больше нуля если первые найденные n байт s1, соответственно меньше, равны, или больше чем первые n байт s2.

g_completion_free ()

void        g_completion_free               (GCompletion *cmp);

Освобождает всю память используемую для GCompletion.

cmp : GCompletion.