Vector class - a standard ooc container. More...

#include "ooc.h"

Include dependency graph for vector.h:

Macros
#define	vector_new_type(chunk_size, pClass, manage)
	Vector constructor. More...

#define	vector_use_type_with_store(vector, size, pClass, manage, store)
	Vector constructor. More...

Typedefs
typedef struct VectorObject *	Vector
	Vector class declaration.

typedef size_t	VectorIndex
	Index for the Vector. More...

typedef void(*	vector_item_destroyer )(void *item)
	Vector Item Destroyer. More...

typedef void(*	vector_item_executor )(void item, void param)
	Vector Item Executor. More...

typedef int(*	vector_item_checker )(void item, void param)
	Vector Item Checker. More...

Functions
Vector	vector_new (VectorIndex chunk_size, vector_item_destroyer destroyer)
	Vector constructor. More...

Vector	_vector_new_type (VectorIndex chunk_size, Class type, int manage)
	Vector constructor. More...

Vector	vector_new_from_table (void *table, size_t record_size, VectorIndex table_size)
	Vector constructor. More...

void	vector_use_with_store (Vector vector, VectorIndex size, vector_item_destroyer destroyer, void *store[])
	Vector constructor. More...

void	_vector_use_type_with_store (Vector vector, VectorIndex size, Class type, int manage, void *store[])
	Vector constructor. More...

VectorIndex	vector_push_back (Vector vector, void *item)
	Put an item at the end of the Vector. More...

VectorIndex	vector_insert (Vector vector, VectorIndex index, void *item)
	Inserts an item into the vector. More...

void	vector_delete_item (Vector vector, VectorIndex index)
	Deletes an item from the vector. More...

VectorIndex	vector_items (Vector vector)
	Numbers stored in the Vector. More...

void	vector_set_item (Vector vector, VectorIndex index, void *item)
	Overwrites an item. More...

void *	vector_get_item (Vector vector, VectorIndex index)
	Retrieves an item. More...

void	vector_swap (Vector vector, VectorIndex index1, VectorIndex index2)
	Swaps two items in the Vector. More...

void	vector_foreach (Vector vector, vector_item_executor task, void *param)
	Executes a task for each item in the Vector. More...

VectorIndex	vector_foreach_until_true (Vector vector, vector_item_checker checker, void *param)
	Executes a task for each item until `TRUE`. More...

VectorIndex	vector_find_item (Vector vector, VectorIndex index, vector_item_checker checker, void *param)
	Finds an item in the Vector. More...

VectorIndex	vector_find_item_reverse (Vector vector, VectorIndex index, vector_item_checker checker, void *param)
	Finds an item in the Vector in reverse order. More...

Class	vector_get_type (Vector vector)
	Get the type of the vector. More...

int	vector_get_managed (Vector vector)
	Check if the vector is managed. More...

Detailed Description

Vector class - a standard ooc container.

Vector is a container class, that can hold pointers to any kind of data. Every item stored in the list must work perfectly with the supplied list item destroyer! In practice this means, that you can only store items in the vector that has the same deletion method. There are two types of Vector: typed and non-typed vector. Typed Vector can hold items of a given type or its subtype only, while non-typed Vector can hold any type of data, that conforms to the supplied object destructor. When creating a Vector, a given amount of space, the chunk size (n*sizeof(void*)) is allocated. If the Vector grows above this size, the Vector automatically reallocates the store, increasing by the chunk size.

Note: Vector implementation is thread safe, in the manner, that adding to or deleting items from the Vector will not mesh up the Vector. But the VectorIndices may become invalid if multiple threads modify the same Vector object. As a consecvence the foreach and find methods may behave unexpectedly if an other thread is modifying the Vector! Make your own locking if needed! The same applies to the ooc_duplicate() method for Vector (uses vector_foreach() internally)!

Macro Definition Documentation

#define vector_new_type	(	chunk_size,
		pClass,
		manage
	)

Vector constructor.

Creates a new typed vector.

Parameters

chunk_size	The chunk size of the Vector. This is used as the initial size of the vector, and as a size increment for each reallocation.
pClass	The type of the items in the Vector. (Name of the class.)
manage	`OOC_MANAGE` is the Vector must manage the stored items (delete when destroying the Vector), `!OOC_MANAGE` if you manage those other way.

Returns: The newly created Vector.

Note: This is a convenient macro for _vector_new_type().

#define vector_use_type_with_store	(	vector,
		size,
		pClass,
		manage,
		store
	)

Vector constructor.

Builds a new typed vector from a preallocated block of memory and assigns a static store to it.

Parameters

vector	The location of the VectorObject to be constructed.
size	The size of the Vector. This is used as the maximal size of the vector.
pClass	The type of the items in the Vector. (Name of the class.)
manage	`TRUE` is the Vector must manage the stored items (release when destroying the Vector), `FALSE` if you manage those other way.
store	The memory block assigned to the Vector that will hold the pointers to the VectorItems. The strore must be statically allocated, and must be large enough to store `size` pieces of VectorItem pointers.

Note: This is a convenient macro for _vector_use_type_with_store().; Recommended in static memory models only (OOC_NO_DYNAMIC_MEM).

