HudStringList

HudStringList — a refcounted list of strings

Synopsis

                    HudStringList;
HudStringList *     hud_string_list_cons                (const gchar *head,
                                                         HudStringList *tail);
HudStringList *     hud_string_list_cons_label          (const gchar *label,
                                                         HudStringList *tail);
const gchar *       hud_string_list_get_head            (HudStringList *list);
HudStringList *     hud_string_list_get_tail            (HudStringList *list);
gchar *             hud_string_list_pretty_print        (HudStringList *list);
HudStringList *     hud_string_list_ref                 (HudStringList *list);
void                hud_string_list_unref               (HudStringList *list);

Description

HudStringList is a refcounted list of strings.

Borrowing heavily on conventions of many functional programming languages, a list is a head element connected to a tail list (ie: the rest of the items).

A NULL pointer is considered to be a valid empty list.

Each list node is refcounted, and holds a reference on its 'tail' list. This allows common tails to be shared.

This mechanism is ideally suited to the HUD which is interested in displaying items of the form "File > New" and "File > Open". In this case, these items would be represented (in reverse) by the lists ['Open', 'File'] and ['New', 'File'] with the common tail portion shared between both items.

Each HudStringList node uses only one variable-sized block of memory. The reference count and pointer to the 'tail' are stored in a header, followed by the 'head' string data.

Details

HudStringList

typedef struct _HudStringList HudStringList;

This is an opaque structure type.


hud_string_list_cons ()

HudStringList *     hud_string_list_cons                (const gchar *head,
                                                         HudStringList *tail);

Create a new list with head as the first item and tail as the rest of the items.

A reference is taken on tail.

head :

a string for the head item

tail :

the tail HudStringList, possibly NULL. [allow-none]

Returns :

a new list. [transfer full]

hud_string_list_cons_label ()

HudStringList *     hud_string_list_cons_label          (const gchar *label,
                                                         HudStringList *tail);

Slight "magic" helper function for doing the right thing with prepending menu labels.

label is processed, removing mnemonic prefixes (ie: '_' characters) and then the function acts, essentially as hud_string_list_cons().

label :

a menuitem label. [allow-none]

tail :

the tail HudStringList, possibly NULL. [allow-none]

Returns :

a new HudStringList. [transfer full]

hud_string_list_get_head ()

const gchar *       hud_string_list_get_head            (HudStringList *list);

Gets the head string of the list.

list :

a non-empty (non-NULL) HudStringList

Returns :

the head element, as a normal C string

hud_string_list_get_tail ()

HudStringList *     hud_string_list_get_tail            (HudStringList *list);

Gets the tail of the list.

list :

a non-empty (non-NULL) HudStringList

Returns :

the tail of the list. [transfer none]

hud_string_list_pretty_print ()

gchar *             hud_string_list_pretty_print        (HudStringList *list);

Pretty-prints the list.

This function is intended only for debugging purposes.

list :

a HudStringList, possibly NULL. [allow-none]

Returns :

the pretty-printed list

hud_string_list_ref ()

HudStringList *     hud_string_list_ref                 (HudStringList *list);

Increases the reference count on list.

list :

a HudStringList, possibly NULL. [allow-none]

Returns :

a new reference to the list

hud_string_list_unref ()

void                hud_string_list_unref               (HudStringList *list);

Decreases the reference count on list, possibly freeing it.

list :

a HudStringList, possibly NULL. [allow-none]