/*
 * This file is part of gtkD.
 *
 * gtkD is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 3
 * of the License, or (at your option) any later version, with
 * some exceptions, please read the COPYING file.
 *
 * gtkD is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with gtkD; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
 */

// generated automatically - do not change
// find conversion definition on APILookup.txt
// implement new conversion functionalities the gir-to-d pakage


module glib.PtrArray;

private import glib.ConstructionException;
private import glib.c.functions;
public  import glib.c.types;


/**
 * Contains the public fields of a `GPtrArray`.
 */
public class PtrArray
{
	/** the main Gtk struct */
	protected GPtrArray* gPtrArray;
	protected bool ownedRef;

	/** Get the main Gtk struct */
	public GPtrArray* getPtrArrayStruct(bool transferOwnership = false)
	{
		if (transferOwnership)
			ownedRef = false;
		return gPtrArray;
	}

	/** the main Gtk struct as a void* */
	protected void* getStruct()
	{
		return cast(void*)gPtrArray;
	}

	/**
	 * Sets our main struct and passes it to the parent class.
	 */
	public this (GPtrArray* gPtrArray, bool ownedRef = false)
	{
		this.gPtrArray = gPtrArray;
		this.ownedRef = ownedRef;
	}

	/**
	 * Number of pointers in the array
	 */
	public uint len() pure
	{
		return gPtrArray.len;
	}

	/**
	 * Returns the pointer at the given index of the pointer array.
	 *
	 * This does not perform bounds checking on the given index, so
	 * you are responsible for checking it against the array length.
	 */
	public void* index(uint idx)
	{
		return (gPtrArray.pdata)[idx];
	}

	/**
	 */

	/**
	 * Adds a pointer to the end of the pointer array. The array will grow
	 * in size automatically if necessary.
	 *
	 * Params:
	 *     data = the pointer to add
	 */
	public void add(void* data)
	{
		g_ptr_array_add(gPtrArray, data);
	}

	/**
	 * Makes a full (deep) copy of a `GPtrArray`.
	 *
	 * @func, as a [callback@GLib.CopyFunc], takes two arguments, the data to be
	 * copied
	 * and a @user_data pointer. On common processor architectures, it’s safe to
	 * pass `NULL` as @user_data if the copy function takes only one argument. You
	 * may get compiler warnings from this though if compiling with GCC’s
	 * `-Wcast-function-type` warning.
	 *
	 * If @func is `NULL`, then only the pointers (and not what they are
	 * pointing to) are copied to the new `GPtrArray`.
	 *
	 * The copy of @array will have the same [callback@GLib.DestroyNotify] for its
	 * elements as
	 * @array. The copy will also be `NULL` terminated if (and only if) the source
	 * array is.
	 *
	 * Params:
	 *     func = a copy function used to copy every element in the array
	 *     userData = the user data passed to the copy function @func
	 *
	 * Returns: The deep copy of the initial `GPtrArray`
	 *
	 * Since: 2.62
	 */
	public PtrArray copy(GCopyFunc func, void* userData)
	{
		auto __p = g_ptr_array_copy(gPtrArray, func, userData);

		if(__p is null)
		{
			return null;
		}

		return new PtrArray(cast(GPtrArray*) __p, true);
	}

	/**
	 * Adds all pointers of @array to the end of the array @array_to_extend.
	 * The array will grow in size automatically if needed. @array_to_extend is
	 * modified in-place.
	 *
	 * @func, as a [callback@GLib.CopyFunc], takes two arguments, the data to be
	 * copied
	 * and a @user_data pointer. On common processor architectures, it’s safe to
	 * pass `NULL` as @user_data if the copy function takes only one argument. You
	 * may get compiler warnings from this though if compiling with GCC’s
	 * `-Wcast-function-type` warning.
	 *
	 * If @func is `NULL`, then only the pointers (and not what they are
	 * pointing to) are copied to the new `GPtrArray`.
	 *
	 * Whether @array_to_extend is `NULL` terminated stays unchanged by this function.
	 *
	 * Params:
	 *     array = a pointer array to add to the end of @array_to_extend
	 *     func = a copy function used to copy every element in the array
	 *     userData = the user data passed to the copy function @func
	 *
	 * Since: 2.62
	 */
	public void extend(PtrArray array, GCopyFunc func, void* userData)
	{
		g_ptr_array_extend(gPtrArray, (array is null) ? null : array.getPtrArrayStruct(), func, userData);
	}

