GLib extras: GOffice Reference Manual

## GLib extras GLib extras |

## Functions

gpointer | (*GOMapFunc) ()
gboolean | (*GOParseKeyValueFunc) ()
#define | GO_LIST_APPEND()
#define | GO_LIST_CONCAT()
#define | GO_LIST_FOREACH()
#define | GO_LIST_PREPEND()
#define | GO_LIST_REMOVE()
#define | GO_LIST_REVERSE()
#define | GO_LIST_SORT()
#define | GO_SLIST_APPEND()
#define | GO_SLIST_CONCAT()
#define | GO_SLIST_FOREACH()
#define | GO_SLIST_PREPEND()
#define | GO_SLIST_REMOVE()
#define | GO_SLIST_REVERSE()
#define | GO_SLIST_SORT()
gint | go_ascii_strcase_equal ()
guint | go_ascii_strcase_hash ()
void | go_debug_check_finalized ()
gboolean | go_debug_flag ()
void | go_destroy_password ()
char const * | go_get_real_name ()
char const * | go_guess_encoding ()
GSList * | go_hash_keys ()
gint | go_list_index_custom ()
gpointer | go_mem_chunk_alloc ()
gpointer | go_mem_chunk_alloc0 ()
void | go_mem_chunk_destroy ()
void | go_mem_chunk_foreach_leak ()
void | go_mem_chunk_free ()
GOMemChunk * | go_mem_chunk_new ()
gpointer | go_memdup ()
gpointer | go_memdup_n ()
void | go_object_properties_apply ()
GSList * | go_object_properties_collect ()
void | go_object_properties_free ()
gboolean | go_object_set_property ()
void | go_object_toggle ()
gboolean | go_parse_key_value ()
void | go_ptr_array_insert ()
GSList * | go_slist_create ()
GSList * | go_slist_map ()
int | go_str_compare ()
void | go_strescape ()
void | go_string_append_c_n ()
void | go_string_append_gstring ()
void | go_string_replace ()
#define | go_string_slist_copy()
GSList * | go_strsplit_to_slist ()
char const * | go_strunescape ()
int | go_unichar_issign ()
gint | go_utf8_collate_casefold ()
char * | go_utf8_strcapital ()

## Types and Values

| GOMemChunk

## Object Hierarchy

        GBoxed
        ╰── GOMemChunk

## Description

## Functions

### GOMapFunc ()

    gpointer
    (*GOMapFunc) (gpointer value);

`GOMapFunc` is deprecated and should not be used in newly-written code.

### GOParseKeyValueFunc ()

    gboolean
    (*GOParseKeyValueFunc) (const char *name,
                            const char *value,
                            GError **err,
                            gpointer user);

### GO_LIST_APPEND()

    #define             GO_LIST_APPEND(list,item)

### GO_LIST_CONCAT()

    #define             GO_LIST_CONCAT(list_a,list_b)

### GO_LIST_FOREACH()

    #define             GO_LIST_FOREACH(list,valtype,val,stmnt)

### GO_LIST_PREPEND()

    #define             GO_LIST_PREPEND(list,item)

### GO_LIST_REMOVE()

    #define             GO_LIST_REMOVE(list,item)

### GO_LIST_REVERSE()

    #define             GO_LIST_REVERSE(list)

### GO_LIST_SORT()

    #define             GO_LIST_SORT(list,cmp_func)

### GO_SLIST_APPEND()

    #define             GO_SLIST_APPEND(list,item)

### GO_SLIST_CONCAT()

    #define             GO_SLIST_CONCAT(list_a,list_b)

### GO_SLIST_FOREACH()

    #define             GO_SLIST_FOREACH(list,valtype,val,stmnt)

### GO_SLIST_PREPEND()

    #define             GO_SLIST_PREPEND(list,item)

### GO_SLIST_REMOVE()

    #define             GO_SLIST_REMOVE(list,item)

### GO_SLIST_REVERSE()

    #define             GO_SLIST_REVERSE(list)

