GLib 2.63.1 has been released. The final new API to mention in this mini-series of blog posts about what’s in 2.63.1 is g_get_os_info().

g_get_os_info() is a way to get identifying information about the OS. On Linux, this is gathered from /etc/os-release. On other OSs, it’s gathered using platform-specific APIs (on other Unixes, this means falling back to uname()).

It was written by Robert Ancell, with contributions from Ruslan Izhbulatov, Ting-Wei Lan and Simon McVittie; and it came out of proposals from Robert at GUADEC.

To use it, pass it a key, like G_OS_INFO_KEY_PRETTY_NAME, and it’ll return a newly-allocated string with the corresponding value for the current OS, or NULL if there was none. Different OSs support different sets of keys, and the amount of support and set of keys may change over time.

An example:

g_autofree gchar *os_name = g_get_os_info (G_OS_INFO_KEY_PRETTY_NAME);
g_print ("OS: %s\n", os_name);
/* Prints “OS: Fedora 30 (Workstation Edition)” for me */

tl;dr: GTimeVal and g_get_current_time() are not year-2038-safe and have been deprecated; use GDateTime and g_get_real_time() instead.

One of the latest changes in GLib (released in 2.61.2) is the deprecation of GTimeVal, g_get_current_time(), and a number of other time functions. This is because we can’t guarantee they’re wide enough on all platforms to be year-2038-safe.

Instead, you should use GDateTime or, if you just need to store epoch time, guint64. They are year-2038-safe — and with that, GLib should be entirely year-2038-safe.

GTimeVal is used in a number of places, and widespread (but simple) changes will need to be made to stop using it. You will likely have already seen some deprecation warnings popping up to inform you of this, if you use any C-based and GLib-based libraries.

If you can’t allocate time to fixing these deprecation warnings yet, you can silence them by explicitly stating your minimum and maximum supported versions of GLib. If your minimum supported version of GLib is older than 2.62, you won’t see deprecation warnings for GTimeVal (since it was deprecated in 2.62, and your code is claiming to need to support older GLib versions than that).

You can do that by setting the following in meson.build:

common_c_args = [
  '-DGLIB_VERSION_MIN_REQUIRED=GLIB_VERSION_2_44',
  '-DGLIB_VERSION_MAX_ALLOWED=GLIB_VERSION_2_60',
]

and then using common_c_args in the c_args field of every executable and library you define in Meson. Your minimum required GLib version should match the version you list in your dependency('glib-2.0').

So,

GTimeVal tv;
g_get_current_time (&tv);
g_message ("Current time: %lu", tv.tv_sec);

becomes

gint64 tv;
tv = g_get_real_time ();
g_message ("Current time: %" G_GINT64_FORMAT, tv / G_USEC_PER_SEC);

And

GTimeVal tv;
if (!g_time_val_from_iso8601 ("2019-08-24T10:47:05Z", &tv))
  g_error ("Conversion failed");

becomes

g_autoptr(GDateTime) dt = g_date_time_new_from_iso8601 ("2019-08-24T10:47:05Z", NULL);
if (dt == NULL)
  {
    g_error ("Conversion failed");
    return;
  }

gint64 time_val = g_date_time_to_unix (dt);
/* or (simpler) use the #GDateTime directly */

Finally

GTimeVal tv = some timeval;
g_autofree gchar *tv_in_iso8601 = g_time_val_to_iso8601 (&tv);
g_message ("In ISO 8601 format: %s", tv_in_iso8601);

becomes the following, using the new g_date_time_format_iso8601() function:

g_autoptr(GDateTime) dt = some GDateTime;
g_autofree gchar *dt_in_iso8601 = g_date_time_format_iso8601 (dt);
g_message ("In ISO 8601 format: %s", dt_in_iso8601);

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()).