	/**
	 * Adds all the pointers in @array to the end of @array_to_extend, transferring
	 * ownership of each element from @array to @array_to_extend and modifying
	 * @array_to_extend in-place. @array is then freed.
	 *
	 * As with [func@GLib.PtrArray.free], @array will be destroyed if its reference
	 * count is 1. If its reference count is higher, it will be decremented and the
	 * length of @array set to zero.
	 *
	 * Params:
	 *     array = a pointer array to add to the end of
	 *         @array_to_extend
	 *
	 * Since: 2.62
	 */
	public void extendAndSteal(PtrArray array)
	{
		g_ptr_array_extend_and_steal(gPtrArray, (array is null) ? null : array.getPtrArrayStruct());
	}

	/**
	 * Checks whether @needle exists in @haystack. If the element is found, true
	 * is returned and the element’s index is returned in @index_ (if non-`NULL`).
	 * Otherwise, false is returned and @index_ is undefined. If @needle exists
	 * multiple times in @haystack, the index of the first instance is returned.
	 *
	 * This does pointer comparisons only. If you want to use more complex equality
	 * checks, such as string comparisons, use
	 * [func@GLib.PtrArray.find_with_equal_func].
	 *
	 * Params:
	 *     needle = the pointer to look for
	 *     index = the return location for the index of
	 *         the element, if found
	 *
	 * Returns: true if @needle is one of the elements of @haystack; false otherwise
	 *
	 * Since: 2.54
	 */
	public bool find(void* needle, out uint index)
	{
		return g_ptr_array_find(gPtrArray, needle, &index) != 0;
	}

	/**
	 * Checks whether @needle exists in @haystack, using the given @equal_func.
	 * If the element is found, true is returned and the element’s index is
	 * returned in @index_ (if non-`NULL`). Otherwise, false is returned and @index_
	 * is undefined. If @needle exists multiple times in @haystack, the index of
	 * the first instance is returned.
	 *
	 * @equal_func is called with the element from the array as its first parameter,
	 * and @needle as its second parameter. If @equal_func is `NULL`, pointer
	 * equality is used.
	 *
	 * Params:
	 *     needle = the pointer to look for
	 *     equalFunc = the function to call for each element, which should
	 *         return true when the desired element is found; or `NULL` to use pointer
	 *         equality
	 *     index = the return location for the index of
	 *         the element, if found
	 *
	 * Returns: true if @needle is one of the elements of @haystack; false otherwise
	 *
	 * Since: 2.54
	 */
	public bool findWithEqualFunc(void* needle, GEqualFunc equalFunc, out uint index)
	{
		return g_ptr_array_find_with_equal_func(gPtrArray, needle, equalFunc, &index) != 0;
	}

	alias foreac = foreach_;
	/**
	 * Calls a function for each element of a `GPtrArray`. @func must not
	 * add elements to or remove elements from the array.
	 *
	 * Params:
	 *     func = the function to call for each array element
	 *     userData = the user data to pass to the function
	 *
	 * Since: 2.4
	 */
	public void foreach_(GFunc func, void* userData)
	{
		g_ptr_array_foreach(gPtrArray, func, userData);
	}

	/**
	 * Frees the memory allocated for the `GPtrArray`. If @free_segment is true
	 * it frees the memory block holding the elements as well. Pass false
	 * if you want to free the `GPtrArray` wrapper but preserve the
	 * underlying array for use elsewhere. If the reference count of @array
	 * is greater than one, the `GPtrArray` wrapper is preserved but the
	 * size of @array will be set to zero.
	 *
	 * If array contents point to dynamically-allocated memory, they should
	 * be freed separately if @free_segment is true and no
	 * [callback@GLib.DestroyNotify] function has been set for @array.
	 *
	 * Note that if the array is `NULL` terminated and @free_segment is false
	 * then this will always return an allocated `NULL` terminated buffer.
	 * If `pdata` is previously `NULL`, a new buffer will be allocated.
	 *
	 * This function is not thread-safe. If using a `GPtrArray` from multiple
	 * threads, use only the atomic [func@GLib.PtrArray.ref] and
	 * [func@GLib.PtrArray.unref] functions.
	 *
	 * Params:
	 *     freeSegment = if true, the actual pointer array is freed as well
	 *
	 * Returns: The allocated pointer array if
	 *     @free_segment is false, otherwise `NULL`.
	 */
	public void*[] free(bool freeSegment)
	{
		auto __p = g_ptr_array_free(gPtrArray, freeSegment);

		return __p[0 .. getArrayLength(__p)];
	}

	/**
	 * Inserts an element into the pointer array at the given index. The
	 * array will grow in size automatically if necessary.
	 *
	 * Params:
	 *     index = the index to place the new element at, or -1 to append
	 *     data = the pointer to add
	 *
	 * Since: 2.40
	 */
	public void insert(int index, void* data)
	{
		g_ptr_array_insert(gPtrArray, index, data);
	}

	/**
	 * Checks whether the @array was constructed as `NULL`-terminated.
	 *
	 * This will only return true for arrays constructed by passing true to the
	 * `null_terminated` argument of [func@GLib.PtrArray.new_null_terminated]. It
	 * will not return true for normal arrays which have had a `NULL` element
	 * appended to them.
	 *
	 * Returns: true if the array is made to be `NULL` terminated; false otherwise
	 *
	 * Since: 2.74
	 */
	public bool isNullTerminated()
	{
		return g_ptr_array_is_null_terminated(gPtrArray) != 0;
	}

	/**
	 * Creates a new `GPtrArray` with a reference count of 1.
	 *
	 * Returns: The new `GPtrArray`
	 *
	 * Throws: ConstructionException GTK+ fails to create the object.
	 */
	public this()
	{
		auto __p = g_ptr_array_new();

		if(__p is null)
		{
			throw new ConstructionException("null returned by new");
		}

		this(cast(GPtrArray*) __p);
	}

	/**
	 * Creates a new `GPtrArray`, copying @len pointers from @data, and setting
	 * the array’s reference count to 1.
	 *
	 * This avoids having to manually add each element one by one.
	 *
	 * If @copy_func is provided, then it is used to copy each element before
	 * adding them to the new array. If it is `NULL` then the pointers are copied
	 * directly.
	 *
	 * It also sets @element_free_func for freeing each element when the array is
	 * destroyed either via [func@GLib.PtrArray.unref], when
	 * [func@GLib.PtrArray.free] is called with @free_segment set to true or when
	 * removing elements.
	 *
	 * Do not use it if @len is greater than [`G_MAXUINT`](types.html#guint).
	 * `GPtrArray` stores the length of its data in `guint`, which may be shorter
	 * than `gsize`.
	 *
	 * Params:
	 *     data = an array of pointers
	 *     copyFunc = a copy function used to copy every element in the
	 *         array
	 *     copyFuncUserData = the user data passed to @copy_func
	 *     elementFreeFunc = a function to free elements on @array
	 *         destruction
	 *
	 * Returns: The new `GPtrArray`
	 *
	 * Since: 2.76
	 *
	 * Throws: ConstructionException GTK+ fails to create the object.
	 */
	public this(void*[] data, GCopyFunc copyFunc, void* copyFuncUserData, GDestroyNotify elementFreeFunc)
	{
		auto __p = g_ptr_array_new_from_array(data.ptr, cast(size_t)data.length, copyFunc, copyFuncUserData, elementFreeFunc);

		if(__p is null)
		{
			throw new ConstructionException("null returned by new_from_array");
		}

		this(cast(GPtrArray*) __p);
	}