See Also: vector_use_with_store()

Typedef Documentation

typedef int(* vector_item_checker)(void *item, void *param)

Vector Item Checker.

See Also: vector_foreach_until_true(), vector_find_item(), vector_find_item_reverse().

typedef void(* vector_item_destroyer)(void *item)

Vector Item Destroyer.

Destroyer for the items stored in the Vector.

See Also: vector_new(),

typedef void(* vector_item_executor)(void *item, void *param)

Vector Item Executor.

See Also: vector_foreach().

typedef size_t VectorIndex

Index for the Vector.

The VectorIndex can be used as an identifier of an item in the Vector. The VectorIndex starts at 0.

Function Documentation

Vector _vector_new_type	(	VectorIndex	chunk_size,
		Class	type,
		int	manage
	)

Vector constructor.

Creates a new typed vector.

Parameters

chunk_size	The chunk size of the Vector. This is used as the initial size of the vector, and as a size increment for each reallocation.
type	The type of the items in the Vector. (Class Table pointer.)
manage	`OOC_MANAGE` is the Vector must manage the stored items (delete when destroying the Vector), `!OOC_MANAGE` if you manage those other way.

Returns: The newly created Vector.

See Also: vector_new_type().

void _vector_use_type_with_store	(	Vector	vector,
		VectorIndex	size,
		Class	type,
		int	manage,
		void *	store[]
	)

Vector constructor.

Builds a new typed vector from a preallocated block of memory and assigns a static store to it.

Parameters

vector	The location of the VectorObject to be constructed.
size	The size of the Vector. This is used as the maximal size of the vector.
type	The type of the items in the Vector. (Class Table pointer.)
manage	`TRUE` is the Vector must manage the stored items (release when destroying the Vector), `FALSE` if you manage those other way.
store	The memory block assigned to the Vector that will hold the pointers to the VectorItems. The strore must be statically allocated, and must be large enough to store `size` pieces of VectorItem pointers.

Note: Recommended in static memory models only (OOC_NO_DYNAMIC_MEM).

See Also: vector_use_type_with_store(), vector_use_with_store()

void vector_delete_item	(	Vector	vector,
		VectorIndex	index
	)

Deletes an item from the vector.

Deletes an item from the Vector at the index. The rest of the Vector is shifted.

Parameters

vector	The vector.
index	The point where to delete the item from the Vector. For managed vectors or if destroyer supplied, the item is destroyed as well.

Note: Because of the memory move, this operation can be time consuming!

VectorIndex vector_find_item	(	Vector	vector,
		VectorIndex	index,
		vector_item_checker	checker,
		void *	param
	)

Finds an item in the Vector.

Executes the checker task for each item in the vector, starting from position index, until the checker returns TRUE. (If checker returns FALSE then will continue with the next item in the vector, otherwise the execution will stop.)

Parameters

vector	The Vector
index	The starting position of the search.
checker	The checker to be executed. The `checker` is a C function, and must have two parameters: the first will point to the item, the second holpd the parameter. This is a normal way of calling a class method too. The `checker` must return `TRUE` if we found the item or `FALSE` otherwise.
param	The second parameter to be passed to the `checker`.

Returns: The position index of the item if found (for which the checker returned TRUE). If the checker did not returned TRUE, the return value is an index value pointing behind the last item in the vector (== vector_items(), an invalid index!)

Note: You must not modify the vector itself in the task (e.g. deleting an item, etc.).; This is a linear search, that may be slow for large Vectors.

See Also: vector_find_item_reverse(), vector_foreach_until_true()

VectorIndex vector_find_item_reverse	(	Vector	vector,
		VectorIndex	index,
		vector_item_checker	checker,
		void *	param
	)

Finds an item in the Vector in reverse order.

Executes the checker task for each item in the vector in reverse order, starting from position index, until the checker returns TRUE. (If checker returns FALSE then will continue with the next item in the vector, otherwise the execution will stop.)

Parameters

vector	The Vector
index	The starting position of the search.
checker	The checker to be executed. The `checker` is a C function, and must have two parameters: the first will point to the item, the second holds the parameter. This is a normal way of calling a class method too. The `checker` must return `TRUE` if we found the item or `FALSE` otherwise.
param	The second parameter to be passed to the `checker`.

Returns: The position index of the item if found (for which the checker returned TRUE). If the checker did not returned TRUE, the return value is an index value pointing behind the last item in the vector (== vector_items(), an invalid index!)

Note: You must not modify the vector itself in the task (e.g. deleting an item, etc.).; This is a linear search, that may be slow for large Vectors.

See Also: vector_find_item(), vector_foreach_until_true()

void vector_foreach	(	Vector	vector,
		vector_item_executor	task,
		void *	param
	)

Executes a task for each item in the Vector.

Parameters

vector	The Vector
task	The task to be executed. The task is a C function, and must have two parameters: the first will point to the item, the second holpd the parameter. This is a normal way of calling a class method too.
param	The second parameter to be passed to the `task`.

Note: You must not modify the vector itself in the task (e.g. deleting an item, etc.).

VectorIndex vector_foreach_until_true	(	Vector	vector,
		vector_item_checker	checker,
		void *	param
	)

