arrays.h File Reference

Arrays and other linear sequential type fields. More...

#include "gate/gate_core_api.h"
#include "gate/memalloc.h"
#include "gate/atomics.h"
#include "gate/comparers.h"
#include "gate/enumerators.h"

Classes
struct	gate_array_class
	A linear constant field of items of the same types. More...
struct	gate_slotlist_class
	A linear changable field of pointers to changable items of the same types. More...
struct	gate_linkedentry_class
	A double-linked-list entry holding the link information and the content. More...
struct	gate_linkedlist_class
	A double-linked-list of item of the same type, where each entry has a pointer-link to the previous and the following item. More...

Typedefs
typedef struct gate_arraylist_class *	gate_arraylist_t
	A linear changable field of items of the same types.
typedef struct gate_array_class	gate_array_t
	A linear constant field of items of the same types.
typedef struct gate_slotlist_class	gate_slotlist_t
	A linear changable field of pointers to changable items of the same types.
typedef gate_size_t	gate_slotlist_iterator_t
typedef struct gate_linkedentry_class	gate_linkedentry_t
	A double-linked-list entry holding the link information and the content.
typedef struct gate_linkedlist_class	gate_linkedlist_t
	A double-linked-list of item of the same type, where each entry has a pointer-link to the previous and the following item.

Functions
GATE_CORE_API gate_array_t *	gate_array_create_static (gate_array_t *arr, void const *data_ptr, gate_size_t item_size, gate_size_t item_count)
	initializes an array object from a static constant C array
GATE_CORE_API gate_array_t *	gate_array_create_empty (gate_array_t *arr)
	initializes an empty array object
GATE_CORE_API gate_array_t *	gate_array_create (gate_array_t *arr, gate_arraylist_t arraylist)
	initializes an array object with the contents of an arraylist
GATE_CORE_API gate_array_t *	gate_array_copy (gate_array_t *arr, gate_array_t const *src)
	initializes an array object by copying the contents of another array
GATE_CORE_API gate_array_t *	gate_array_duplicate (gate_array_t *arr, gate_array_t const *src)
	initializes an array object as a reference duplicate of another array
GATE_CORE_API gate_array_t *	gate_array_subset (gate_array_t *arr, gate_array_t const *src, gate_size_t offset, gate_size_t count)
	initializes an array object as a reference duplicate of the subset of another array
GATE_CORE_API void	gate_array_release (gate_array_t *arr)
	releases acquired resources of an array object
GATE_CORE_API gate_size_t	gate_array_length (gate_array_t const *arr)
	returns the amount of items in an array object (== length)
GATE_CORE_API void const *	gate_array_get (gate_array_t const *arr, gate_size_t index)
	returns a pointer to an item contained in array object
GATE_CORE_API gate_enumerator_t *	gate_array_enumerate (gate_array_t const *arr, gate_enumerator_t *enumerator)
	creates an item enumerator from the array object
GATE_CORE_API gate_result_t	gate_array_copy_constructor (void *dst, void const *src)
	generic copy-constructor function for array objects
GATE_CORE_API void	gate_array_destructor (void *dst)
	generic destructor function for array objects
GATE_CORE_API void *	gate_array_sort (void *items, gate_size_t item_size, gate_size_t items_count, gate_comparer_t comparer, gate_mem_copyctor_t copy_constructor, gate_mem_dtor_t destructor)
	generic array items sorting function (ascending)
GATE_CORE_API void *	gate_array_sort_descending (void *items, gate_size_t item_size, gate_size_t items_count, gate_comparer_t comparer, gate_mem_copyctor_t copy_constructor, gate_mem_dtor_t destructor)
	generic array items sorting function (descending)
GATE_CORE_API gate_size_t	gate_array_remove_if (void *items, gate_size_t item_size, gate_size_t items_count, gate_check_condition_t condition_callback, void *param, gate_mem_copyctor_t copy_constructor, gate_mem_dtor_t destructor)
	generic array item removal functions, moves following items into position of removed items.
GATE_CORE_API gate_arraylist_t	gate_arraylist_create (gate_size_t itemsize, void const *source, gate_size_t length, gate_mem_copyctor_t cctor, gate_mem_dtor_t dtor)
	Creates an arraylist instance.
GATE_CORE_API gate_arraylist_t	gate_arraylist_retain (gate_arraylist_t arr)
	Increases the reference count of the arraylist instance.
GATE_CORE_API void	gate_arraylist_release (gate_arraylist_t arr)
	Decreases the reference count of the arraylist instance and deletes all resource when zero is reached.
GATE_CORE_API gate_arraylist_t	gate_arraylist_copy (gate_arraylist_t src_arr)
	Creates a copy of an existing arraylist.
GATE_CORE_API gate_size_t	gate_arraylist_itemsize (gate_arraylist_t arr)
	Returns the byte size of the item type that an arraylist contains (sizeof(item))
GATE_CORE_API gate_size_t	gate_arraylist_length (gate_arraylist_t arr)
	Returns the amount of items currently contained in an arraylist.
GATE_CORE_API void *	gate_arraylist_get (gate_arraylist_t arr, gate_size_t index)
	Returns a pointer to an item in arraylist, addressed by its index.
