GLib Helpers

The API in this file is designed to provide support functions that wrap the base glib functions and make them easier to use. More...

Files
file	gnc-glib-utils.h
	GLib helper routines.

Functions
gchar *	gnc_g_list_stringjoin (GList *list_of_strings, const gchar *sep)
	Return a string joining a GList whose elements are gchar* strings.
gchar *	gnc_g_list_stringjoin_nodups (GList *list_of_strings, const gchar *sep)
	Like stringjoin but ensures that the string to be added isn't already part of the return string.
gint	gnc_list_length_cmp (const GList *list, size_t len)
	Scans the GList elements the minimum number of iterations required to test it against a specified size.

GList Manipulation
typedef gpointer(*	GncGMapFunc) (gpointer data, gpointer user_data)
GList *	gnc_g_list_map (GList *list, GncGMapFunc fn, gpointer user_data)
void	gnc_g_list_cut (GList **list, GList *cut_point)
	Cut a GList into two parts; the cut_point is the beginning of the new list; list may need to be modified, but will be the list before the cut_point.

Character Sets
int	safe_utf8_collate (const char *str1, const char *str2)
	Collate two UTF-8 strings.
gboolean	gnc_utf8_validate (const gchar *str, gssize max_len, const gchar **end)
	Validates UTF-8 encoded text for use in GnuCash.
void	gnc_utf8_strip_invalid (gchar *str)
	Strip any non-UTF-8 characters from a string.
gchar *	gnc_utf8_strip_invalid_strdup (const gchar *str)
	Returns a newly allocated copy of the given string but with any non-UTF-8 character stripped from it.
void	gnc_utf8_strip_invalid_and_controls (gchar *str)
	Strip any non-utf8 characters and any control characters (everything < 0x20, , \f, , \r, \t, and \v) from a string.
gchar *	gnc_locale_from_utf8 (const gchar *str)
	Converts a string from UTF-8 to the encoding used for strings in the current locale.
gchar *	gnc_locale_to_utf8 (const gchar *str)
	Converts a string to UTF-8 from the encoding used for strings in the current locale.

Detailed Description

The API in this file is designed to provide support functions that wrap the base glib functions and make them easier to use.

Typedef Documentation

GncGMapFunc

typedef gpointer(* GncGMapFunc) (gpointer data, gpointer user_data)

Definition at line 156 of file gnc-glib-utils.h.

Function Documentation

gnc_g_list_cut()

void gnc_g_list_cut	(	GList **	list,
		GList *	cut_point
	)

Cut a GList into two parts; the cut_point is the beginning of the new list; list may need to be modified, but will be the list before the cut_point.

Definition at line 275 of file gnc-glib-utils.c.

{
    if (list == NULL || *list == NULL)
        return;
 
    // if it's the first element.
    if (cut_point->prev == NULL)
    {
        *list = NULL;
        return;
    }
 
    cut_point->prev->next = NULL;
    cut_point->prev = NULL;
}

gnc_g_list_map()

GList * gnc_g_list_map	(	GList *	list,
		GncGMapFunc	fn,
		gpointer	user_data
	)

Returns

Caller-owned GList* of results of apply fn to list in order.

Definition at line 264 of file gnc-glib-utils.c.

{
    GList *rtn = NULL;
    for (; list != NULL; list = list->next)
    {
        rtn = g_list_prepend (rtn, (*fn)(list->data, user_data));
    }
    return g_list_reverse (rtn);
}

gnc_g_list_stringjoin()

gchar * gnc_g_list_stringjoin	(	GList *	list_of_strings,
		const gchar *	sep
	)

Return a string joining a GList whose elements are gchar* strings.

Returns NULL if an empty GList* is passed through. The optional sep string will be used as separator. Must be g_freed when not needed anymore.

Parameters

list_of_strings	A GList of chars*
sep	a separator or NULL

Returns

A newly allocated string that has to be g_free'd by the caller.

Definition at line 345 of file gnc-glib-utils.c.

{
    return gnc_g_list_stringjoin_internal (list_of_strings, sep, false);
}

gnc_g_list_stringjoin_nodups()

gchar * gnc_g_list_stringjoin_nodups	(	GList *	list_of_strings,
		const gchar *	sep
	)

