## rb-util

rb-util — assorted utility functions

## Synopsis

    gboolean            rb_true_function                    (gpointer dummy);
    gboolean            rb_false_function                   (gpointer dummy);
    gpointer            rb_null_function                    (gpointer dummy);
    gpointer            rb_copy_function                    (gpointer data);
    int                 rb_gvalue_compare                   (GValue *a,
                                                             GValue *b);
    int                 rb_compare_gtimeval                 (GTimeVal *a,
                                                             GTimeVal *b);
    GtkWidget *         rb_image_new_from_stock             (const gchar *stock_id,
                                                             GtkIconSize size);
    void                rb_gtk_action_popup_menu            (GtkUIManager *uimanager,
                                                             const char *path);
    gboolean            rb_is_main_thread                   (void);
    void                rb_assert_locked                    (GMutex *mutex);
    void                rb_threads_init                     (void);
    gchar**             rb_string_split_words               (const gchar *string);
    gchar*              rb_search_fold                      (const char *original);
    char *              rb_make_duration_string             (guint duration);
    char *              rb_make_elapsed_time_string         (guint elapsed,
                                                             guint duration,
                                                             gboolean show_remaining);
    gboolean            rb_string_list_equal                (GList *a,
                                                             GList *b);
    GList*              rb_string_list_copy                 (GList *list);
    gboolean            rb_string_list_contains             (GList *list,
                                                             const char *s);
    void                rb_list_destroy_free                (GList *list,
                                                             GDestroyNotify destroyer);
    void                rb_list_deep_free                   (GList *list);
    void                rb_slist_deep_free                  (GSList *list);
    GList*              rb_collate_hash_table_keys          (GHashTable *table);
    GList*              rb_collate_hash_table_values        (GHashTable *table);
    GList*              rb_uri_list_parse                   (const char *uri_list);
    char*               rb_mime_get_friendly_name           (const char *mime_type);
    gboolean            rb_signal_accumulator_object_handled
                                                            (GSignalInvocationHint *hint,
                                                             GValue *return_accu,
                                                             const GValue *handler_return,
                                                             gpointer dummy);
    gboolean            rb_signal_accumulator_value_array   (GSignalInvocationHint *hint,
                                                             GValue *return_accu,
                                                             const GValue *handler_return,
                                                             gpointer dummy);
    void                rb_value_array_append_data          (GValueArray *array,
                                                             GType type,
                                                             ...);
    void                rb_value_free                       (GValue *val);
    gboolean            rb_str_in_strv                      (const char *needle,
                                                             char **haystack);
    void                rb_set_tree_view_column_fixed_width (GtkWidget *treeview,
                                                             GtkTreeViewColumn *column,
                                                             GtkCellRenderer *renderer,
                                                             const char **strings,
                                                             int padding);
    GdkPixbuf *         rb_scale_pixbuf_to_size             (GdkPixbuf *pixbuf,
                                                             GtkIconSize size);

## Description

This is a dumping ground for utility functions that may or may not be generally useful in Rhythmbox or elsewhere. Things end up here if they're clever or if they're used all over the place.

## Details

### rb_true_function ()

    gboolean            rb_true_function                    (gpointer dummy);

Just returns `TRUE`, useful as a callback function.

`dummy` : | unused
Returns : | `TRUE`

### rb_false_function ()

    gboolean            rb_false_function                   (gpointer dummy);

Just returns `FALSE`, useful as a callback function.

`dummy` : | unused
Returns : | `FALSE`

### rb_null_function ()

    gpointer            rb_null_function                    (gpointer dummy);

Just returns NULL. Useful as a callback function.

`dummy` : | unused
Returns : | NULL

### rb_copy_function ()

    gpointer            rb_copy_function                    (gpointer data);

Just returns its first argument. Useful as a callback function.

`data` : | generic argument
Returns : | `data`

### rb_gvalue_compare ()

    int                 rb_gvalue_compare                   (GValue *a,
                                                             GValue *b);

Compares `a` and `b` for sorting. `a` and `b` must contain the same value type for the comparison to be valid. Comparisons for some value types are not particularly useful.

`a` : | left hand side
`b` : | right hand size
Returns : | -1 if `a` < `b`, 0 if `a` == `b`, 1 if `a` > `b`