GATE_CORE_API void *	gate_arraylist_add (gate_arraylist_t arr, void const *item)
	Adds one new item to the arraylist by copying an existing source.
GATE_CORE_API void *	gate_arraylist_add_n (gate_arraylist_t arr, void const *item, gate_size_t repeat_count)
	Adds one item N times to the arraylist by copying an existing source.
GATE_CORE_API void *	gate_arraylist_insert (gate_arraylist_t arr, gate_size_t index, void const *item, gate_size_t itemcount)
	Inserts new items into an arraylist at a specific index position.
GATE_CORE_API gate_result_t	gate_arraylist_remove (gate_arraylist_t arr, gate_size_t index, gate_size_t count)
	Removes 1 to N items from the arraylist beginning at a specific index.
GATE_CORE_API gate_result_t	gate_arraylist_remove_if (gate_arraylist_t arr, gate_check_condition_t condition, void *param)
	Removes items from an arraylist that match a specific check evaluation.
GATE_CORE_API void	gate_arraylist_clear (gate_arraylist_t arr)
	Removes all items of the arraylist.
GATE_CORE_API gate_size_t	gate_arraylist_get_value (gate_arraylist_t arr, gate_size_t index, void *dest_buffer, gate_size_t dest_buffer_size)
	Constructs a copy of the addressed item's value on an external destination buffer.
GATE_CORE_API gate_size_t	gate_arraylist_create_item (gate_arraylist_t arr, void *dest_buffer, gate_size_t dest_buffer_size)
	Creates an item type on an external destination buffer.
GATE_CORE_API void	gate_arraylist_destroy_item (gate_arraylist_t arr, void *dest_buffer)
	Destroys an item type on an external buffer location.
GATE_CORE_API gate_enumerator_t *	gate_arraylist_enumerate (gate_arraylist_t arr, gate_enumerator_t *enumerator)
	Creates an enumerator instance to iterate over all items in the arraylist.
GATE_CORE_API gate_result_t	gate_arraylist_copy_constructor (void *dst, void const *src)
	Copy-constructor function to copy-construct an error list.
GATE_CORE_API void	gate_arraylist_destructor (void *dst)
	Destructor function to deallocate an arraylist object.
GATE_CORE_API gate_slotlist_t *	gate_slotlist_create (gate_slotlist_t *sl, gate_size_t itemsize, gate_mem_copyctor_t ctor, gate_mem_dtor_t dtor)
	Creates a new slotlist.
GATE_CORE_API gate_slotlist_t *	gate_slotlist_create_copy (gate_slotlist_t *sl, gate_slotlist_t const *src)
	Creates a new slotlist containing copies of items of another slotlist.
GATE_CORE_API void	gate_slotlist_destroy (gate_slotlist_t *sl)
	Destroys a slotlist and its associated content.
GATE_CORE_API void *	gate_slotlist_add (gate_slotlist_t *sl, void const *item)
	Adds an item to a slotlist at the next free slot.
GATE_CORE_API void *	gate_slotlist_first (gate_slotlist_t const *sl, gate_slotlist_iterator_t *iterator)
	Returns an iterator the first item on the slotlist.
GATE_CORE_API void *	gate_slotlist_next (gate_slotlist_t const *sl, gate_slotlist_iterator_t *iterator)
	Returns an iterator the first item on the slotlist.
GATE_CORE_API void *	gate_slotlist_at (gate_slotlist_t const *sl, gate_size_t index)
	Returns an item at a specific position.
GATE_CORE_API void *	gate_slotlist_get (gate_slotlist_t const *sl, gate_slotlist_iterator_t const *iterator)
	Returns an item addressed by an iterator.
GATE_CORE_API void *	gate_slotlist_insert_at (gate_slotlist_t *sl, gate_size_t index, void const *item)
	Inserts a new item into the slotlist at a specific position.
GATE_CORE_API gate_bool_t	gate_slotlist_remove (gate_slotlist_t *sl, gate_slotlist_iterator_t *iterator)
	Removes an item from slotlist addressed by iterator.
GATE_CORE_API gate_bool_t	gate_slotlist_remove_at (gate_slotlist_t *sl, gate_size_t index)
	Removes an item from slotlist addressed by index.
GATE_CORE_API void	gate_slotlist_clear (gate_slotlist_t *sl)
	Removes all items from a slotlist.
GATE_CORE_API gate_size_t	gate_slotlist_length (gate_slotlist_t const *sl)
	Returns the amount of items in the slotlist.
GATE_CORE_API gate_size_t	gate_slotlist_capacity (gate_slotlist_t const *sl)
	Returns the current allocated amount of slots in the slotlist.
GATE_CORE_API void *	gate_slotlist_import (gate_slotlist_t *sl, void *item)
	Inserts an allocated item into the slotlist at the next free slot position.
GATE_CORE_API void *	gate_slotlist_export (gate_slotlist_t *sl, gate_slotlist_iterator_t *iterator)
	Exports an allocated item from the slotlist, slot will be empty afterwards.
GATE_CORE_API void *	gate_slotlist_import_at (gate_slotlist_t *sl, gate_size_t index, void *item)
	Inserts an allocated item into the slotlist at an addressed position.
GATE_CORE_API void *	gate_slotlist_export_at (gate_slotlist_t *sl, gate_size_t index)
	Exports an allocated item from the slotlist, slot will be empty afterwards.
GATE_CORE_API gate_result_t	gate_linkedlist_create (gate_linkedlist_t *list, gate_size_t itemsize, gate_mem_copyctor_t ctor, gate_mem_dtor_t dtor)
	Creates a new linked list.
GATE_CORE_API void	gate_linkedlist_destroy (gate_linkedlist_t *list)
	Destroys a linked list.
GATE_CORE_API gate_linkedentry_t *	gate_linkedlist_add (gate_linkedlist_t *list, void const *item)
	Appends an item at the end of a linked-list.
GATE_CORE_API gate_linkedentry_t *	gate_linkedlist_insert (gate_linkedlist_t *list, gate_linkedentry_t *entry, void const *item)
	Inserts a new item at a specific position.
GATE_CORE_API gate_result_t	gate_linkedlist_remove (gate_linkedlist_t *list, gate_linkedentry_t *entry)
	Removes an entry from a linked-list.
GATE_CORE_API gate_linkedentry_t *	gate_linkedlist_first (gate_linkedlist_t const *list)
	Returns the first entry in the linked-list.
GATE_CORE_API gate_linkedentry_t *	gate_linkedlist_last (gate_linkedlist_t const *list)
	Returns the last entry in the linked-list.
GATE_CORE_API gate_linkedentry_t *	gate_linkedlist_previous (gate_linkedentry_t const *entry)
	Returns the previous linked-entry of a specific linked-entry.
GATE_CORE_API gate_linkedentry_t *	gate_linkedlist_next (gate_linkedentry_t const *entry)
	Returns the next linked-entry of a specific linked-entry.
GATE_CORE_API gate_enumerator_t *	gate_linkedlist_enumerate (gate_linkedlist_t const *list, gate_enumerator_t *enumerator)
	Initializes an enumerator to iterate over the elements of a linked-list.
GATE_CORE_API gate_bool_t	gate_bit_is_set (void const *data, gate_size_t bitindex)
	Reads a bit of a binary field at a specific bit position.
GATE_CORE_API void	gate_bit_set (void *data, gate_size_t bitindex)
	Sets a bit in a binary field.
GATE_CORE_API void	gate_bit_clear (void *data, gate_size_t bitindex)
	Sets a bit in a binary field.

Detailed Description

Arrays and other linear sequential type fields.

Typedef Documentation

gate_array_t

typedef struct gate_array_class gate_array_t

A linear constant field of items of the same types.

The object points to the first item of a linear list of items. A static array is a pointer to an external (non-owned) field of items, while a default array contains an arraylist that owns all contained items The length and the items of an array is constant, they cannot be changed during runtime.

gate_arraylist_t

typedef struct gate_arraylist_class* gate_arraylist_t

A linear changable field of items of the same types.

New items are copied into the array. An added or inserted item is owned by the array object and destroyed on its removal. All items are allocated in one block of memory.

gate_linkedentry_t

typedef struct gate_linkedentry_class gate_linkedentry_t

A double-linked-list entry holding the link information and the content.

A linked-entry instance is overallocated (sizeof(gate_linkedentry_t) + sizeof(item_type)) and the content data is placed after the entry object The entry object holds links to the previous and the next entry in a linked-list. A data pointer addresses the beginning of the content type (following the linked-entry object)

gate_linkedlist_t

typedef struct gate_linkedlist_class gate_linkedlist_t

A double-linked-list of item of the same type, where each entry has a pointer-link to the previous and the following item.

Each inserted item is allocated in a separate memory space and links of neighbor items are updated accordingly. Insertion and deletion of items is performed fast at the cost of memory overhead and fragmentation.

gate_slotlist_iterator_t

typedef gate_size_t gate_slotlist_iterator_t

iterator type of slotlist

gate_slotlist_t

typedef struct gate_slotlist_class gate_slotlist_t

A linear changable field of pointers to changable items of the same types.

A new item is copied into a separate memory space and a pointer to it is added to the slotlist array. Such pointer arrays are manipulated faster than arraylists as they only need to move pointers instead of copying whole objects, but they have a higher memory overhead. New added items are inserted in the next free position. If an item is removed at a specific position, the next added item takes that free position.

Function Documentation

gate_array_copy()

GATE_CORE_API gate_array_t * gate_array_copy	(	gate_array_t *	arr,
		gate_array_t const *	src )

initializes an array object by copying the contents of another array

Parameters

[out]	arr	array object to be initialized
[in]	src	source array to be copied

Returns

return pointer to array (same as "arr") on success or NULL on error

gate_array_copy_constructor()

GATE_CORE_API gate_result_t gate_array_copy_constructor	(	void *	dst,
		void const *	src )

generic copy-constructor function for array objects

Parameters

[out]	dst	pointer to target array to be initialized
[in]	src	pointer to source array to be duplicated

