The final API so far in this mini-series on new APIs in the GLib 2.62 series is g_array_binary_search(), put together by Emmanuel Fleury and based on code by Christian Hergert. It’s due to be released in 2.61.2 soon. But first, a reminder about GLib version numbering.

Like the rest of GNOME’s official module set, GLib follows an odd/even versioning scheme, where every odd minor version number, like 2.61.x, is an unstable release building up to an even minor version number, like 2.62.x, which is stable. APIs may be added in unstable releases. They may be modified or even removed (if they haven’t been in a stable release yet). So all of the APIs I’ve blogged about recently still have a chance to be tweaked or dropped if people find problems with them. So if you see a problem or think that one of these APIs would be awkward to use in some way, please say, sooner rather than later! They need fixing before they’re in a stable release.

Back to today’s API, g_array_binary_search(). As its name suggests, this does a binary search on an array (which it requires is already sorted). You can use it like this:

static gint
compare_guint64 (gconstpointer a,
                 gconstpointer b)
{
  guint64 uint64_a = *((guint64 *) a);
  guint64 uint64_b = *((guint64 *) b);

  if (uint64_a < uint64_b)
    return -1;
  else if (uint64_a > uint64_b)
    return 1;
  else
    return 0;
}

g_autoptr(GArray) my_array = g_array_new (FALSE, TRUE, sizeof (guint64));

for (guint i = 0; i < 100; i++)
  {
    guint64 random_uint64 = ( (guint64) g_random_int () << 32) | g_random_int ();
    g_array_append_val (my_array, random_uint64);
  }

g_array_sort (my_array, compare_guint64);

/* Is ‘1234’ in the array? If so, where? */
const guint64 search_uint64 = 1234;
guint search_index;
if (g_array_binary_search (my_array, &amp;search_uint64, compare_guint64, &amp;search_index))
  g_message ("Found ‘1234’ at index %u", search_index);
else
  g_message ("Didn’t find ‘1234’");

As all computer science algorithms courses will tell you, a binary search is faster than a linear search, so you should use this in preference to iterating over an array to find an element in it, where possible.

(That’s not entirely true: the overheads of accounting for the binary search bounds, and the slowness of scattered memory loads from the array in a binary search vs sequential access in a linear search, will probably make it slower than a linear search for small arrays. But both will be fast, and if you need to care about that level of performance, you should be using a custom data structure rather than GArray.)

A slightly more in-depth post in the mini-series this time, about various new functions which Emmanuel Fleury has landed in GLib 2.61.2 (which is due to be released soon), based on some old but not-quite-finished patches from others.

There’s g_ptr_array_copy() and g_array_copy(); and also g_ptr_array_extend() and g_ptr_array_extend_and_steal().

g_ptr_array_copy() and g_array_copy() are obvious functions and it’s not clear why they haven’t been added before. They allow you to copy a GPtrArray or a GArray, including its contents.
When copying a GPtrArray, you pass in a GCopyFunc to copy each element (for example, by increasing its reference count). If the GCopyFunc is NULL, the element is copied by value.

For example,

g_autoptr(GPtrArray) object_array = g_ptr_array_new_with_free_func (g_object_unref);

for (gsize i = 0; i < 10; i++)
  g_ptr_array_add (object_array, create_new_object (i));

object_array_copy = g_ptr_array_copy (object_array, g_object_ref, NULL);
/* object_array and object_array_copy now contain copies of the same elements, but
 * modifying one array will not modify the other */

The g_ptr_array_extend() functions are used to join one array onto the end of another. This means you can turn the following code to join the GObject elements of array2 onto the end of array1 and ref them all:

for (gsize i = 0; i < array2->len; i++)
  g_ptr_array_add (array1, g_object_ref (g_ptr_array_index (array2, i)));

into

g_ptr_array_extend (array1, array2, g_object_ref, NULL);

If you no longer need array2, you can go further and use g_ptr_array_extend_and_steal() to avoid copying each element. This might be particularly beneficial when using string arrays, where each copy (a g_strdup()) is more expensive. So the following code:

g_autoptr(GPtrArray) array1 = g_ptr_array_new_with_free_func (g_free);
for (guint i = 0; i < 10; i++)
  g_ptr_array_add (array1, g_strdup_printf ("array1 %u", i));

g_autoptr(GPtrArray) array2 = g_ptr_array_new_with_free_func (g_free);
for (guint i = 100; i < 110; i++)
  g_ptr_array_add (array2, g_strdup_printf ("array2 %u", i));