	/**
	 * Creates a new `GPtrArray` with @reserved_size pointers preallocated
	 * and a reference count of 1. This avoids frequent reallocation, if
	 * you are going to add many pointers to the array. Note however that
	 * the size of the array is still 0. It also sets @element_free_func
	 * for freeing each element when the array is destroyed either via
	 * [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is called with
	 * @free_segment set to true or when removing elements.
	 *
	 * Params:
	 *     reservedSize = the number of pointers preallocated
	 *     elementFreeFunc = a function to free elements with
	 *         destroy @array
	 *
	 * Returns: The new `GPtrArray`
	 *
	 * Since: 2.30
	 *
	 * Throws: ConstructionException GTK+ fails to create the object.
	 */
	public this(uint reservedSize, GDestroyNotify elementFreeFunc)
	{
		auto __p = g_ptr_array_new_full(reservedSize, elementFreeFunc);

		if(__p is null)
		{
			throw new ConstructionException("null returned by new_full");
		}

		this(cast(GPtrArray*) __p);
	}

	/**
	 * Like [func@GLib.PtrArray.new_full] but also allows to set the array to
	 * be `NULL` terminated. A `NULL` terminated pointer array has an
	 * additional `NULL` pointer after the last element, beyond the
	 * current length.
	 *
	 * `GPtrArray` created by other constructors are not automatically `NULL`
	 * terminated.
	 *
	 * Note that if the @array’s length is zero and currently no
	 * data array is allocated, then `pdata` will still be `NULL`.
	 * `GPtrArray` will only `NULL` terminate `pdata`, if an actual
	 * array is allocated. It does not guarantee that an array
	 * is always allocated. In other words, if the length is zero,
	 * then `pdata` may either point to a `NULL` terminated array of length
	 * zero or be `NULL`.
	 *
	 * Params:
	 *     reservedSize = the number of pointers preallocated.
	 *         If @null_terminated is `TRUE`, the actually allocated
	 *         buffer size is @reserved_size plus 1, unless @reserved_size
	 *         is zero, in which case no initial buffer gets allocated.
	 *     elementFreeFunc = a function to free elements during
	 *         destruction of @array
	 *     nullTerminated = if true, make the array `NULL` terminated
	 *
	 * Returns: The new `GPtrArray`
	 *
	 * Since: 2.74
	 *
	 * Throws: ConstructionException GTK+ fails to create the object.
	 */
	public this(uint reservedSize, GDestroyNotify elementFreeFunc, bool nullTerminated)
	{
		auto __p = g_ptr_array_new_null_terminated(reservedSize, elementFreeFunc, nullTerminated);

		if(__p is null)
		{
			throw new ConstructionException("null returned by new_null_terminated");
		}

		this(cast(GPtrArray*) __p);
	}

	/**
	 * Creates a new `GPtrArray` with @data as pointers, @len as length and a
	 * reference count of 1.
	 *
	 * This avoids having to copy such data manually.
	 * After this call, @data belongs to the `GPtrArray` and may no longer be
	 * modified by the caller. The memory of @data has to be dynamically
	 * allocated and will eventually be freed with [func@GLib.free].
	 *
	 * It also sets @element_free_func for freeing each element when the array is
	 * destroyed either via [func@GLib.PtrArray.unref], when
	 * [func@GLib.PtrArray.free] is called with @free_segment set to true or when
	 * removing elements.
	 *
	 * Do not use it if @len is greater than [`G_MAXUINT`](types.html#guint).
	 * `GPtrArray` stores the length of its data in `guint`, which may be shorter
	 * than `gsize`.
	 *
	 * Params:
	 *     data = an array of pointers
	 *     elementFreeFunc = a function to free elements on @array
	 *         destruction
	 *
	 * Returns: The new `GPtrArray`
	 *
	 * Since: 2.76
	 *
	 * Throws: ConstructionException GTK+ fails to create the object.
	 */
	public this(void*[] data, GDestroyNotify elementFreeFunc)
	{
		auto __p = g_ptr_array_new_take(data.ptr, cast(size_t)data.length, elementFreeFunc);

		if(__p is null)
		{
			throw new ConstructionException("null returned by new_take");
		}

		this(cast(GPtrArray*) __p);
	}