Returns

result indicating copying was successful

gate_array_create()

GATE_CORE_API gate_array_t * gate_array_create	(	gate_array_t *	arr,
		gate_arraylist_t	arraylist )

initializes an array object with the contents of an arraylist

Parameters

[out]	arr	array object to be initialized
[in]	arraylist	arraylist object containing array data

Returns

return pointer to array (same as "arr") on success or NULL on error

gate_array_create_empty()

GATE_CORE_API gate_array_t * gate_array_create_empty

(

gate_array_t *

arr

)

initializes an empty array object

Parameters

[out]

arr

array object to be initialized

Returns

returns pointer to array (same as "arr") on success or NULL on error

gate_array_create_static()

GATE_CORE_API gate_array_t * gate_array_create_static	(	gate_array_t *	arr,
		void const *	data_ptr,
		gate_size_t	item_size,
		gate_size_t	item_count )

initializes an array object from a static constant C array

Parameters

[out]	arr	array object to be initialized
[in]	data_ptr	pointer to first item in array
[in]	item_size	size of one array element in bytes (== sizeof(item_type))
[in]	item_count	amount of items to be addressed by array

Returns

returns pointer to array (same as "arr") on success or NULL on error

gate_array_destructor()

GATE_CORE_API void gate_array_destructor

(

void *

dst

)

generic destructor function for array objects

Parameters

[in,out]

dst

pointer to array to be released

gate_array_duplicate()

GATE_CORE_API gate_array_t * gate_array_duplicate	(	gate_array_t *	arr,
		gate_array_t const *	src )

initializes an array object as a reference duplicate of another array

Parameters

[out]	arr	array object to be initialized
[in]	src	source array to be referenced

Returns

return pointer to array (same as "arr") on success or NULL on error

gate_array_enumerate()

GATE_CORE_API gate_enumerator_t * gate_array_enumerate	(	gate_array_t const *	arr,
		gate_enumerator_t *	enumerator )

creates an item enumerator from the array object

Parameters

[in]	arr	array object to be evaluated
[out]	enumerator	pointer to enumerator to be initialized

Returns

pointer to enumerator, or NULL in case of an internal error

gate_array_get()

GATE_CORE_API void const * gate_array_get	(	gate_array_t const *	arr,
		gate_size_t	index )

returns a pointer to an item contained in array object

Parameters

[in]	arr	array object to be evaluated
[in]	index	index of item in array

Returns

pointer to array, or NULL if index is out of array bounds

gate_array_length()

GATE_CORE_API gate_size_t gate_array_length

(

gate_array_t const *

arr

)

returns the amount of items in an array object (== length)

Parameters

[in]

arr

array object to be evaluated

Returns

amount of items contained in array object

gate_array_release()

GATE_CORE_API void gate_array_release

(

gate_array_t *

arr

)

releases acquired resources of an array object

Parameters

[in,out]

arr

array object to be released

gate_array_remove_if()

GATE_CORE_API gate_size_t gate_array_remove_if	(	void *	items,
		gate_size_t	item_size,
		gate_size_t	items_count,
		gate_check_condition_t	condition_callback,
		void *	param,
		gate_mem_copyctor_t	copy_constructor,
		gate_mem_dtor_t	destructor )

generic array item removal functions, moves following items into position of removed items.

Parameters

[in,out]	items	pointer to first item in target array to be evaluated.
[in]	item_size	size of one array item ( ==sizeof(array_item_t) ).
[in]	items_count	amount of items in array.
[in]	condition_callback	removal check condition callback function.
[in]	param	user parameter to be used in condition_callback
[in]	copy_constructor	item constructor function (or NULL to use gate_mem_copy).
[in]	destructor	item destructor function (or NULL if no destruction required).

Returns

new size of valid items in array

gate_array_sort()

GATE_CORE_API void * gate_array_sort	(	void *	items,
		gate_size_t	item_size,
		gate_size_t	items_count,
		gate_comparer_t	comparer,
		gate_mem_copyctor_t	copy_constructor,
		gate_mem_dtor_t	destructor )

generic array items sorting function (ascending)

Parameters

[in,out]	items	pointer to first item in target array to be sorted
[in]	item_size	size of one array item ( ==sizeof(array_item_t) )
[in]	items_count	amount of items in array
[in]	comparer	item comparer function (or NULL to use gate_mem_compare)
[in]	copy_constructor	item constructor function (or NULL to use gate_mem_copy)
[in]	destructor	item destructor function (or NULL if no destruction required)

Returns

pointer to first item in array on success, or NULL in case of error

gate_array_sort_descending()

GATE_CORE_API void * gate_array_sort_descending	(	void *	items,
		gate_size_t	item_size,
		gate_size_t	items_count,
		gate_comparer_t	comparer,
		gate_mem_copyctor_t	copy_constructor,
		gate_mem_dtor_t	destructor )

generic array items sorting function (descending)

Parameters

[in,out]	items	pointer to first item in target array to be sorted
[in]	item_size	size of one array item ( ==sizeof(array_item_t) )
[in]	items_count	amount of items in array
[in]	comparer	item comparer function (or NULL to use gate_mem_compare)
[in]	copy_constructor	item constructor function (or NULL to use gate_mem_copy)
[in]	destructor	item destructor function (or NULL if no destruction required)