### GO_SLIST_SORT()

    #define             GO_SLIST_SORT(list,cmp_func)

### go_ascii_strcase_equal ()

    gint
    go_ascii_strcase_equal (gconstpointer v1,
                            gconstpointer v2);

Compares two ASCII strings for equality, ignoring case.

#### Parameters

v1 | first string. | [type utf8]
v2 | second string. | [type utf8]

#### Returns

`TRUE` if the strings are equal.

### go_ascii_strcase_hash ()

    guint
    go_ascii_strcase_hash (gconstpointer v);

a char* hash function from ASU.

#### Parameters

v | the string to hash. | [type utf8]

#### Returns

the hash value.

### go_debug_check_finalized ()

    void
    go_debug_check_finalized (gpointer obj,
                              const char *id);

Registers `obj` to be checked for finalization at shutdown.

#### Parameters

obj | GObject |
id | identifier for `obj` |

### go_debug_flag ()

    gboolean
    go_debug_flag (const char *flag);

#### Parameters

flag | the flag to check |

#### Returns

`TRUE` if the GO_DEBUG environment variable contains `flag` .

### go_destroy_password ()

    void
    go_destroy_password (char *passwd);

Overwrite a string holding a password. This is a separate routine to ensure that the compiler does not try to outsmart us.

Note: this does not free the memory.

#### Parameters

passwd | The buffer to clear. | [transfer none]

### go_get_real_name ()

    char const *
    go_get_real_name (void);

#### Returns

a UTF-8 encoded string with the current user name.

[transfer none]

### go_guess_encoding ()

    char const *
    go_guess_encoding (char const *raw,
                       gsize len,
                       char const *user_guess,
                       GString **utf8_str,
                       guint *truncated);

Guesses the encoding of `raw` and converts it to UTF-8.

#### Parameters

raw | raw data |
len | length of `raw` |
user_guess | encoding to try first. | [nullable]
utf8_str | location to store the UTF-8 string. | [out][optional][nullable]
truncated | location to store the number of bytes that could not be converted. | [out][optional][nullable]

#### Returns

the name of the guessed encoding.

[transfer none][nullable]

### go_hash_keys ()

    GSList *
    go_hash_keys (GHashTable *hash);

Collects an unordered list of the keys in `hash` .

#### Parameters

hash | GHashTable |

#### Returns

a list of all keys in the hash.

Note: consider using g_hash_table_get_keys instead.

[element-type void][transfer container]

### go_list_index_custom ()

    gint
    go_list_index_custom (GList *list,
                          gpointer data,
                          GCompareFunc cmp_func);

Searched for `data` in `list` and return the corresponding index or -1 if not found.

#### Parameters

list | GList. | [element-type void]
data | element for which the index is searched for |
cmp_func | GCompareFunc. | [scope call]

#### Returns

the data index in the list.

### go_mem_chunk_alloc ()

    gpointer
    go_mem_chunk_alloc (GOMemChunk *chunk);

#### Parameters

chunk | GOMemChunk |

#### Returns

an unused memory block.

[transfer full]

### go_mem_chunk_alloc0 ()

    gpointer
    go_mem_chunk_alloc0 (GOMemChunk *chunk);

#### Parameters

chunk | GOMemChunk |

#### Returns

an unused memory block filled with 0.

[transfer full]

### go_mem_chunk_destroy ()

    void
    go_mem_chunk_destroy (GOMemChunk *chunk,
                          gboolean expect_leaks);

Destroys `chunk` .

#### Parameters

chunk | GOMemChunk. | [transfer full]
expect_leaks | whether to expect leaks |

### go_mem_chunk_foreach_leak ()

    void
    go_mem_chunk_foreach_leak (GOMemChunk *chunk,
                               GFunc cb,
                               gpointer user);

Loop over all non-freed memory in the chunk. It's safe to allocate or free from the chunk in the callback.

#### Parameters

chunk | GOMemChunk |
cb | callback. | [scope call]
user | user data for `cb` |

### go_mem_chunk_free ()

    void
    go_mem_chunk_free (GOMemChunk *chunk,
                       gpointer mem);

Frees, ie., returns the given item to the pool.

#### Parameters

chunk | GOMemChunk |
mem | item to release. | [transfer full]

### go_mem_chunk_new ()

    GOMemChunk *
    go_mem_chunk_new (char const *name,
                      gsize user_atom_size,
                      gsize chunk_size);

#### Parameters

name | name of the chunk |
user_atom_size | size of each atom |
chunk_size | size of each chunk |

#### Returns

a new GOMemChunk.

[transfer full]

### go_memdup ()

    gpointer
    go_memdup (gconstpointer mem,
               gsize byte_size);

Like g_memdup or g_memdup2. This function is meant to ease transition to g_memdup2 without having to require very new glib.

#### Parameters

mem | Memory to copy. | [nullable]
byte_size | size of memory block to copy |

### go_memdup_n ()

    gpointer
    go_memdup_n (gconstpointer mem,
                 gsize n_blocks,
                 gsize block_size);

Like go_memdup (`mem` , `n_blocks` * `block_size` ), but with overflow check. Like a potential future g_memdup_n.

#### Parameters

mem | Memory to copy. | [nullable]
n_blocks | Number of blocks to copy. |
block_size | Number of bytes per blocks. |

### go_object_properties_apply ()

    void
    go_object_properties_apply (GObject *obj,
                                GSList *props,
                                gboolean changed_only);

Sets a list of properties for `obj` . The list needs to be a list of alternating GParamSpec and GValue.

#### Parameters

obj | GObject |
props | the list of properties and their values to apply. | [element-type void]
changed_only | whether to restrict calls to `g_object_set_property()` to properties with changed values. |

### go_object_properties_collect ()

    GSList *
    go_object_properties_collect (GObject *obj);

Collect all rw properties and their values.

#### Parameters

obj | GObject |

#### Returns

the list of collected properties as GParamSpec and values as GValue.

[element-type void][transfer container]

### go_object_properties_free ()

    void
    go_object_properties_free (GSList *props);

Unsets the values in the list which needs to be a list of alternating GParamSpec and GValue.

#### Parameters

props | the list of properties and their values to unset. | [element-type void]

### go_object_set_property ()

    gboolean
    go_object_set_property (GObject *obj,
                            const char *property_name,
                            const char *user_prop_name,
                            const char *value,
                            GError **err,
                            const char *error_template);

Sets a property of an object from a string.

#### Parameters

obj | GObject |
property_name | property name to set |
user_prop_name | name of the property to show in error message |
value | value to set |
err | location to store a GError. | [out][optional][nullable]
error_template | error message template |

#### Returns

`TRUE` on failure.

### go_object_toggle ()

    void
    go_object_toggle (gpointer object,
                      const gchar *property_name);

Toggle a boolean object property.

#### Parameters

object | GObject |
property_name | name |

### go_parse_key_value ()

    gboolean
    go_parse_key_value (const char *options,
                        GError **err,
                        GOParseKeyValueFunc handler,
                        gpointer user);

#### Parameters

options | Options string. |
err | Error return if parsing fails. | [out][optional][nullable]
handler | Handler to call for each key-value pair. | [scope call]
user | user pointer. |

### go_ptr_array_insert ()

    void
    go_ptr_array_insert (GPtrArray *array,
                         gpointer value,
                         int index);

`go_ptr_array_insert` is deprecated and should not be used in newly-written code.

Inserts a pointer inside an existing array.

Note: consider using g_ptr_array_insert instead, but watch out of the argument order.

#### Parameters

array | a GPtrArray. | [element-type void]
value | the pointer to insert |
index | where to insert `value` |

### go_slist_create ()

    GSList *
    go_slist_create (gconstpointer item1,
                     ...);

Creates a GList from NULL-terminated list of arguments. As the arguments are just copied to the list, the caller owns them.