	/**
	 * Creates a new `GPtrArray` with a reference count of 1 and use
	 * @element_free_func for freeing each element when the array is destroyed
	 * either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is
	 * called with @free_segment set to true or when removing elements.
	 *
	 * Params:
	 *     elementFreeFunc = a function to free elements with
	 *         destroy @array
	 *
	 * Returns: The new `GPtrArray`
	 *
	 * Since: 2.22
	 *
	 * Throws: ConstructionException GTK+ fails to create the object.
	 */
	public this(GDestroyNotify elementFreeFunc)
	{
		auto __p = g_ptr_array_new_with_free_func(elementFreeFunc);

		if(__p is null)
		{
			throw new ConstructionException("null returned by new_with_free_func");
		}

		this(cast(GPtrArray*) __p);
	}

	alias doref = ref_;
	/**
	 * Atomically increments the reference count of @array by one.
	 * This function is thread-safe and may be called from any thread.
	 *
	 * Returns: The passed in `GPtrArray`
	 *
	 * Since: 2.22
	 */
	public PtrArray ref_()
	{
		auto __p = g_ptr_array_ref(gPtrArray);

		if(__p is null)
		{
			return null;
		}

		return new PtrArray(cast(GPtrArray*) __p, true);
	}

	/**
	 * Removes the first occurrence of the given pointer from the pointer
	 * array. The following elements are moved down one place. If @array
	 * has a non-`NULL` [callback@GLib.DestroyNotify] function it is called for the
	 * removed element.
	 *
	 * It returns true if the pointer was removed, or false if the
	 * pointer was not found.
	 *
	 * Params:
	 *     data = the pointer to remove
	 *
	 * Returns: true if the pointer is found and removed; false otherwise
	 */
	public bool remove(void* data)
	{
		return g_ptr_array_remove(gPtrArray, data) != 0;
	}

	/**
	 * Removes the first occurrence of the given pointer from the pointer
	 * array. The last element in the array is used to fill in the space,
	 * so this function does not preserve the order of the array. But it
	 * is faster than [func@GLib.PtrArray.remove]. If @array has a non-`NULL`
	 * [callback@GLib.DestroyNotify] function it is called for the removed element.
	 *
	 * It returns true if the pointer was removed, or false if the
	 * pointer was not found.
	 *
	 * Params:
	 *     data = the pointer to remove
	 *
	 * Returns: true if the pointer is found and removed; false otherwise
	 */
	public bool removeFast(void* data)
	{
		return g_ptr_array_remove_fast(gPtrArray, data) != 0;
	}

	/**
	 * Removes the pointer at the given index from the pointer array.
	 * The following elements are moved down one place. If @array has
	 * a non-`NULL` [callback@GLib.DestroyNotify] function it is called for the
	 * removed
	 * element. If so, the return value from this function will potentially point
	 * to freed memory (depending on the [callback@GLib.DestroyNotify]
	 * implementation).
	 *
	 * Params:
	 *     index = the index of the pointer to remove
	 *
	 * Returns: The pointer which was removed
	 */
	public void* removeIndex(uint index)
	{
		return g_ptr_array_remove_index(gPtrArray, index);
	}