Returns

pointer to first item in array on success, or NULL in case of error

gate_array_subset()

GATE_CORE_API gate_array_t * gate_array_subset	(	gate_array_t *	arr,
		gate_array_t const *	src,
		gate_size_t	offset,
		gate_size_t	count )

initializes an array object as a reference duplicate of the subset of another array

Parameters

[out]	arr	array object to be initialized
[in]	src	source array to be referenced
[in]	offset	index in source array to start referencing
[in]	count	amount of array items to be referenced

Returns

return pointer to array (same as "arr") on success or NULL on error

gate_arraylist_add()

GATE_CORE_API void * gate_arraylist_add	(	gate_arraylist_t	arr,
		void const *	item )

Adds one new item to the arraylist by copying an existing source.

Parameters

[in]	arr	arraylist instance to be updated
[in]	item	pointer to item, thats copy is added to the arraylist

Returns

pointer to new item within arraylist, NULL indicates an allocation error

gate_arraylist_add_n()

GATE_CORE_API void * gate_arraylist_add_n	(	gate_arraylist_t	arr,
		void const *	item,
		gate_size_t	repeat_count )

Adds one item N times to the arraylist by copying an existing source.

Parameters

[in]	arr	arraylist instance to be updated
[in]	item	pointer to item, thats copy is added to the arraylist
[in]	repeat_count	count of copies to be added to the arraylist

Returns

pointer to the first new item within arraylist, NULL indicates an allocation error

gate_arraylist_clear()

GATE_CORE_API void gate_arraylist_clear

(

gate_arraylist_t

arr

)

Removes all items of the arraylist.

Parameters

[in]

arr

arraylist instance to be updated

gate_arraylist_copy()

GATE_CORE_API gate_arraylist_t gate_arraylist_copy

(

gate_arraylist_t

src_arr

)

Creates a copy of an existing arraylist.

Parameters

[in]

src_arr

source array list to be copied

Returns

new arraylist instance that contains copies of the elements of src_arr

gate_arraylist_copy_constructor()

GATE_CORE_API gate_result_t gate_arraylist_copy_constructor	(	void *	dst,
		void const *	src )

Copy-constructor function to copy-construct an error list.

Parameters

[in]	dst	pointer to space where a new arraylist is created
[in]	src	pointer to existing arraylist object to be copied

Returns

GATE_RESULT_* result code

gate_arraylist_create()

GATE_CORE_API gate_arraylist_t gate_arraylist_create	(	gate_size_t	itemsize,
		void const *	source,
		gate_size_t	length,
		gate_mem_copyctor_t	cctor,
		gate_mem_dtor_t	dtor )

Creates an arraylist instance.

Parameters

[in]	itemsize	sizeof(item) that this arraylist is going to contain.
[in]	source	optional pointer to first element of items to be added to arraylist during construction
[in]	length	amount of elemts to be added
[in]	cctor	copy-constructor function to be used to insert items, NULL means memcpy() is used
[in]	dtor	destructor function that is applied when an element is removed, NULL means no action is applied

Returns

new arraylist object instance (pointer type)

gate_arraylist_create_item()

GATE_CORE_API gate_size_t gate_arraylist_create_item	(	gate_arraylist_t	arr,
		void *	dest_buffer,
		gate_size_t	dest_buffer_size )

Creates an item type on an external destination buffer.

Parameters

[in]	arr	arraylist instance to be used
[in]	dest_buffer	pointer to byte buffer where new item is constructed (using the internal constructor function)
[in]	dest_buffer_size	capacity of dest_buffer in bytes

Returns

size of constructed item in bytes, or zero if construction has failed

gate_arraylist_destroy_item()

GATE_CORE_API void gate_arraylist_destroy_item	(	gate_arraylist_t	arr,
		void *	dest_buffer )

Destroys an item type on an external buffer location.

Parameters

[in]	arr	arraylist instance to be used
[in]	dest_buffer	pointer to byte buffer where an existing item is destroy (using the internal destructor function)

gate_arraylist_destructor()

GATE_CORE_API void gate_arraylist_destructor

(

void *

dst

)

Destructor function to deallocate an arraylist object.

Parameters

[in]

dst

pointer to space arraylist to be destroyed

gate_arraylist_enumerate()

GATE_CORE_API gate_enumerator_t * gate_arraylist_enumerate	(	gate_arraylist_t	arr,
		gate_enumerator_t *	enumerator )

Creates an enumerator instance to iterate over all items in the arraylist.

Parameters

[in]	arr	arraylist instance to be used
[in]	enumerator	pointer to uninitialized enumerator space, where the enumerator will be constructed

Returns

pointer to constructed enumerator, or NULL in case of an error

gate_arraylist_get()

GATE_CORE_API void * gate_arraylist_get	(	gate_arraylist_t	arr,
		gate_size_t	index )

Returns a pointer to an item in arraylist, addressed by its index.

Parameters

