maxdz Software GmbH

mdz_vector Overview and Reference

Please refer to mdz_vector Wiki for API details.

mdz_vector Advantages

1. Very high portability: the whole code conforms to ANSI C 89/90 Standard. Multithreading/asynchronous part is POSIX compatible (under UNIX/Linux).

2. Very little dependencies: basically, mdz_vector functions are only dependent on standard C-library memory-management/access functions. Multithreading part is dependent on POSIX pthreads API (under UNIX/Linux) and old process control/synchronization API (from Windows 2000). It means you can use library in your code without any further dependencies except standard platform libraries/APIs.

3. Very fast: comparison tables are coming soon...

4. Flexibilty: nearly all functions contain not only "left position" but also "right position" parameters to limit processed area from right. Vector contains more functions than according STL, boost or glib analogs have.

5. Extended error-checking: all functions preserve internal error-code pointing the problem. It is possible to use strict error-checking (when all preserved error-codes should be MDZ_ERROR_NONE) or "relaxed"-checking - when only returned mdz_false will indicate error.

6. Extended control: vector does only explicit operations. It means for example, when "insert" function is called - it will return error if there is not enough capacity in vector. No implicit reservations will be made.

7. Attached usage: vector should not necessarily use dynamically-allocated memory - which may be not available on your embedded system (or if malloc()/free() are forbidden to use in you safety-critical software). Just attach vector/data to your statically-allocated memory and use all vector functionality.

8. Asynchronous execution: almost all functions can be executed asynchronously.

mdz_vector General Information and Functions

mdz_vector is dynamically-sized contiguous container.

Capacity - how many items memory is reserved for.
Size - how many items are actually residing in a vector.

"reserve/AndReserve" functions allocate/reallocate memory dynamically using malloc()/realloc().
"attach" functionality allows attaching contiguous block of memory to vector, for using vector functions on it.

Library init functions:

mdz_vector_init
mdz_vector_init_attached
mdz_vector_uninit
mdz_vector_create
mdz_vector_create_attached
mdz_vector_destroy
mdz_vector_clear
mdz_vector_attachData

Reserve capacity functions:

mdz_vector_reserve
mdz_vector_reserveAndInit
mdz_vector_capacity
mdz_vector_size
mdz_vector_resize
mdz_vector_offsetFromStart
mdz_vector_isAttachedData

Insert/remove functions:

mdz_vector_insert
mdz_vector_append
mdz_vector_removeFrom
mdz_vector_remove
mdz_vector_trimLeft
mdz_vector_trimRight
mdz_vector_trim

Find functions:

mdz_vector_findSingle
mdz_vector_find
mdz_vector_firstOf
mdz_vector_firstNotOf
mdz_vector_rfindSingle
mdz_vector_rfind
mdz_vector_lastOf
mdz_vector_lastNotOf

Miscellaneous functions:

mdz_vector_compare
mdz_vector_replace
mdz_vector_count
mdz_vector_copySubVector
mdz_vector_copySubVectorFrom

mdz_vector_init

Initializes vector library. This function should be called before any other function of the library.

mdz_bool mdz_vector_init(const uint32_t* pFirstNameHash, const uint32_t* pLastNameHash, const uint32_t* pEmailHash, const uint32_t* pLicenseHash);

mdz_vector_init_attached

Initializes vector library. This function should be caled before any other function of the library.
Memory for license data starts at position pStart. Size of internal initialization structure is returned in pSize.

mdz_bool mdz_vector_init_attached(const uint32_t* pFirstNameHash, const uint32_t* pLastNameHash, const uint32_t* pEmailHash, const uint32_t* pLicenseHash, const char* pStart, size_t nAreaSize, size_t* pOutSize);

mdz_vector_uninit

Un-initializes vector library and frees corresponding memory allocations.

void mdz_vector_uninit(void);

mdz_vector_create

Create empty vector with Capacity and Size 0. Memory for vector structure is allocated using malloc().

struct mdz_Vector* mdz_vector_create(size_t nTypeSize);

mdz_vector_create_attached

Create empty vector with Capacity and Size 0. Memory for vector structure starts at position pStart. Size in bytes of internal vector structure (it is usually bigger than mdz_Vector!) is returned in pSize.

struct mdz_Vector* mdz_vector_create_attached(size_t nTypeSize, const void* pStart, size_t* pSize);

mdz_vector_destroy

Destroy vector including underlying data using free().
If vector is attached using mdz_vector_create_attached(), vector controlling data will not be destroyed.
If vector data is attached using mdz_vector_attachData(), m_pData will not be destroyed.

void mdz_vector_destroy(const struct mdz_Vector* pVector);

mdz_vector_clear

Clear m_pData of vector with setting Size in 0.

void mdz_vector_clear(struct mdz_Vector* pVector);

mdz_vector_attachData

Attach pre-allocated data to vector, assigning pData to m_pData. If attached, m_pData will not be destroyed in mdz_vector_destroy()

mdz_bool mdz_vector_attachData(struct mdz_Vector* pVector, void* pData, size_t nOffsetFromStart, size_t nCapacity, enum mdz_attach_type enAttachType);

mdz_vector_reserve

Reserve nNewCapacity items for vector. Vector Size does not change. Reservation is not made if m_pData is attached using mdz_vector_attachData()

mdz_bool mdz_vector_reserve(struct mdz_Vector* pVector, size_t nNewCapacity);

mdz_vector_reserveAndInit

Reserve nNewCapacity items for vector and initializes all items in pItem. May be called only on empty vectors (with Size == 0). After call, vector Size equals to Capacity.
Reservation is not made if m_pData is attached using mdz_vector_attachData() and nNewCapacity > Capacity

mdz_bool mdz_vector_reserveAndInit(struct mdz_Vector* pVector, size_t nNewCapacity, const void* pItem);

mdz_vector_capacity

Return vector Capacity in items.

size_t mdz_vector_capacity(const struct mdz_Vector* pVector);

mdz_vector_size

Return vector Size in items.

size_t mdz_vector_size(const struct mdz_Vector* pVector);

mdz_vector_resize

Set vector Size. Size must be <= Capacity.

mdz_bool mdz_vector_resize(struct mdz_Vector* pVector, size_t nNewSize);

mdz_vector_offsetFromStart

Return vector OffsetFromStart in items.

size_t mdz_vector_offsetFromStart(const struct mdz_Vector* pVector);

mdz_vector_isAttachedData

Return if vector data is attached.

mdz_bool mdz_vector_isAttachedData(const struct mdz_Vector* pVector);

mdz_vector_insert

Insert nCount items in vector. Capacity should contain enough free space for nCount items. Vector m_pData and pItems cannot overlap. Size grows on nCount.

mdz_bool mdz_vector_insert(struct mdz_Vector* pVector, size_t nLeftPos, const void* pItems, size_t nCount, mdz_bool bReserve);

mdz_vector_append

Appends nCount items in vector. Capacity should contain enough free space for nCount items. Vector m_pData and pItems cannot overlap. Size grows on nCount.

mdz_bool mdz_vector_append(struct mdz_Vector* pVector, const void* pItems, size_t nCount, mdz_bool bReserve);

mdz_vector_findSingle

Find first occurrence of pItem in vector. Returns 0-based position of match (if found), or vector Size if not found, or SIZE_MAX if error.

size_t mdz_vector_findSingle(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItem);

mdz_vector_find

Find first occurrence of pItems in vector. Returns 0-based position of match (if found), or vector Size if not found, or SIZE_MAX if error.

size_t mdz_vector_find(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItems, size_t nCount, enum mdz_find_method enFindMethod);

mdz_vector_firstOf

Find first occurrence of any item of pItems in vector. Returns 0-based position of match (if found), or vector Size if not found, or SIZE_MAX if error.

size_t mdz_vector_firstOf(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItems, size_t nCount);