#### Parameters

item1 | first item. | [allow-none][transfer none]
... | `NULL` terminated list of additional items. | [transfer none]

#### Returns

created list.

[element-type void][transfer container]

### go_slist_map ()

    GSList *
    go_slist_map (GSList const *list,
                  GOMapFunc map_func);

`go_slist_map` is deprecated and should not be used in newly-written code.

The ownership of the list elements depends on map_func.

#### Parameters

list | list of some items. | [element-type void]
map_func | mapping function. | [scope call]

#### Returns

the mapped list

Note: consider using g_slist_copy_deep instead.

[element-type void][transfer container]

### go_str_compare ()

    int
    go_str_compare (void const *x,
                    void const *y);

#### Parameters

x | first string. | [nullable]
y | second string. | [nullable]

#### Returns

< 0 if `x` < `y` , 0 if `x` == `y` , > 0 if `x` > `y` .

### go_strescape ()

    void
    go_strescape (GString *target,
                  char const *str);

Escapes all backslashes and quotes in a string. It is based on glib's g_strescape.

Also adds quotes around the result.

#### Parameters

target | GString. | [inout]
str | a string to escape |

### go_string_append_c_n ()

    void
    go_string_append_c_n (GString *target,
                          char c,
                          gsize n);

Appends `c` to `target` `n` times.

#### Parameters

target | GString. | [inout]
c | the character to append |
n | number of times to append `c` |

### go_string_append_gstring ()

    void
    go_string_append_gstring (GString *target,
                              const GString *src);

Appends `source` to `target` .

#### Parameters

target | GString. | [inout]
src | GString. | [in]

### go_string_replace ()

    void
    go_string_replace (GString *target,
                       gsize pos,
                       gssize oldlen,
                       const char *txt,
                       gssize newlen);

Replaces `oldlen` characters at `pos` with `newlen` characters from `txt` .

#### Parameters

target | GString. | [inout]
pos | position |
oldlen | length of text to be replaced |
txt | text to insert |
newlen | length of `txt` |

### go_string_slist_copy()

    #define	 go_string_slist_copy(list) g_slist_copy_deep (list, (GCopyFunc)g_strdup, NULL)

### go_strsplit_to_slist ()

    GSList *
    go_strsplit_to_slist (char const *str,
                          gchar delimiter);

Splits up string into tokens at delim and returns a string list.

#### Parameters

str | String to split |
delimiter | Token delimiter |

#### Returns

string list.

[element-type utf8][transfer full]

### go_strunescape ()

    char const *
    go_strunescape (GString *target,
                    char const *str);

The reverse operation of go_strescape. Returns a pointer to the first char after the string on success or `NULL` on failure.

First character of the string should be an ASCII character used for quoting.

#### Parameters

target | GString. | [inout]
str | the string to unescape |

#### Returns

a pointer to the first char after the string.

[transfer none][nullable]

### go_unichar_issign ()

    int
    go_unichar_issign (gunichar uc);

#### Parameters

uc | gunichar |

#### Returns

+1 if `uc` is a plus sign, -1 if `uc` is a minus sign, 0 otherwise.

### go_utf8_collate_casefold ()

    gint
    go_utf8_collate_casefold (char const *a,
                              char const *b);

Compares two UTF-8 strings for collation, ignoring case.

#### Parameters

a | a UTF-8 string |
b | a UTF-8 string |

#### Returns

< 0 if `a` < `b` , 0 if `a` == `b` , > 0 if `a` > `b` .

### go_utf8_strcapital ()

    char *
    go_utf8_strcapital (char const *p,
                        gssize len);

Similar to g_utf8_strup and g_utf8_strup, except that this function creates a string "Very Much Like: This, One".

#### Parameters

p | string |
len | length in bytes, or -1. |

#### Returns

capitalized string.

[transfer full]

## Types and Values

### GOMemChunk

    typedef struct _GOMemChunk GOMemChunk;