### rb_compare_gtimeval ()

    int                 rb_compare_gtimeval                 (GTimeVal *a,
                                                             GTimeVal *b);

Compares two GTimeval structures for sorting.

`a` : | left hand side
`b` : | right hand size
Returns : | -1 if `a` < `b`, 0 if `a` == `b`, 1 if `a` > `b`

### rb_image_new_from_stock ()

    GtkWidget *         rb_image_new_from_stock             (const gchar *stock_id,
                                                             GtkIconSize size);

Same as `gtk_image_new_from_stock` except that it mirrors the icons for RTL languages.

`stock_id` : | stock image id
`size` : | requested icon size
Returns : | a GtkImage of the requested stock item

### rb_gtk_action_popup_menu ()

    void                rb_gtk_action_popup_menu            (GtkUIManager *uimanager,
                                                             const char *path);

Simple shortcut for getting a popup menu from a GtkUIManager and displaying it.

`uimanager` : | a GtkUIManager
`path` : | UI path for the popup to display

### rb_is_main_thread ()

    gboolean            rb_is_main_thread                   (void);

Checks if currently executing on the main thread.

Returns : | `TRUE` if on the main thread

### rb_assert_locked ()

    void                rb_assert_locked                    (GMutex *mutex);

Asserts that `mutex` is currently locked. Does not work with all mutex implementations.

`mutex` : | a GMutex

### rb_threads_init ()

    void                rb_threads_init                     (void);

Initializes various thread helpers. Must be called on startup.

### rb_string_split_words ()

    gchar**             rb_string_split_words               (const gchar *string);

Splits `string` on word boundaries using Unicode character definitions.

`string` : | the string to split
Returns : | NULL-terminated array of strings, must be freed by caller (see `g_strfreev`)

### rb_search_fold ()

    gchar*              rb_search_fold                      (const char *original);

Returns a case-folded and punctuation-stripped version of `original`, useful for performing text searches.

`original` : | the string to fold
Returns : | case-folded string, must be freed by caller.

### rb_make_duration_string ()

    char *              rb_make_duration_string             (guint duration);

Constructs a string describing the specified duration. The string describes hours, minutes, and seconds, and its format is localised.

`duration` : | duration in seconds
Returns : | duration string, must be freed by caller.

### rb_make_elapsed_time_string ()

    char *              rb_make_elapsed_time_string         (guint elapsed,
                                                             guint duration,
                                                             gboolean show_remaining);

Constructs a string describing a playback position. The string describes hours, minutes, and seconds, and its format is localised. The string can describe either the elapsed time or the time remaining.

`elapsed` : | elapsed time (in seconds)
`duration` : | duration (in seconds)
`show_remaining` : | if `TRUE`, show the remaining time, otherwise show elapsed time
Returns : | elapsed/remaining time string, must be freed by caller

### rb_string_list_equal ()

    gboolean            rb_string_list_equal                (GList *a,
                                                             GList *b);

Checks if `a` and `b` contain exactly the same set of strings, regardless of order.

`a` : | list of strings to compare
`b` : | other list of strings to compare
Returns : | `TRUE` if the lists contain all the same strings

### rb_string_list_copy ()

    GList*              rb_string_list_copy                 (GList *list);

Creates a deep copy of `list`.

`list` : | list of strings to copy
Returns : | copied list, must be freed (and its contents freed) by caller

### rb_string_list_contains ()

    gboolean            rb_string_list_contains             (GList *list,
                                                             const char *s);

Checks if `list` contains the string `s`.

`list` : | list to check
`s` : | string to check for
Returns : | `TRUE` if found

### rb_list_destroy_free ()

    void                rb_list_destroy_free                (GList *list,
                                                             GDestroyNotify destroyer);

Calls `destroyer` for each element in `list`, then frees `list`.

`list` : | list to destroy
`destroyer` : | function to call to free elements of `list`

### rb_list_deep_free ()

    void                rb_list_deep_free                   (GList *list);

Frees each element of `list` and `list` itself.

`list` : | list to free

### rb_slist_deep_free ()

    void                rb_slist_deep_free                  (GSList *list);

