maxdz Software GmbH

mdz_ansi_dyn Overview and Reference

mdz_ansi_dyn Advantages

1. High Portability: The entire codebase conforms to the ANSI C 89/90 standard.

2. Minimal Dependencies: mdz_ansi_dyn functions solely depend on standard C-library functions. This means you can integrate the library into your code without any additional dependencies beyond the standard platform libraries/APIs.

3. Performance: The library functions are highly optimized for speed, particularly for operations like searching. Especially when processing very large string (e.g., hundreds of megabytes or gigabytes).

4. Flexibilty: Most library functions offer both "left position" and "right position" parameters, allowing you to limit the processing area. Additionally, the library provides more string functions than comparable libraries such as STL, Boost, or GLib.

5. Extended Error-Checking: All functions use strict error-checking mechanisms and return specific error codes pointing the problem precisely.

6. Extended Control: The functions perform only explicit operations. For example, when an "insert" function is called, it will return an error if there is not enough capacity in string - no implicit memory allocations/reservations will be made.

7. Optional dynamic memory: There is possibility to set dynamic memory management functions like malloc, realloc, free to use dynamic memory for storing/processing very long strings.

8. Metadata encapsulated: String controls its Size and Capacity, thus making automatical checking and if necessary adjustment during each string function call.

mdz_ansi_dyn General Information and Functions

mdz_ansi_dyn is dynamically-sized contiguous single-byte string, containing ASCII (0..127) and "ANSI" (128 - 255) characters.

String may contain 0-terminators ('\0') inside, and must end with 0-terminator.

Capacity - how many bytes of memory is reserved for string content.
Size - how many characters are actually residing in a string.

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

Init/destroy functions:

mdz_ansi_dyn_init
mdz_ansi_dyn_setAllocFunctions
mdz_ansi_dyn_create
mdz_ansi_dyn_attach
mdz_ansi_dyn_destroy

Status functions:

mdz_ansi_dyn_sizeMetadata
mdz_ansi_dyn_size
mdz_ansi_dyn_capacity
mdz_ansi_dyn_data
mdz_ansi_dyn_dataConst

Insert/remove functions:

mdz_ansi_dyn_insert
mdz_ansi_dyn_removeFrom
mdz_ansi_dyn_remove
mdz_ansi_dyn_trimLeft
mdz_ansi_dyn_trimRight
mdz_ansi_dyn_trim

Find functions:

mdz_ansi_dyn_findSingle
mdz_ansi_dyn_find
mdz_ansi_dyn_rfindSingle
mdz_ansi_dyn_rfind
mdz_ansi_dyn_firstOf
mdz_ansi_dyn_firstNotOf
mdz_ansi_dyn_lastOf
mdz_ansi_dyn_lastNotOf

Miscellaneous functions:

mdz_ansi_dyn_compare
mdz_ansi_dyn_count
mdz_ansi_dyn_replace
mdz_ansi_dyn_reverse

mdz_ansi_dyn_init

Initialize mdz_ansi_dyn library and license. This function should be called before any other function of the library.

mdz_bool mdz_ansi_dyn_init(const unsigned long* pnFirstNameHash, const unsigned long* pnLastNameHash, const unsigned long* pnEmailHash, const unsigned long* pnLicenseHash);

mdz_ansi_dyn_setAllocFunctions

Set allocation functions for dynamic memory-management. If functions are not set - library is only using static memory, thus no dynamic memory allocations.

void mdz_ansi_dyn_setAllocFunctions(mdz_AllocFunc pAllocFunc, mdz_ReallocFunc pReallocFunc, mdz_FreeFunc pFreeFunc);

mdz_ansi_dyn_create

Create empty string with Capacity nCapacity and Size 0. This function uses dynamic-memory allocator malloc() function set in mdz_ansi_dyn_setAllocFunctions()

mdz_AnsiDyn* mdz_ansi_dyn_create(size_t nCapacity, enum mdz_error* penError);

mdz_ansi_dyn_attach

Attach string to pre-allocated pcBuffer of nBufferSize bytes. If penError is not NULL, error will be written there

mdz_AnsiDyn* mdz_ansi_dyn_attach(char* pcBuffer, size_t nBufferSize, enum mdz_error* penError);

mdz_ansi_dyn_destroy

Destroy string. If string is created using mdz_ansi_dyn_create() - free() function set in mdz_ansi_dyn_setAllocFunctions() will be used for destroying.

enum mdz_error mdz_ansi_dyn_destroy(mdz_AnsiDyn* psAnsi);

mdz_ansi_dyn_sizeMetadata

Return size of string Metadata

size_t mdz_ansi_dyn_sizeMetadata(void);

mdz_ansi_dyn_size

Return Size of string Data in characters/bytes.

size_t mdz_ansi_dyn_size(const mdz_AnsiDyn* psAnsi);

mdz_ansi_dyn_capacity

Return Capacity of string Data in characters/bytes.

size_t mdz_ansi_dyn_capacity(const mdz_AnsiDyn* psAnsi);

mdz_ansi_dyn_data

Return pointer to string Data.

char* mdz_ansi_dyn_data(mdz_AnsiDyn* psAnsi);

mdz_ansi_dyn_dataConst

Return const pointer to string Data.