[in]	arr	arraylist instance to be evaluated
[in]	index	zero-based index of item in arraylist

Returns

pointer to addressed item or NULL if index is out of bounds

gate_arraylist_get_value()

GATE_CORE_API gate_size_t gate_arraylist_get_value	(	gate_arraylist_t	arr,
		gate_size_t	index,
		void *	dest_buffer,
		gate_size_t	dest_buffer_size )

Constructs a copy of the addressed item's value on an external destination buffer.

Parameters

[in]	arr	arraylist instance to be used
[in]	index	index of item to be accessed
[in]	dest_buffer	pointer to byte buffer where item's value is copy-constructed (using the internal constructor function)
[in]	dest_buffer_size	capacity of dest_buffer in bytes

Returns

size of constructed item in bytes, or zero if construction has failed

gate_arraylist_insert()

GATE_CORE_API void * gate_arraylist_insert	(	gate_arraylist_t	arr,
		gate_size_t	index,
		void const *	item,
		gate_size_t	itemcount )

Inserts new items into an arraylist at a specific index position.

Parameters

[in]	arr	arraylist instance to be updated
[in]	index	index within arraylist, where new items are inserted
[in]	item	pointer to first item of list to be added to the arraylist
[in]	itemcount	count of items beginning at item-pointer

Returns

pointer to the first new item within arraylist, NULL indicates an allocation error

gate_arraylist_itemsize()

GATE_CORE_API gate_size_t gate_arraylist_itemsize

(

gate_arraylist_t

arr

)

Returns the byte size of the item type that an arraylist contains (sizeof(item))

Parameters

[in]

arr

arraylist instance to be evaluated

Returns

byte size of datatype managed by arraylist instance

gate_arraylist_length()

GATE_CORE_API gate_size_t gate_arraylist_length

(

gate_arraylist_t

arr

)

Returns the amount of items currently contained in an arraylist.

Parameters

[in]

arr

arraylist instance to be evaluated

Returns

count of contained items

gate_arraylist_release()

GATE_CORE_API void gate_arraylist_release

(

gate_arraylist_t

arr

)

Decreases the reference count of the arraylist instance and deletes all resource when zero is reached.

Parameters

[in,out]

arr

arraylist instance to be released

gate_arraylist_remove()

GATE_CORE_API gate_result_t gate_arraylist_remove	(	gate_arraylist_t	arr,
		gate_size_t	index,
		gate_size_t	count )

Removes 1 to N items from the arraylist beginning at a specific index.

Parameters

[in]	arr	arraylist instance to be updated
[in]	index	index within arraylist, where items are deleted
[in]	count	count of items to be removed

Returns

GATE_RESULT_* error code

gate_arraylist_remove_if()

GATE_CORE_API gate_result_t gate_arraylist_remove_if	(	gate_arraylist_t	arr,
		gate_check_condition_t	condition,
		void *	param )

Removes items from an arraylist that match a specific check evaluation.

Parameters

[in]	arr	arraylist instance to be updated
[in]	condition	pointer to function that is called for each item, return value TRUE enables deletion of item
[in]	param	parameter pointer to be used in each condition function call

Returns

GATE_RESULT_* error code

gate_arraylist_retain()

GATE_CORE_API gate_arraylist_t gate_arraylist_retain

(

gate_arraylist_t

arr

)

Increases the reference count of the arraylist instance.

Parameters

[in,out]

arr

arraylist instance to be retained

Returns

arraylist instance that was retained

gate_bit_clear()

GATE_CORE_API void gate_bit_clear	(	void *	data,
		gate_size_t	bitindex )

Sets a bit in a binary field.

Parameters

[in]	data	pointer to bit-data to be updated
[in]	bitindex	index of bit to be cleared

gate_bit_is_set()

GATE_CORE_API gate_bool_t gate_bit_is_set	(	void const *	data,
		gate_size_t	bitindex )

Reads a bit of a binary field at a specific bit position.

Parameters

[in]	data	pointer to bit-data to be evaluated
[in]	bitindex	index of bit to be accessed

Returns

TRUE if bit was set, FALSE if bit was cleared

gate_bit_set()

GATE_CORE_API void gate_bit_set	(	void *	data,
		gate_size_t	bitindex )

Sets a bit in a binary field.

Parameters

[in]	data	pointer to bit-data to be updated
[in]	bitindex	index of bit to be set

gate_linkedlist_add()

GATE_CORE_API gate_linkedentry_t * gate_linkedlist_add	(	gate_linkedlist_t *	list,
		void const *	item )

Appends an item at the end of a linked-list.

Parameters

[in]	list	pointer to linkedlist to be updated
[in]	item	pointer to item, thats copy is going to be added to the linked-list

Returns

pointer to new linkedentry in the linked-list

gate_linkedlist_create()

GATE_CORE_API gate_result_t gate_linkedlist_create	(	gate_linkedlist_t *	list,
		gate_size_t	itemsize,
		gate_mem_copyctor_t	ctor,
		gate_mem_dtor_t	dtor )

Creates a new linked list.

Parameters

