GLib Helpers
[GLib]

---

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.

Files
file	gnc-glib-utils.h
	GLib helper routines.
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)
Character Sets
int	safe_utf8_collate (const char *str1, const char *str2)
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)
gchar *	gnc_utf8_strip_invalid_strdup (const gchar *str)
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.
Message Logging
void	gnc_scm_log_warn (const gchar *msg)
void	gnc_scm_log_error (const gchar *msg)
void	gnc_scm_log_msg (const gchar *msg)
void	gnc_scm_log_debug (const gchar *msg)
glib Miscellaneous Functions
void	gnc_gpid_kill (GPid pid)

---

Function Documentation

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 253 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;
}

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 242 of file gnc-glib-utils.c.

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

void gnc_gpid_kill

(

GPid

pid

)

Kill a process. On UNIX send a SIGKILL, on Windows call TerminateProcess.

Parameters:

pid

The process ID.

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

{
#ifdef G_OS_WIN32
    if (!TerminateProcess((HANDLE) pid, 0)) {
        gchar *msg = g_win32_error_message(GetLastError());
        g_warning("Could not kill child process: %s", msg ? msg : "(null)");
        g_free(msg);
    }
#else /* !G_OS_WIN32 */
    if (kill(pid, SIGKILL)) {
        g_warning("Could not kill child process: %s", g_strerror(errno));
    }
#endif /* G_OS_WIN32 */
}

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 208 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;
}

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 225 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;
}

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 http://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 184 of file gnc-glib-utils.c.

{
  gchar *end;
  gint len;

  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));
}

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 http://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 200 of file gnc-glib-utils.c.

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

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 http://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 123 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;
}

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 37 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;
}

---