Frees each element of `list` and `list` itself.

`list` : | list to free

### rb_collate_hash_table_keys ()

    GList*              rb_collate_hash_table_keys          (GHashTable *table);

Returns a GList containing all keys from `table`. The keys are not copied.

`table` : | GHashTable to collate
Returns : | GList of keys, must be freed by caller

### rb_collate_hash_table_values ()

    GList*              rb_collate_hash_table_values        (GHashTable *table);

Returns a GList containing all values from `table`. The values are not copied.

`table` : | GHashTable to collate
Returns : | GList of values, must be freed by caller

### rb_uri_list_parse ()

    GList*              rb_uri_list_parse                   (const char *uri_list);

Converts a single string containing a list of URIs into a GList of URI strings.

`uri_list` : | string containing URIs to parse
Returns : | GList of URI strings, must be deep-freed by caller

### rb_mime_get_friendly_name ()

    char*               rb_mime_get_friendly_name           (const char *mime_type);

Returns a human-friendly description of the MIME type `mime_type`.

`mime_type` : | a MIME type
Returns : | type description, must be freed by caller

### rb_signal_accumulator_object_handled ()

    gboolean            rb_signal_accumulator_object_handled
                                                            (GSignalInvocationHint *hint,
                                                             GValue *return_accu,
                                                             const GValue *handler_return,
                                                             gpointer dummy);

A GSignalAccumulator that aborts the signal emission after the first handler to return a value, and returns the value returned by that handler. This is the opposite behaviour from what you get when no accumulator is specified, where the last signal handler wins.

`hint` : | a GSignalInvocationHint
`return_accu` : | holds the accumulated return value
`handler_return` : | holds the return value to be accumulated
`dummy` : | user data (unused)
Returns : | `FALSE` to abort signal emission, `TRUE` to continue

### rb_signal_accumulator_value_array ()

    gboolean            rb_signal_accumulator_value_array   (GSignalInvocationHint *hint,
                                                             GValue *return_accu,
                                                             const GValue *handler_return,
                                                             gpointer dummy);

A GSignalAccumulator used to combine all returned values into a GValueArray.

`hint` : | a GSignalInvocationHint
`return_accu` : | holds the accumulated return value
`handler_return` : | holds the return value to be accumulated
`dummy` : | user data (unused)
Returns : | `FALSE` to abort signal emission, `TRUE` to continue

### rb_value_array_append_data ()

    void                rb_value_array_append_data          (GValueArray *array,
                                                             GType type,
                                                             ...);

Appends a single value to `array`, collecting it from `Varargs`.

`array` : | GValueArray to append to
`type` : | GType of the value being appended
`...` : | value to append

### rb_value_free ()

    void                rb_value_free                       (GValue *val);

Unsets and frees `val`. `val` must have been allocated using `g_slice_new` or `g_slice_new0`.

`val` : | a GValue

### rb_str_in_strv ()

    gboolean            rb_str_in_strv                      (const char *needle,
                                                             char **haystack);

Checks if `needle` is present in the NULL-terminated string array `haystack`.

`needle` : | string to search for
`haystack` : | array of strings to search
Returns : | `TRUE` if found

### rb_set_tree_view_column_fixed_width ()

    void                rb_set_tree_view_column_fixed_width (GtkWidget *treeview,
                                                             GtkTreeViewColumn *column,
                                                             GtkCellRenderer *renderer,
                                                             const char **strings,
                                                             int padding);

Sets a fixed size for a tree view column based on a set of strings to be displayed in the column.

`treeview` : | the GtkTreeView containing the column
`column` : | the GtkTreeViewColumn to size
`renderer` : | the GtkCellRenderer used in the column
`strings` : | a NULL-terminated set of strings to base the size on
`padding` : | a small amount of extra padding for the column

### rb_scale_pixbuf_to_size ()

    GdkPixbuf *         rb_scale_pixbuf_to_size             (GdkPixbuf *pixbuf,
                                                             GtkIconSize size);

Creates a new GdkPixbuf from the original one, for a target of size, respecting the aspect ratio of the image.

`pixbuf` : | the GdkPixbuf containing the original image
`size` : | a stock icon size
Returns : | scaled GdkPixbuf