Executes a task for each item until TRUE.

Executes the checker task for each item in the vector, until the checker returns TRUE. (If checker returns FALSE then will continue with the next item in the vector, otherwise the execution will stop.)

Parameters

vector	The Vector
checker	The task to be executed. The `checker` is a C function, and must have two parameters: the first will point to the item, the second holpd the parameter. This is a normal way of calling a class method too. The `checker` must return `TRUE` or @ FALSE.
param	The second parameter to be passed to the `checker`.

Returns: The position index of the last checked item (for which the checker returned TRUE). If the checker did not returned TRUE, the return value is an index value pointing behind the last item in the vector (== vector_items(), an invalid index!)

Note: You must not modify the vector itself in the task (e.g. deleting an item, etc.).

See Also: vector_find_item(), vector_find_item_reverse()

void* vector_get_item	(	Vector	vector,
		VectorIndex	index
	)

Retrieves an item.

Gets the item at position index. The item is not removed from the Vector and is still maintained by it.

Parameters

vector	The Vector.
index	Position.

Returns: Pointer to the item.

int vector_get_managed ( Vector vector )

Check if the vector is managed.

Check is the items in the vector are managed by the vector.

Parameters

vector The vector

Returns: OOC_MANAGE if managed vector, !OOC_MANAGE if not.

See Also: vector_new(), vector_new_type()

Class vector_get_type ( Vector vector )

Get the type of the vector.

Returns the type of the vector in case of a typed vector.

Parameters

vector The vector

Returns: The Class pointer in case of a typed vector, otherwise NULL;

See Also: vector_new_type()

VectorIndex vector_insert	(	Vector	vector,
		VectorIndex	index,
		void *	item
	)

Inserts an item into the vector.

Inserts an item into the Vector at the index. The rest of the Vector is shifted.

Parameters

vector	The vector.
index	The point to insert the item. The new item will be accessed at index.
item	The item to insert.

Note: Because of the memory move, this operation can be time consuming! For typed Vectors type check is performed. In case of type failure a Exception(err_bad_cast)) exception is thrown.

VectorIndex vector_items ( Vector vector )

Numbers stored in the Vector.

Parameters

vector The vector.

Returns: The number of items stored in the Vector. (This is the number of items you really put into the vector, and not the size of the allocation chunks!)

Vector vector_new	(	VectorIndex	chunk_size,
		vector_item_destroyer	destroyer
	)

Vector constructor.

Creates a new non-typed vector.

Parameters

chunk_size	The chunk size of the Vector. This is used as the initial size of the vector, and as a size increment for each reallocation.
destroyer	The destructor for the items stored in the Vector (usually ooc_free() or ooc_delete()). You can pass `NULL` if you store static items in the Vector, or you take care of the item's deletion other way.

Returns: The newly created Vector.

Vector vector_new_from_table	(	void *	table,
		size_t	record_size,
		VectorIndex	table_size
	)

Vector constructor.

Creates a new non-typed Vector from a data table. All items in the Vector are treated static, they are not freed when destroying Vector.

Parameters

table	The source table.
record_size	The record size in the table.
table_size	The number of records in the table.

Returns: The newly created Vector.

VectorIndex vector_push_back	(	Vector	vector,
		void *	item
	)

Put an item at the end of the Vector.

Parameters

vector	The vector.
item	The item to be put.

Note: For typed Vectors type check is performed. In case of type failure a Exception(err_bad_cast)) exception is thrown.

void vector_set_item	(	Vector	vector,
		VectorIndex	index,
		void *	item
	)

Overwrites an item.

Overwrites an item at index.

Parameters

vector	The vector.
index	The position in the vector.
item	The item to put in the vector.

Note: The previous item at this position is destroyed, if destroyer was supplied, or managed is set for typed Vector. The other items are not moved.

void vector_swap	(	Vector	vector,
		VectorIndex	index1,
		VectorIndex	index2
	)

Swaps two items in the Vector.

Parameters

vector	The Vector.
index1	First position to be swapped.
index2	Second position to be swapped.

void vector_use_with_store	(	Vector	vector,
		VectorIndex	size,
		vector_item_destroyer	destroyer,
		void *	store[]
	)

Vector constructor.

Builds a new non-typed vector from a preallocated block of memory and assigns a static store to it.

Parameters

vector	The location of the VectorObject to be constructed.
size	The size of the Vector. This is used as the maximal size of the vector.
destroyer	The destructor for the items stored in the Vector (usually ooc_release()). You can pass `NULL` if you store static items in the Vector, or you take care of releasing the item's other way.
store	The memory block assigned to the Vector that will hold the pointers to the VectorItems. The strore must be statically allocated, and must be large enough to store `size` pieces of `void*` . #define MY_VECTOR_SIZE 13 VectoItem myVectorStore[ MY_VECTOR_SIZE ]; struct VectorObject myVector; vector_use_with_store( & myVector, MY_VECTOR_SIZE, NULL, myVectorStore );

Note: Recommended in static memory models only (OOC_NO_DYNAMIC_MEM).

See Also: vector_use_type_with_store()

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation