ooc 1.3
Object Oriented tollkit fo ANSI C

vector.h File Reference

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

#include "ooc.h"
Include dependency graph for vector.h:

Defines

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

Typedefs

typedef struct VectorObject * Vector
 Vector class declaration.
typedef size_t VectorIndex
 Index for the Vector.
typedef void(* vector_item_destroyer )(void *item)
 Vector Item Destroyer.
typedef void(* vector_item_executor )(void *item, void *param)
 Vector Item Executor.
typedef int(* vector_item_checker )(void *item, void *param)
 Vector Item Checker.

Functions

Vector vector_new (VectorIndex chunk_size, vector_item_destroyer destroyer)
 Vector constructor.
Vector _vector_new_type (VectorIndex chunk_size, Class type, int manage)
 Vector constructor.
Vector vector_new_from_table (void *table, size_t record_size, VectorIndex table_size)
 Vector constructor.
void vector_use_with_store (Vector vector, VectorIndex size, vector_item_destroyer destroyer, void *store[])
 Vector constructor.
void _vector_use_type_with_store (Vector vector, VectorIndex size, Class type, int manage, void *store[])
 Vector constructor.
VectorIndex vector_push_back (Vector vector, void *item)
 Put an item at the end of the Vector.
VectorIndex vector_insert (Vector vector, VectorIndex index, void *item)
 Inserts an item into the vector.
void vector_delete_item (Vector vector, VectorIndex index)
 Deletes an item from the vector.
VectorIndex vector_items (Vector vector)
 Numbers stored in the Vector.
void vector_set_item (Vector vector, VectorIndex index, void *item)
 Overwrites an item.
void * vector_get_item (Vector vector, VectorIndex index)
 Retrieves an item.
void vector_swap (Vector vector, VectorIndex index1, VectorIndex index2)
 Swaps two items in the Vector.
void vector_foreach (Vector vector, vector_item_executor task, void *param)
 Executes a task for each item in the Vector.
VectorIndex vector_foreach_until_true (Vector vector, vector_item_checker checker, void *param)
 Executes a task for each item until TRUE.
VectorIndex vector_find_item (Vector vector, VectorIndex index, vector_item_checker checker, void *param)
 Finds an item in the Vector.
VectorIndex vector_find_item_reverse (Vector vector, VectorIndex index, vector_item_checker checker, void *param)
 Finds an item in the Vector in reverse order.

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)!

Define Documentation

#define vector_new_type (   chunk_size,
  pClass,
  manage 
)

Vector constructor.

Creates a new typed vector.

Parameters:
chunk_sizeThe chunk size of the Vector. This is used as the initial size of the vector, and as a size increment for each reallocation.
pClassThe type of the items in the Vector. (Name of the class.)
manageOOC_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:
vectorThe location of the VectorObject to be constructed.
sizeThe size of the Vector. This is used as the maximal size of the vector.
pClassThe type of the items in the Vector. (Name of the class.)
manageTRUE is the Vector must manage the stored items (release when destroying the Vector), FALSE if you manage those other way.
storeThe 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)
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_sizeThe chunk size of the Vector. This is used as the initial size of the vector, and as a size increment for each reallocation.
typeThe type of the items in the Vector. (Class Table pointer.)
manageOOC_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:
vectorThe location of the VectorObject to be constructed.
sizeThe size of the Vector. This is used as the maximal size of the vector.
typeThe type of the items in the Vector. (Class Table pointer.)
manageTRUE is the Vector must manage the stored items (release when destroying the Vector), FALSE if you manage those other way.
storeThe 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:
vectorThe vector.
indexThe 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:
vectorThe Vector
indexThe starting position of the search.
checkerThe 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.
paramThe 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:
vectorThe Vector
indexThe starting position of the search.
checkerThe 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.
paramThe 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:
vectorThe Vector
taskThe 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.
paramThe 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:
vectorThe Vector
checkerThe 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.
paramThe 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:
vectorThe Vector.
indexPosition.
Returns:
Pointer to the item.
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:
vectorThe vector.
indexThe point to insert the item. The new item will be accessed at index.
itemThe 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:
vectorThe 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_sizeThe chunk size of the Vector. This is used as the initial size of the vector, and as a size increment for each reallocation.
destroyerThe 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:
tableThe source table.
record_sizeThe record size in the table.
table_sizeThe 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:
vectorThe vector.
itemThe 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:
vectorThe vector.
indexThe position in the vector.
itemThe 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:
vectorThe Vector.
index1First position to be swapped.
index2Second 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:
vectorThe location of the VectorObject to be constructed.
sizeThe size of the Vector. This is used as the maximal size of the vector.
destroyerThe 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.
storeThe 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()
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines