maxdz Software GmbH

mdz_ansi_16 Overview and Reference

mdz_ansi_16 Advantages

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

2. Minimal Dependencies: mdz_ansi_16 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.

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. No Memory Overhead: The functions are designed to process input data without making internal memory allocations or using dynamic memory.

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

mdz_ansi_16 General Information and Functions

mdz_ansi_16 is library for contiguous single-byte String, containing ASCII (0..127) and "ANSI" (128 - 255) characters.
Dynamic memory-allocations inside library functions are only possible, if according allocation functions are set by user.

String can be dynamically allocated or attached to static/pre-allocated char
buffer.

String - contains metadata like Size, Capacity, etc. and Data consisting of Items. String may contain 0-terminators ('\0') inside, and MUST end with 0-terminator.
Item - single element/character of String or of buffer passed as parameter for insertion, removing, find, etc. For this single-byte String Item is always a byte.
Capacity - how many Items is reserved for String content. Capacity does NOT include ending 0-terminator byte.
Size - how many Items are actually residing in a String.

Init functions:

mdz_ansi_16_init
mdz_ansi_16_setAllocFunctions
mdz_ansi_16_create
mdz_ansi_16_fromText
mdz_ansi_16_attach
mdz_ansi_16_destroy
mdz_ansi_16_clear

Status functions:

mdz_ansi_16_minBufferSize
mdz_ansi_16_maxCapacity
mdz_ansi_16_size
mdz_ansi_16_capacity
mdz_ansi_16_data
mdz_ansi_16_dataConst

Insert/remove functions:

mdz_ansi_16_reserve
mdz_ansi_16_insert
mdz_ansi_16_append
mdz_ansi_16_removeFrom
mdz_ansi_16_remove
mdz_ansi_16_trimLeft
mdz_ansi_16_trimRight
mdz_ansi_16_trim

Find functions:

mdz_ansi_16_findSingle
mdz_ansi_16_find
mdz_ansi_16_rfindSingle
mdz_ansi_16_rfind
mdz_ansi_16_firstOf
mdz_ansi_16_firstNotOf
mdz_ansi_16_lastOf
mdz_ansi_16_lastNotOf

Miscellaneous functions:

mdz_ansi_16_equal
mdz_ansi_16_compare
mdz_ansi_16_count
mdz_ansi_16_replace
mdz_ansi_16_reverse

mdz_ansi_16_init

Initializes mdz_ansi_16 library and license. This function should be called before any other function of the library.

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

mdz_ansi_16_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_16_setAllocFunctions(mdz_AllocFunc pAllocFunc, mdz_ReallocFunc pReallocFunc, mdz_FreeFunc pFreeFunc);

mdz_ansi_16_create

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

mdz_Ansi16* mdz_ansi_16_create(unsigned short nCapacity, enum mdz_error* penError);

mdz_ansi_16_fromText

Create String including pcText with 0-terminator. This function uses dynamic-memory allocator malloc() function set in mdz_ansi_16_setAllocFunctions()

mdz_Ansi16* mdz_ansi_16_fromText(const char* pcText, size_t nLength, enum mdz_error* penError);

mdz_ansi_16_attach

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

mdz_Ansi16* mdz_ansi_16_attach(char* pcBuffer, unsigned short nBufferSize, enum mdz_error* penError);

mdz_ansi_16_destroy

Destroy String. If String is created using mdz_ansi_16_create() - free() function set in mdz_ansi_16_setAllocFunctions() will be used for destroying.

enum mdz_error mdz_ansi_16_destroy(mdz_Ansi16* psAnsi);

mdz_ansi_16_clear

Clear Data of String with setting Size to 0.

void mdz_ansi_16_clear(struct mdz_Ansi16* psAnsi);

mdz_ansi_16_minBufferSize

Return size of minimal buffer for attachment using mdz_ansi_16_attach(). Capacity of such a String is 0

unsigned short mdz_ansi_16_minBufferSize(void);

mdz_ansi_16_maxCapacity

Return size of maximal Capacity

unsigned short mdz_ansi_16_maxCapacity(void);

mdz_ansi_16_size

Return Size of String Data in Items

unsigned short mdz_ansi_16_size(const mdz_Ansi16* psAnsi);