[in]	list	pointer to linkedlist to be initialized
[in]	itemsize	sizeof of item type handled by the new linkedlist
[in]	ctor	pointer to copy-constructor function of item type, NULL employs memcpy() for content construction
[in]	dtor	pointer to destructor function of item type, NULL does not perform content destruction

Returns

GATE_RESULT_* result code

gate_linkedlist_destroy()

GATE_CORE_API void gate_linkedlist_destroy

(

gate_linkedlist_t *

list

)

Destroys a linked list.

Parameters

[in]

list

pointer to linkedlist to be destroyed

gate_linkedlist_enumerate()

GATE_CORE_API gate_enumerator_t * gate_linkedlist_enumerate	(	gate_linkedlist_t const *	list,
		gate_enumerator_t *	enumerator )

Initializes an enumerator to iterate over the elements of a linked-list.

Parameters

[in]	list	pointer to linked-entry to be evaluated
[in,out]	enumerator	pointer to enumerator to be initialized with linked-list

Returns

pointer to initialized enumerator, NULL indicates an internal error

gate_linkedlist_first()

GATE_CORE_API gate_linkedentry_t * gate_linkedlist_first

(

gate_linkedlist_t const *

list

)

Returns the first entry in the linked-list.

Parameters

[in]

list

pointer to linkedlist to be iterated

Returns

pointer to linkedentry of first element, or NULL if list was empty

gate_linkedlist_insert()

GATE_CORE_API gate_linkedentry_t * gate_linkedlist_insert	(	gate_linkedlist_t *	list,
		gate_linkedentry_t *	entry,
		void const *	item )

Inserts a new item at a specific position.

Parameters

[in]	list	pointer to linkedlist to be updated
[in]	entry	pointer to linkedentry, where the item is going to be inserted, that entry will afterwards follow the new entry
[in]	item	pointer to item, thats copy is going to be added to the linked-list

Returns

pointer to new linkedentry in the linked-list

gate_linkedlist_last()

GATE_CORE_API gate_linkedentry_t * gate_linkedlist_last

(

gate_linkedlist_t const *

list

)

Returns the last entry in the linked-list.

Parameters

[in]

list

pointer to linkedlist to be iterated

Returns

pointer to linkedentry of last element, or NULL if list was empty

gate_linkedlist_next()

GATE_CORE_API gate_linkedentry_t * gate_linkedlist_next

(

gate_linkedentry_t const *

entry

)

Returns the next linked-entry of a specific linked-entry.

Parameters

[in]

entry

pointer to linked-entry to be evaluated

Returns

pointer to next following linked-entry or NULL if no following entry is available

gate_linkedlist_previous()

GATE_CORE_API gate_linkedentry_t * gate_linkedlist_previous

(

gate_linkedentry_t const *

entry

)

Returns the previous linked-entry of a specific linked-entry.

Parameters

[in]

entry

pointer to linked-entry to be evaluated

Returns

pointer to previous linked-entry or NULL if no previous entry is available

gate_linkedlist_remove()

GATE_CORE_API gate_result_t gate_linkedlist_remove	(	gate_linkedlist_t *	list,
		gate_linkedentry_t *	entry )

Removes an entry from a linked-list.

Parameters

[in]	list	pointer to linkedlist to be updated
[in]	entry	pointer to linkedentry to be removed

Returns

GATE_RESULT_* result code

gate_slotlist_add()

GATE_CORE_API void * gate_slotlist_add	(	gate_slotlist_t *	sl,
		void const *	item )

Adds an item to a slotlist at the next free slot.

Parameters

[in]	sl	pointer to slotlist to be updated
[in]	item	pointer to an item, thats copy is a going to be added to the slotlist

Returns

pointer to new item contained in slotlist

gate_slotlist_at()

GATE_CORE_API void * gate_slotlist_at	(	gate_slotlist_t const *	sl,
		gate_size_t	index )

Returns an item at a specific position.

Parameters

[in]	sl	pointer to slotlist to be accessed
[in]	index	zero-based index (less capacity)

Returns

pointer to item addressed by position, or NULL if slot is empty or index is out of bounds

gate_slotlist_capacity()

GATE_CORE_API gate_size_t gate_slotlist_capacity

(

gate_slotlist_t const *

sl

)

Returns the current allocated amount of slots in the slotlist.

Parameters

[in]

sl

pointer to slotlist to be accessed

Returns

Allocated capacity of possible items in slotlist

gate_slotlist_clear()

GATE_CORE_API void gate_slotlist_clear

(

gate_slotlist_t *

sl

)

Removes all items from a slotlist.

Parameters

[in]

sl

pointer to slotlist to be updated

gate_slotlist_create()

GATE_CORE_API gate_slotlist_t * gate_slotlist_create	(	gate_slotlist_t *	sl,
		gate_size_t	itemsize,
		gate_mem_copyctor_t	ctor,
		gate_mem_dtor_t	dtor )

Creates a new slotlist.

Parameters

[in]	sl	pointer to slotlist to be initialized
[in]	itemsize	byte size of item type to be handled by slotlist (sizeof(item))
[in]	ctor	copy-constructor function of item type, if NULL is used, memcpy() is employed
[in]	dtor	destructor function of item type, if NULL is used, no action is performed