	/**
	 * Removes the pointer at the given index from the pointer array.
	 * The last element in the array is used to fill in the space, so
	 * this function does not preserve the order of the array. But it
	 * is faster than [func@GLib.PtrArray.remove_index]. If @array has a non-`NULL`
	 * [callback@GLib.DestroyNotify] function it is called for the removed element.
	 * If so, the
	 * return value from this function will potentially point to freed memory
	 * (depending on the [callback@GLib.DestroyNotify] implementation).
	 *
	 * Params:
	 *     index = the index of the pointer to remove
	 *
	 * Returns: The pointer which was removed
	 */
	public void* removeIndexFast(uint index)
	{
		return g_ptr_array_remove_index_fast(gPtrArray, index);
	}

	/**
	 * Removes the given number of pointers starting at the given index
	 * from a `GPtrArray`. The following elements are moved to close the
	 * gap. If @array has a non-`NULL` [callback@GLib.DestroyNotify] function it is
	 * called for the removed elements.
	 *
	 * Params:
	 *     index = the index of the first pointer to remove
	 *     length = the number of pointers to remove
	 *
	 * Returns: The @array
	 *
	 * Since: 2.4
	 */
	public PtrArray removeRange(uint index, uint length)
	{
		auto __p = g_ptr_array_remove_range(gPtrArray, index, length);

		if(__p is null)
		{
			return null;
		}

		return new PtrArray(cast(GPtrArray*) __p);
	}

	/**
	 * Sets a function for freeing each element when @array is destroyed
	 * either via [func@GLib.PtrArray.unref], when [func@GLib.PtrArray.free] is
	 * called with @free_segment set to true or when removing elements.
	 *
	 * Params:
	 *     elementFreeFunc = a function to free elements during
	 *         destruction of @array
	 *
	 * Since: 2.22
	 */
	public void setFreeFunc(GDestroyNotify elementFreeFunc)
	{
		g_ptr_array_set_free_func(gPtrArray, elementFreeFunc);
	}

	/**
	 * Sets the size of the array. When making the array larger,
	 * newly-added elements will be set to `NULL`. When making it smaller,
	 * if @array has a non-`NULL` [callback@GLib.DestroyNotify] function then it
	 * will be called for the removed elements.
	 *
	 * Params:
	 *     length = the new length of the pointer array
	 */
	public void setSize(int length)
	{
		g_ptr_array_set_size(gPtrArray, length);
	}

	/**
	 * Creates a new `GPtrArray` with @reserved_size pointers preallocated
	 * and a reference count of 1. This avoids frequent reallocation, if
	 * you are going to add many pointers to the array. Note however that
	 * the size of the array is still 0.
	 *
	 * Params:
	 *     reservedSize = the number of pointers preallocated
	 *
	 * Returns: The new `GPtrArray`
	 */
	public static PtrArray sizedNew(uint reservedSize)
	{
		auto __p = g_ptr_array_sized_new(reservedSize);

		if(__p is null)
		{
			return null;
		}

		return new PtrArray(cast(GPtrArray*) __p, true);
	}

	/**
	 * Sorts the array, using @compare_func which should be a `qsort()`-style
	 * comparison function (returns less than zero for first arg is less
	 * than second arg, zero for equal, greater than zero if first arg is
	 * greater than second arg).
	 *
	 * Note that the comparison function for [func@GLib.PtrArray.sort] doesn’t
	 * take the pointers from the array as arguments, it takes pointers to
	 * the pointers in the array.
	 *
	 * Use [func@GLib.PtrArray.sort_values] if you want to use normal
	 * [callback@GLib.CompareFunc] instances, otherwise here is a full example of
	 * use:
	 *
	 * ```c
	 * typedef struct
	 * {
	 * gchar *name;
	 * gint size;
	 * } FileListEntry;
	 *
	 * static gint
	 * sort_filelist (gconstpointer a, gconstpointer b)
	 * {
	 * const FileListEntry *entry1 = *((FileListEntry **) a);
	 * const FileListEntry *entry2 = *((FileListEntry **) b);
	 *
	 * return g_ascii_strcasecmp (entry1->name, entry2->name);
	 * }
	 *
	 * …
	 * g_autoptr (GPtrArray) file_list = NULL;
	 *
	 * // initialize file_list array and load with many FileListEntry entries
	 * ...
	 * // now sort it with
	 * g_ptr_array_sort (file_list, sort_filelist);
	 * ```
	 *
	 * This is guaranteed to be a stable sort since version 2.32.
	 *
	 * Params:
	 *     compareFunc = a comparison function
	 */
	public void sort(GCompareFunc compareFunc)
	{
		g_ptr_array_sort(gPtrArray, compareFunc);
	}