mdz_vector_firstNotOf

Find first non-occurrence of any item of pItems in vector. Returns 0-based position of match (if found), or vector Size if not found, or SIZE_MAX if error.

size_t mdz_vector_firstNotOf(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItems, size_t nCount);

mdz_vector_rfindSingle

Find last occurrence of pItem in vector. Returns 0-based position of match (if found), or vector Size if not found, or SIZE_MAX if error.

size_t mdz_vector_rfindSingle(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItem);

mdz_vector_rfind

Find last occurrence of pItems in vector. Returns 0-based position of match (if found), or vector Size if not found, or SIZE_MAX if error.

size_t mdz_vector_rfind(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItems, size_t nCount, enum mdz_find_method enFindMethod);

mdz_vector_lastOf

Find last occurrence of any item of pItems in vector. Returns 0-based position of match (if found), or vector Size if not found, or SIZE_MAX if error.

size_t mdz_vector_lastOf(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItems, size_t nCount);

mdz_vector_lastNotOf

Find last non-occurrence of any item of pItems in vector. Returns 0-based position of match (if found), or vector Size if not found, or SIZE_MAX if error.

size_t mdz_vector_lastNotOf(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItems, size_t nCount);

mdz_vector_removeFrom

Remove nCount item(s) starting from 0-based nLeftPos position. After the operation, Capacity doesn't change, Size decreases on nCount.

mdz_bool mdz_vector_removeFrom(struct mdz_Vector* pVector, size_t nLeftPos, size_t nCount);

mdz_vector_remove

Remove all occurrences of nCount item(s) matching to pItems, residing between nLeftPos and nRightPos. Vector m_pData and pItems cannot overlap. After remove(s) Capacity doesn't change, Size decreases on nCount of removed items.

mdz_bool mdz_vector_remove(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItems, size_t nCount);

mdz_vector_trimLeft

Remove items which are contained in pItems from left, until first non-contained in pItems item is reached. Vector m_pData and pItems cannot overlap.

mdz_bool mdz_vector_trimLeft(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItems, size_t nCount);

mdz_vector_trimRight

Remove items which are contained in pItems from right, until first non-contained in pItems item is reached. Vector m_pData and pItems cannot overlap.

mdz_bool mdz_vector_trimRight(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItems, size_t nCount);

mdz_vector_trim

Remove items which are contained in pItems from left and from right, until first non-contained in pItems item is reached. Vector m_pData and pItems cannot overlap.

mdz_bool mdz_vector_trim(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItems, size_t nCount);

mdz_vector_compare

Compare content of vector with pItems.

enum mdz_compare_result mdz_vector_compare(struct mdz_Vector* pVector, size_t nLeftPos, const void* pItems, size_t nCount);

mdz_vector_replace

Replace every occurrence of pItemsBefore with pItemsAfter. There should be enough Capacity for replacing data. Vector m_pData and pItemsBefore/pItemsAfter cannot overlap.

mdz_bool mdz_vector_replace(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItemsBefore, size_t nCountBefore, const void* pItemsAfter, size_t nCountAfter, mdz_bool bReserve);

mdz_vector_count

Counts number of pItems subvector occurrences in vector.

size_t mdz_vector_count(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pItems, size_t nCount, mdz_bool bAllowOverlapped);

mdz_vector_copySubVector

Fills pSubVector with items, starting from nLeftPos and ending with one of pSeparators or nRightPos.

size_t mdz_vector_copySubVector(struct mdz_Vector* pVector, size_t nLeftPos, size_t nRightPos, const void* pSeparators, size_t nSeparatorsCount, struct mdz_Vector* pSubVector);

mdz_vector_copySubVectorFrom

Fills pSubVector with items, starting from nLeftPos and containing nCount items.

size_t mdz_vector_copySubVectorFrom(struct mdz_Vector* pVector, size_t nLeftPos, size_t nCount, struct mdz_Vector* pSubVector);