Returns

pointer to initialized slotlist, NULL indicates an allocation error

gate_slotlist_create_copy()

GATE_CORE_API gate_slotlist_t * gate_slotlist_create_copy	(	gate_slotlist_t *	sl,
		gate_slotlist_t const *	src )

Creates a new slotlist containing copies of items of another slotlist.

Parameters

[in]	sl	pointer to slotlist to be initialized
[in]	src	pointer to source slotlist thats items are copied

Returns

pointer to initialized slotlist, NULL indicates an allocation error

gate_slotlist_destroy()

GATE_CORE_API void gate_slotlist_destroy

(

gate_slotlist_t *

sl

)

Destroys a slotlist and its associated content.

Parameters

[in]

sl

pointer to slotlist to be destroyed

gate_slotlist_export()

GATE_CORE_API void * gate_slotlist_export	(	gate_slotlist_t *	sl,
		gate_slotlist_iterator_t *	iterator )

Exports an allocated item from the slotlist, slot will be empty afterwards.

Parameters

[in]	sl	pointer to slotlist to be updated
[in]	iterator	pointer to iterator that addresses the item to be exported

Returns

Pointer to exported item

gate_slotlist_export_at()

GATE_CORE_API void * gate_slotlist_export_at	(	gate_slotlist_t *	sl,
		gate_size_t	index )

Exports an allocated item from the slotlist, slot will be empty afterwards.

Parameters

[in]	sl	pointer to slotlist to be updated
[in]	index	index position of item in slotlist to be exported

Returns

Pointer to exported item

gate_slotlist_first()

GATE_CORE_API void * gate_slotlist_first	(	gate_slotlist_t const *	sl,
		gate_slotlist_iterator_t *	iterator )

Returns an iterator the first item on the slotlist.

Parameters

[in]	sl	pointer to slotlist to be iterated
[in]	iterator	pointer to iterator to be initialized with first item

Returns

pointer to first item or NULL if no item is available

gate_slotlist_get()

GATE_CORE_API void * gate_slotlist_get	(	gate_slotlist_t const *	sl,
		gate_slotlist_iterator_t const *	iterator )

Returns an item addressed by an iterator.

Parameters

[in]	sl	to slotlist to be accessed
[in]	iterator	pointer to iterator addressing the desired item

Returns

pointer to item addressed by iterator, or NULL if slot is empty or iterator is invalid

gate_slotlist_import()

GATE_CORE_API void * gate_slotlist_import	(	gate_slotlist_t *	sl,
		void *	item )

Inserts an allocated item into the slotlist at the next free slot position.

Parameters

[in]	sl	pointer to slotlist to be updated
[in]	item	pointer to allocated item to be inserted

Returns

Pointer to inserted item, NULL indicates an internal allocation error

gate_slotlist_import_at()

GATE_CORE_API void * gate_slotlist_import_at	(	gate_slotlist_t *	sl,
		gate_size_t	index,
		void *	item )

Inserts an allocated item into the slotlist at an addressed position.

Parameters

[in]	sl	pointer to slotlist to be updated
[in]	index	index position in slotlist where item is inserted
[in]	item	pointer to allocated item to be inserted

Returns

Pointer to inserted item, NULL indicates an internal allocation error

gate_slotlist_insert_at()

GATE_CORE_API void * gate_slotlist_insert_at	(	gate_slotlist_t *	sl,
		gate_size_t	index,
		void const *	item )

Inserts a new item into the slotlist at a specific position.

Parameters

[in]	sl	pointer to slotlist to be updated
[in]	index	zero-based index
[in]	item	pointer to item thats copy is going to be inserted

Returns

pointer to new item in slotlist, NULL indicates an allocation error

gate_slotlist_length()

GATE_CORE_API gate_size_t gate_slotlist_length

(

gate_slotlist_t const *

sl

)

Returns the amount of items in the slotlist.

Parameters

[in]

sl

pointer to slotlist to be accessed

Returns

Count of items in the slotlist

gate_slotlist_next()

GATE_CORE_API void * gate_slotlist_next	(	gate_slotlist_t const *	sl,
		gate_slotlist_iterator_t *	iterator )

Returns an iterator the first item on the slotlist.

Parameters

[in]	sl	pointer to slotlist to be iterated
[in]	iterator	pointer to iterator to be moved to next item

Returns

pointer to next item or NULL if no item is available

gate_slotlist_remove()

GATE_CORE_API gate_bool_t gate_slotlist_remove	(	gate_slotlist_t *	sl,
		gate_slotlist_iterator_t *	iterator )

Removes an item from slotlist addressed by iterator.

Parameters

[in]	sl	pointer to slotlist to be updated
[in]	iterator	pointer to iterator to element to be removed

Returns

TRUE if item was removed

gate_slotlist_remove_at()

GATE_CORE_API gate_bool_t gate_slotlist_remove_at	(	gate_slotlist_t *	sl,
		gate_size_t	index )

Removes an item from slotlist addressed by index.

Parameters

[in]	sl	pointer to slotlist to be updated
[in]	index	index of item to be removed

Returns

TRUE if item was removed