Like stringjoin but ensures that the string to be added isn't already part of the return string.

Parameters

list_of_strings	A GList of chars*
sep	a separator or NULL

Returns

A newly allocated string that has to be g_free'd by the caller.

Definition at line 351 of file gnc-glib-utils.c.

{
    return gnc_g_list_stringjoin_internal (list_of_strings, sep, true);
}

gnc_list_length_cmp()

gint gnc_list_length_cmp	(	const GList *	list,
		size_t	len
	)

Scans the GList elements the minimum number of iterations required to test it against a specified size.

Returns -1, 0 or 1 depending on whether the GList length has less, same, or more elements than the size specified.

Parameters

lst	A GList
len	the comparator length to compare the GList length with

Returns

A signed int comparing GList length with specified size.

Definition at line 357 of file gnc-glib-utils.c.

{
    for (GList *lst = (GList*) list;; lst = g_list_next (lst), len--)
    {
        if (!lst) return (len ? -1 : 0);
        if (!len) return 1;
    }
}

gnc_locale_from_utf8()

gchar * gnc_locale_from_utf8

(

const gchar *

str

)

Converts a string from UTF-8 to the encoding used for strings in the current locale.

This essentially is a wrapper for g_locale_from_utf8 that can be swigified for use with Scheme to avoid adding a dependency for guile-glib.

Parameters

str	A pointer to a UTF-8 encoded string to be converted.

Returns

A newly allocated string that has to be g_free'd by the caller. If an error occurs, NULL is returned.

Definition at line 228 of file gnc-glib-utils.c.

{
    gchar *   locale_str;
    gsize     bytes_written = 0;
    GError *  err = NULL;
 
    /* Convert from UTF-8 to the encoding used in the current locale. */
    locale_str = g_locale_from_utf8(str, -1, NULL, &bytes_written, &err);
    if (err)
    {
        g_warning("g_locale_from_utf8 failed: %s", err->message);
        g_error_free(err);
    }
 
    return locale_str;
}

gnc_locale_to_utf8()

gchar * gnc_locale_to_utf8

(

const gchar *

str

)

Converts a string to UTF-8 from the encoding used for strings in the current locale.

This essentially is a wrapper for g_locale_to_utf8 that can be swigified for use with Scheme to avoid adding a dependency for guile-glib.

Parameters

str	A pointer to a string encoded according to locale.

Returns

A newly allocated string that has to be g_free'd by the caller. If an error occurs, NULL is returned.

Definition at line 246 of file gnc-glib-utils.c.

{
    gchar *   utf8_str;
    gsize     bytes_written = 0;
    GError *  err = NULL;
 
    /* Convert to UTF-8 from the encoding used in the current locale. */
    utf8_str = g_locale_to_utf8(str, -1, NULL, &bytes_written, &err);
    if (err)
    {
        g_warning("g_locale_to_utf8 failed: %s", err->message);
        g_error_free(err);
    }
 
    return utf8_str;
}

gnc_utf8_strip_invalid()

void gnc_utf8_strip_invalid

(

gchar *

str

)

Strip any non-UTF-8 characters from a string.

This function rewrites the string "in place" instead of allocating and returning a new string. This allows it to operate on strings that are defined as character arrays in a larger data structure. Note that it also removes some subset of invalid XML characters, too. See https://www.w3.org/TR/REC-xml/#NT-Char linked from bug #346535

Parameters

str	A pointer to the string to strip of invalid characters.

Definition at line 185 of file gnc-glib-utils.c.

{
    gchar *end;
    gint len;
 
    g_return_if_fail(str);
 
    if (gnc_utf8_validate(str, -1, (const gchar **)&end))
        return;
 
    g_warning("Invalid utf8 string: %s", str);
    do
    {
        len = strlen(end);
        memmove(end, end + 1, len); /* shuffle the remainder one byte */
    }
    while (!gnc_utf8_validate(str, -1, (const gchar **)&end));
}

gnc_utf8_strip_invalid_and_controls()

void gnc_utf8_strip_invalid_and_controls

(

gchar *

str

)

Strip any non-utf8 characters and any control characters (everything < 0x20, , \f,
, \r, \t, and \v) from a string.

Rewrites the string in-place.

Parameters

str	Pointer to the string to clean up.

Definition at line 213 of file gnc-glib-utils.c.

{
    gchar *c = NULL;
    const gchar *controls = "\b\f\n\r\t\v";
    g_return_if_fail (str != NULL && strlen (str) > 0);
    gnc_utf8_strip_invalid (str); /* First fix the UTF-8 */
    for(c = str + strlen (str) - 1; c != str; --c)
    {
        gboolean line_control = ((unsigned char)(*c) < 0x20);
        if (line_control || strchr(controls, *c) != NULL)
            *c = ' '; /*replace controls with a single space. */
    }
}

gnc_utf8_strip_invalid_strdup()

gchar * gnc_utf8_strip_invalid_strdup

(

const gchar *

str

)

Returns a newly allocated copy of the given string but with any non-UTF-8 character stripped from it.

Note that it also removes some subset of invalid XML characters, too. See https://www.w3.org/TR/REC-xml/#NT-Char linked from bug #346535

Parameters

str	A pointer to the string to be copied and stripped of non-UTF-8 characters.

Returns

A newly allocated string that has to be g_free'd by the caller.

Definition at line 205 of file gnc-glib-utils.c.

{
    gchar *result = g_strdup (str);
    gnc_utf8_strip_invalid (result);
    return result;
}

gnc_utf8_validate()

gboolean gnc_utf8_validate	(	const gchar *	str,
		gssize	max_len,
		const gchar **	end
	)

Validates UTF-8 encoded text for use in GnuCash.

Validates the strict subset of UTF-8 that is valid XML text, as detailed in https://www.w3.org/TR/REC-xml/#NT-Char linked from bug #346535.

Copied from g_utf8_validate():

Validates UTF-8 encoded text, where str is the text to validate; if str is nul-terminated, then max_len can be -1, otherwise max_len should be the number of bytes to validate. If end is non-NULL, then the end of the valid range will be stored there (i.e. the start of the first invalid character if some bytes were invalid, or the end of the text being validated otherwise).

Returns TRUE if all of str was valid. Many GLib and GTK+ routines require valid UTF-8 as input; so data read from a file or the network should be checked with g_utf8_validate() before doing anything else with it.

Parameters

str	a pointer to character data
max_len	max bytes to validate, or -1 to go until NUL
end	return location for end of valid data

Returns

TRUE if the text was valid UTF-8.

Definition at line 124 of file gnc-glib-utils.c.

{
 
    const gchar *p;
 
    g_return_val_if_fail (str != NULL, FALSE);
 
    if (end)
        *end = str;
 
    p = str;
 
    while ((max_len < 0 || (p - str) < max_len) && *p)
    {
        int i, mask = 0, len;
        gunichar result;
        unsigned char c = (unsigned char) * p;
 
        UTF8_COMPUTE (c, mask, len);
 
        if (len == -1)
            break;
 
        /* check that the expected number of bytes exists in str */
        if (max_len >= 0 &&
                ((max_len - (p - str)) < len))
            break;
 
        UTF8_GET (result, p, i, mask, len);
 
        if (UTF8_LENGTH (result) != len) /* Check for overlong UTF-8 */
            break;
 
        if (result == (gunichar) - 1)
            break;
 
        if (!UNICODE_VALID (result))
            break;
 
        p += len;
    }
 
    if (end)
        *end = p;
 
    /* See that we covered the entire length if a length was
     * passed in, or that we ended on a nul if not
     */
    if (max_len >= 0 &&
            p != (str + max_len))
        return FALSE;
    else if (max_len < 0 &&
             *p != '\0')
        return FALSE;
    else
        return TRUE;
}

safe_utf8_collate()

int safe_utf8_collate	(	const char *	str1,
		const char *	str2
	)

Collate two UTF-8 strings.

This function performs basic argument checking before calling g_utf8_collate.

Parameters

str1	The first string.
str2	The first string.

Returns

Same return value as g_utf8_collate. The values are: < 0 if str1 compares before str2, 0 if they compare equal, > 0 if str1 compares after str2.

Definition at line 38 of file gnc-glib-utils.c.

{
    if (da && !(*da))
        da = NULL;
    if (db && !(*db))
        db = NULL;
 
    if (da && db)
        return g_utf8_collate(da, db);
    if (da)
        return 1;
    if (db)
        return -1;
    return 0;
}