for (gsize i = 0; i < array2->len; i++)
  g_ptr_array_add (array1, g_strdup (g_ptr_array_index (array2, i)));

would become:

g_autoptr(GPtrArray) array1 = g_ptr_array_new_with_free_func (g_free);
for (guint i = 0; i < 10; i++)
  g_ptr_array_add (array1, g_strdup_printf ("array1 %u", i));

g_autoptr(GPtrArray) array2 = g_ptr_array_new_with_free_func (g_free);
for (guint i = 100; i < 110; i++)
  g_ptr_array_add (array2, g_strdup_printf ("array2 %u", i));

g_ptr_array_extend_and_steal (array1, g_steal_pointer (&amp;array2));
/* array2 has now been destroyed */

Another short post about new APIs, this time from the upcoming 2.61.2 release. This time it’s two unrelated new APIs, which I’m covering together because they’re fairly short.

g_test_summary() is a new API along the same lines as the existing g_test_bug() function. It’s to be called from within a unit test to provide a summary of the test to the test harness. In contrast, g_test_bug() provides a bug reference for the unit test. In this fashion, the two can be used to provide documentation within the test code of what the test is testing, how it goes about testing it, and which bug it’s checking for regressions in. The summary passed to g_test_summary() might be printed out as a comment in the test logs.

The summary passed to g_test_summary() should contain a brief overview of what the test does, and should note any particularly non-obvious things about how the test is implemented.

For example:

g_test_summary ("Test g_queue_push_nth_link() with various combinations of position (before, "
                "in the middle of, or at the end of the queue) and various existing queues "
                "(empty, single element, multiple elements).");

or:

g_test_summary ("Ensure that we successfully return IPv4 results even when they come significantly later than an IPv6 failure.");

The second API, g_get_console_charset(), is more useful only on Windows. On Linux, it returns the same value as g_get_charset(). On Windows, its result may differ if the console the current process is attached to has a different character encoding from that of the current locale. In those situations, g_get_console_charset() will return something which should result in correct character decoding by the console. If the process is not attached to a console, it returns UTF-8.

When should you care? Use g_get_console_charset() whenever you need to work out the character encoding for printing to the console (stdout or stderr), even on Linux (if you want your code to be portable). Use g_get_charset() whenever you need the character encoding for other strings related to the system locale, such as dates or file names. GLib correctly uses the two functions internally so that you should generally never have to care (for example, you don’t need to care when you use g_log(), g_date_time_format() or g_filename_to_utf8()).

The second post in a little mini-series on new APIs in the GLib 2.62 series, this one’s about Christian Hergert’s g_queue_insert_before_link().

This is a new helper function for inserting elements at arbitrary positions in a queue, without needing to allocate a new container element for them. Previously, using g_queue_insert_before(), a new GList container would have been allocated. The new function means that elements can be moved from one position in a queue to another, without any allocations; and statically allocated GList elements can be used in a GQueue correctly.

The new function comes with friends, too: g_queue_insert_after_link() and g_list_insert_before_link(). They behave similarly.

One example of using the new function would be to bump the priority of an element in the middle of a queue:

GList *element_to_bump = g_queue_find (queue, important_data);
GList *old_sibling = element_to_bump->prev;
if (old_sibling != NULL)
  {
    g_queue_unlink (queue, element_to_bump);
    g_queue_insert_before_link (queue, old_sibling, element_to_bump);
  }
else
  {
    g_debug ("Already at the head of the queue");
  }

Christian is using it in GNOME Builder to arrange embedded structures in a queue using embedded GList instances, kernel-style.

It’s been a long time since I’ve blogged, so I thought I’d do a quick series on new APIs in the upcoming 2.62 release series of GLib.

Today, it’s the g_clear_signal_handler() function added by Marco Trevisan. This is a simple helper function along the same lines as g_clear_pointer(), g_clear_error() and g_clear_handle_id(). Given a GObject and a signal handler ID, it disconnects the signal handler and clears the signal handler ID variable to zero.

This turns the following standard pattern of code:

if (obj != NULL && handler_id != 0)
  {
    g_signal_handler_disconnect (obj, handler_id);
    handler_id = 0;
  }

to this:

g_clear_signal_handler (&handler_id, obj);

Nothing earth-shattering, but it does allow code to become a little more compact.