	/**
	 * Sorts the array, using @compare_func which should be a `qsort()`-style
	 * comparison function (returns less than zero for first arg is less
	 * than second arg, zero for equal, greater than zero if first arg is
	 * greater than second arg).
	 *
	 * This is guaranteed to be a stable sort.
	 *
	 * Params:
	 *     compareFunc = a comparison function
	 *
	 * Since: 2.76
	 */
	public void sortValues(GCompareFunc compareFunc)
	{
		g_ptr_array_sort_values(gPtrArray, compareFunc);
	}

	/**
	 * Like [func@GLib.PtrArray.sort_values], but the comparison function has an
	 * extra user data argument.
	 *
	 * This is guaranteed to be a stable sort.
	 *
	 * Params:
	 *     compareFunc = a comparison function
	 *     userData = the data to pass to @compare_func
	 *
	 * Since: 2.76
	 */
	public void sortValuesWithData(GCompareDataFunc compareFunc, void* userData)
	{
		g_ptr_array_sort_values_with_data(gPtrArray, compareFunc, userData);
	}

	/**
	 * Like [func@GLib.PtrArray.sort], but the comparison function has an extra
	 * user data argument.
	 *
	 * Note that the comparison function for [func@GLib.PtrArray.sort_with_data]
	 * doesn’t take the pointers from the array as arguments, it takes
	 * pointers to the pointers in the array.
	 *
	 * Use [func@GLib.PtrArray.sort_values_with_data] if you want to use normal
	 * [callback@GLib.CompareDataFunc] instances, otherwise here is a full example
	 * of use:
	 *
	 * ```c
	 * typedef enum { SORT_NAME, SORT_SIZE } SortMode;
	 *
	 * typedef struct
	 * {
	 * gchar *name;
	 * gint size;
	 * } FileListEntry;
	 *
	 * static gint
	 * sort_filelist (gconstpointer a, gconstpointer b, gpointer user_data)
	 * {
	 * gint order;
	 * const SortMode sort_mode = GPOINTER_TO_INT (user_data);
	 * const FileListEntry *entry1 = *((FileListEntry **) a);
	 * const FileListEntry *entry2 = *((FileListEntry **) b);
	 *
	 * switch (sort_mode)
	 * {
	 * case SORT_NAME:
	 * order = g_ascii_strcasecmp (entry1->name, entry2->name);
	 * break;
	 * case SORT_SIZE:
	 * order = entry1->size - entry2->size;
	 * break;
	 * default:
	 * order = 0;
	 * break;
	 * }
	 * return order;
	 * }
	 *
	 * ...
	 * g_autoptr (GPtrArray) file_list = NULL;
	 * SortMode sort_mode;
	 *
	 * // initialize file_list array and load with many FileListEntry entries
	 * ...
	 * // now sort it with
	 * sort_mode = SORT_NAME;
	 * g_ptr_array_sort_with_data (file_list,
	 * sort_filelist,
	 * GINT_TO_POINTER (sort_mode));
	 * ```
	 *
	 * This is guaranteed to be a stable sort since version 2.32.
	 *
	 * Params:
	 *     compareFunc = a comparison function
	 *     userData = the data to pass to @compare_func
	 */
	public void sortWithData(GCompareDataFunc compareFunc, void* userData)
	{
		g_ptr_array_sort_with_data(gPtrArray, compareFunc, userData);
	}

	/**
	 * Frees the data in the array and resets the size to zero, while
	 * the underlying array is preserved for use elsewhere and returned
	 * to the caller.
	 *
	 * Note that if the array is `NULL` terminated this may still return
	 * `NULL` if the length of the array was zero and pdata was not yet
	 * allocated.
	 *
	 * Even if set, the [callback@GLib.DestroyNotify] function will never be called
	 * on the current contents of the array and the caller is
	 * responsible for freeing the array elements.
	 *
	 * An example of use:
	 * ```c
	 * g_autoptr(GPtrArray) chunk_buffer = g_ptr_array_new_with_free_func (g_bytes_unref);
	 *
	 * // Some part of your application appends a number of chunks to the pointer array.
	 * g_ptr_array_add (chunk_buffer, g_bytes_new_static ("hello", 5));
	 * g_ptr_array_add (chunk_buffer, g_bytes_new_static ("world", 5));
	 *
	 * …
	 *
	 * // Periodically, the chunks need to be sent as an array-and-length to some
	 * // other part of the program.
	 * GBytes **chunks;
	 * gsize n_chunks;
	 *
	 * chunks = g_ptr_array_steal (chunk_buffer, &n_chunks);
	 * for (gsize i = 0; i < n_chunks; i++)
	 * {
	 * // Do something with each chunk here, and then free them, since
	 * // g_ptr_array_steal() transfers ownership of all the elements and the
	 * // array to the caller.
	 * …
	 *
	 * g_bytes_unref (chunks[i]);
	 * }
	 *
	 * g_free (chunks);
	 *
	 * // After calling g_ptr_array_steal(), the pointer array can be reused for the
	 * // next set of chunks.
	 * g_assert (chunk_buffer->len == 0);
	 * ```
	 *
	 * Returns: The allocated element data.
	 *     This may be `NULL`if the array doesn’t have any elements (i.e. if `*len` is zero).
	 *
	 * Since: 2.64
	 */
	public void*[] steal()
	{
		size_t len;

		auto __p = g_ptr_array_steal(gPtrArray, &len);

		return __p[0 .. len];
	}

	/**
	 * Removes the pointer at the given index from the pointer array.
	 * The following elements are moved down one place. The
	 * [callback@GLib.DestroyNotify] for
	 * @array is *not* called on the removed element; ownership is transferred to
	 * the caller of this function.
	 *
	 * Params:
	 *     index = the index of the pointer to steal
	 *
	 * Returns: The pointer which was removed
	 *
	 * Since: 2.58
	 */
	public void* stealIndex(uint index)
	{
		return g_ptr_array_steal_index(gPtrArray, index);
	}

	/**
	 * Removes the pointer at the given index from the pointer array.
	 * The last element in the array is used to fill in the space, so
	 * this function does not preserve the order of the array. But it
	 * is faster than [func@GLib.PtrArray.steal_index]. The
	 * [callback@GLib.DestroyNotify] for @array is
	 * *not* called on the removed element; ownership is transferred to the caller
	 * of this function.
	 *
	 * Params:
	 *     index = the index of the pointer to steal
	 *
	 * Returns: The pointer which was removed
	 *
	 * Since: 2.58
	 */
	public void* stealIndexFast(uint index)
	{
		return g_ptr_array_steal_index_fast(gPtrArray, index);
	}

	/**
	 * Atomically decrements the reference count of @array by one. If the
	 * reference count drops to 0, the effect is the same as calling
	 * [func@GLib.PtrArray.free] with @free_segment set to true. This function
	 * is thread-safe and may be called from any thread.
	 *
	 * Since: 2.22
	 */
	public void unref()
	{
		g_ptr_array_unref(gPtrArray);
	}
}
