array: add support for %NULL termination in GPtrArray

GArray supports a "zero_terminated" flag, but GPtrArray doesn't.
This is odd, because especially for a pointer array it makes sense
to have a %NULL sentinel. This would be for example useful to track
or construct a strv array with a GPtrArray.

As workaround for this missing feature you could use a GArray instead
(ugly) or to explicitly add the %NULL element. However the latter increases
the "len" of the array, which can be problematic if you want to still use
the GPtrArray for other purposes.

Add API for marking a GPtrArray as %NULL terminated. In that case, the
API will ensure that there is always a valid %NULL sentinel after the
array. Note that the API does not enforce that a %NULL terminated API
actually has any data allocated. That means, even with a %NULL terminated
array, pdata can still be %NULL (only if len is zero).

Add g_ptr_array_new_null_terminated() constructor. The null-terminated flag
cannot be cleared. Once the GPtrArray is flagged to be %NULL terminated, it
sticks. The purpose is that once a user checks whether a GPtrArray instance
is safe to be treated as a %NULL terminated array, the decision does
not need to be re-evaluated.

Also add a g_ptr_array_is_null_terminated(). That is useful because it
allows you to check whether a GPtrArray created by somebody else is safe
to use as a %NULL terminated array. Since there is no API to make an
array not %NULL terminated anymore, this is not error prone.

The new flag is tracked as a guint8 in GRealPtrArray. On common 64 bit
architectures this does not increase the size of the struct as it fits
in an existing hole. Note that this is not a bitfield because it's
probably more efficient to access the entire guint8. However, there is
still a 3 bytes hole (on common 32 and 64 architectures), so if we need
to add more flags in the future, we still have space for 24 bits,
despite the new flag not being a bitfield.

The biggest downside of the patch is the runtime overhead that most
operations now need to check whether %NULL termination is requested.

Includes some tweaks and additional tests by Philip Withnall.

https://gitlab.gnome.org/GNOME/glib/-/issues/353

docs/reference/glib/glib-sections.txt

@@ -3028,7 +3028,9 @@ g_ptr_array_sized_new
 g_ptr_array_new_with_free_func
 g_ptr_array_copy
 g_ptr_array_new_full
+g_ptr_array_new_null_terminated
 g_ptr_array_set_free_func
+g_ptr_array_is_null_terminated
 g_ptr_array_ref
 g_ptr_array_unref
 g_ptr_array_add