mdz_ansi_16_capacity

Return Capacity of string Data in Items

unsigned short mdz_ansi_16_capacity(const mdz_Ansi16* psAnsi);

mdz_ansi_16_data

Return pointer to String Data.

char* mdz_ansi_16_data(mdz_Ansi16* psAnsi);

mdz_ansi_16_dataConst

Return const pointer to string Data.

const char* mdz_ansi_16_dataConst(const mdz_Ansi16* psAnsi);

mdz_ansi_16_reserve

Reserve nNewCapacity for String using realloc() function set in mdz_ansi_16_setAllocFunctions(). String Size does not change.

enum mdz_error mdz_ansi_16_reserve(mdz_Ansi16** ppsAnsi, unsigned short nNewCapacity);

mdz_ansi_16_insert

Insert pcItems into Data from nLeftPos position. Data and pcItems cannot overlap. New Size is written in psAnsi.

enum mdz_error mdz_ansi_16_insert(mdz_Ansi16** ppsAnsi, unsigned short nLeftPos, const char* pcItems, size_t nCount, mdz_bool bReserve);

mdz_ansi_16_append

Append pcItems to Data. Data and pcItems cannot overlap. New Size is written in psAnsi.

enum mdz_error mdz_ansi_16_append(mdz_Ansi16** ppsAnsi, const char* pcItems, size_t nCount, mdz_bool bReserve);

mdz_ansi_16_findSingle

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

unsigned short mdz_ansi_16_findSingle(const mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, char cItem, enum mdz_error* penError);

mdz_ansi_16_find

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

unsigned short mdz_ansi_16_find(const mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_16_rfindSingle

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

unsigned short mdz_ansi_16_rfindSingle(const mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, char cItem, enum mdz_error* penError);

mdz_ansi_16_rfind

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

unsigned short mdz_ansi_16_rfind(const mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_16_firstOf

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

unsigned short mdz_ansi_16_firstOf(const mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_16_firstNotOf

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

unsigned short mdz_ansi_16_firstNotOf(const mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_16_lastOf

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

unsigned short mdz_ansi_16_lastOf(const mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_16_lastNotOf

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

unsigned short mdz_ansi_16_lastNotOf(const mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_16_removeFrom

Remove nCount Items starting from 0-based nLeftPos position

enum mdz_error mdz_ansi_16_removeFrom(mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nCount);

mdz_ansi_16_remove

Remove all ocurrences of pcItems with lenth nCount, residing between nLeftPos and nRightPos

enum mdz_error mdz_ansi_16_remove(mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItems, size_t nCount, mdz_bool bFromLeft);

mdz_ansi_16_trimLeft

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

enum mdz_error mdz_ansi_16_trimLeft(mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItems, size_t nCount);

mdz_ansi_16_trimRight

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

enum mdz_error mdz_ansi_16_trimRight(mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItems, size_t nCount);

mdz_ansi_16_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_16_trim(mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItems, size_t nCount);

mdz_ansi_16_equal

Compare content of Data with pcItems on equalty by length and content. If penError is not NULL, error will be written there

enum mdz_ansi_compare_result mdz_ansi_16_equal(const mdz_Ansi16* psAnsi, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_16_compare

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

enum mdz_ansi_compare_result mdz_ansi_16_compare(const mdz_Ansi16* psAnsi, unsigned short nLeftPos, const char* pcItems, size_t nCount, enum mdz_error* penError);

mdz_ansi_16_count

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

size_t mdz_ansi_16_count(const mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItems, size_t nCount, mdz_bool bAllowOverlapped, mdz_bool bFromLeft, enum mdz_error* penError);

mdz_ansi_16_replace

Replace every occurence of pcItemsBefore with pcItemsAfter in Data. There should be enough Capacity for replacing data.

enum mdz_error mdz_ansi_16_replace(mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos, const char* pcItemsBefore, size_t nCountBefore, const char* pcItemsAfter, size_t nCountAfter, mdz_bool bFromLeft, enum mdz_ansi_replace_type enReplacementType);

mdz_ansi_16_reverse

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

enum mdz_error mdz_ansi_16_reverse(mdz_Ansi16* psAnsi, unsigned short nLeftPos, unsigned short nRightPos);