const char* mdz_ansi_dyn_dataConst(const mdz_AnsiDyn* psAnsi);

mdz_ansi_dyn_insert

Insert pcItems from nLeftPos position. Data and pcItems cannot overlap. New Size is written in psAnsi. If there is not enouhgh Capacity, realloc() function set in mdz_ansi_dyn_setAllocFunctions() will be used

enum mdz_error mdz_ansi_dyn_insert(mdz_AnsiDyn** ppsAnsi, size_t nLeftPos, const char* pcItems, size_t nCount);

mdz_ansi_dyn_findSingle

Find first occurrence of cItem. Returns 0-based position of match (if found), or SIZE_MAX if not found or error happened. If penError is not NULL, error will be written there

size_t mdz_ansi_dyn_findSingle(const mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, char cItem, enum mdz_error* penError);

mdz_ansi_dyn_find

Find first occurrence of pcItems using optimized Boyer-Moore-Horspool search. Returns 0-based position of match (if found), or SIZE_MAX if not found or error happened. If penError is not NULL, error will be written there

size_t mdz_ansi_dyn_find(const mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_dyn_rfindSingle

Find last occurrence of cItem. Returns 0-based position of match (if found), or SIZE_MAX if not found or error happened. If penError is not NULL, error will be written there

size_t mdz_ansi_dyn_rfindSingle(const mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, char cItem, enum mdz_error* penError);

mdz_ansi_dyn_rfind

Find last occurrence of pcItems using optimized Boyer-Moore-Horspool search. Returns 0-based position of match (if found), or SIZE_MAX if not found or error happened. If penError is not NULL, error will be written there

size_t mdz_ansi_dyn_rfind(const mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_dyn_firstOf

Find first occurrence of any item of pcItems. Returns 0-based position of match (if found), or SIZE_MAX if not found or error happened. If penError is not NULL, error will be written there

size_t mdz_ansi_dyn_firstOf(const mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_dyn_firstNotOf

Find first non-occurrence of any item of pcItems. Returns 0-based position of match (if found), or SIZE_MAX if not found or error happened. If penError is not NULL, error will be written there

size_t mdz_ansi_dyn_firstNotOf(const mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_dyn_lastOf

Find last occurrence of any item of pcItems. Returns 0-based position of match (if found), or SIZE_MAX if not found or error happened. If penError is not NULL, error will be written there

size_t mdz_ansi_dyn_lastOf(const mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_dyn_lastNotOf

Find last non-occurrence of any item of pcItems. Returns 0-based position of match (if found), or SIZE_MAX if not found or error happened. If penError is not NULL, error will be written there

size_t mdz_ansi_dyn_lastNotOf(const mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_dyn_removeFrom

Remove nCount item(s) starting from 0-based nLeftPos position

enum mdz_error mdz_ansi_dyn_removeFrom(mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nCount);

mdz_ansi_dyn_remove

Remove all ocurrences of nCount item(s) matching to pcItems, residing between nLeftPos and nRightPos

enum mdz_error mdz_ansi_dyn_remove(mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItems, size_t nCount, mdz_bool bFromLeft);

mdz_ansi_dyn_trimLeft

Remove items which are contained in pcItems from left, until first non-contained in pcItems item is reached.

enum mdz_error mdz_ansi_dyn_trimLeft(mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItems, size_t nCount);

mdz_ansi_dyn_trimRight

Remove items which are contained in pcItems from right, until first non-contained in pcItems item is reached.

enum mdz_error mdz_ansi_dyn_trimRight(mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItems, size_t nCount);

mdz_ansi_dyn_trim

Remove items which are contained in pcItems from left and from right, until first non-contained in pcItems item is reached.

enum mdz_error mdz_ansi_dyn_trim(mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItems, size_t nCount);

mdz_ansi_dyn_compare

Compare content of Data with pcItems. If penError is not NULL, error will be written there

enum mdz_ansi_compare_result mdz_ansi_dyn_compare(const mdz_AnsiDyn* psAnsi, size_t nLeftPos, const char* pcItems, size_t nCount, mdz_bool bPartialCompare, enum mdz_error* penError);

mdz_ansi_dyn_count

Counts number of pcItems substring occurences in Data. If penError is not NULL, error will be written there

size_t mdz_ansi_dyn_count(const mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItems, size_t nCount, mdz_bool bAllowOverlapped, mdz_bool bFromLeft, enum mdz_error* penError);

mdz_ansi_dyn_replace

Replace every occurence of pcItemsBefore with pcItemsAfter in Data. If there is not enouhgh Capacity, realloc() function set in mdz_ansi_dyn_setAllocFunctions() will be used

enum mdz_error mdz_ansi_dyn_replace(mdz_AnsiDyn** ppsAnsi, size_t nLeftPos, size_t nRightPos, const char* pcItemsBefore, size_t nCountBefore, const char* pcItemsAfter, size_t nCountAfter, mdz_bool bFromLeft, enum mdz_ansi_replace_type enReplacementType);

mdz_ansi_dyn_reverse

Reverses characters in string, like "1234" into "4321".

enum mdz_error mdz_ansi_dyn_reverse(mdz_AnsiDyn* psAnsi, size_t nLeftPos, size_t nRightPos);