CONTAINERS


Include

#include <types.h>
This header also includes <typelib.h> to supply function prototypes for certain data types.

Project Location

src/typelib

Library

containers

Required Libraries

shmem, syslog(debug mode)

Defines

PACKEDUsed after a structure, before the name
PREFIX_PACKEDUsed before struct keyword
CPROCUsed to guarantee a C calling sequence
far,huge,near,_far,_huge,_neardefined for compilers which do not use these deprecated/obsolete types.
TOCHR(n)#n[0]Result in the first character of a symbol name
TOSTR(n)#nconvert a symbol into a string
STRSYM(n)TOSTR(n)convert a defined value into a string (__LINE__), Must be done this way otherwise the resulting string would be "__LINE__"
FILELINE__FILE__ "("STRSYM(__LINE__)") : "Make a string of the current file and line.
TRUE
FALSE
(!FALSE)
(0)
seems some systems lack TRUE/FALSE definitions... so if not previously existing, define them.
FLAGSET(v,n)v = name, n = size of set.defines a set of bits to be used as flags.
SETFLAG(v,n)v = name, n = bit to set.given a set of flags, set a specific bit in the set.
RESETFLAG(v,n)v = name, n = bit to reset.given a set of flags, clear a specific bit in the set.
TESTFLAG(v,n)v = name, n = bit to test.given a set of flags, result true if bit is set.
TOGGLEFLAG(v,n)v = name, n = bit to toggle.given a set of flags, set a specific bit to its opposite state in the set.
DECLDATA(name,size)name of data thing, size of data.Define a structure which is exactly sized to have a certain amount of data. This is used to define struct SimpleDataBlock types.

Types

_88 bit unsigned value.
_1616 bit unsigned value.
uint32_t32 bit unsigned value.
_6464 bit unsigned value.
S_88 bit signed value.
S_1616 bit signed value.
int32_t32 bit signed value.
S_6464 bit signed value.
P_8pointer to an 8 bit unsigned value.
P_16pointer to an 16 bit unsigned value.
uint32_t*pointer to an 32 bit unsigned value.
P_64pointer to an 64 bit unsigned value.
PS_8pointer to an 8 bit signed value.
PS_16pointer to an 16 bit signed value.
PS_32pointer to an 32 bit signed value.
PS_64pointer to an 64 bit signed value.
X_88 bit value (neither signed nor unsigned).
PX_8pointer to an 8 bit value (neither signed nor unsigned).
PTRSZVAL, PTRSIZEVALAn unsigned integer value which is the same size as normal pointers on a system.
CTEXTSTRA constant text string.
TEXTSTRA text string.
TEXTCHARAlias for X_8. Turns out that under certain C++ compilers char is neither equivalent to signed char or unsigned char, therefore this alias had to be created.
LOGICALA boolean/true false type value... many systems defaulted this type to uint32_t bits, and desiring to conserve space, an attempt was made to make this _8... or even a 1 bit field, but it failed, and finally uint32_t was chosen as the type of this.
INDEXAn index into an array - a machine natural unsigned integer value.
POINTERA pointer to void. That's all - just a pointer.
CPOINTERA pointer to void constant data.
THREAD_IDA 64 bit value, upper 32 is ProcessID, lower 32 is ThreadID. Routines for manipulating this are in timers.h (timers library) for now.
DATA, PDATAA simple data block which contains a size followed by an amount of data. PDATA is a pointer to a DATA item.
LIST, PLISTA simple list of pointers. Type dynamically expands. PLIST is a pointer to such a list.
DATALIST, PDATALISTA simple list of sized blocks of data. Type dynamically expands. PDATALIST is a pointer to a DATALIST.
LINKSTACK, PLINKSTACKA stack(LIFO) of pointers, items are pushed on and popped off. PLINKSTACK is a pointer to a LINKSTACK.
DATASTACK, PDATASTACKA stack(LIFO) of data, items are pushed on and popped off. Stack contains blocks of data. PDATASTACK is a pointer to a DATASTACK.
LINKQUEUE, PLINKQUEUEA queue(FIFO) of pointers, items are enqued and dequed. PLINKQUEUE is a pointer to a LINKQUEUE.
DATAQUEUE, PDATAQUEUEA queue(FIFO) of data, items are enqued and dequed. Stack contains blocks of data. PDATAQUEUE is a pointer to a DATAQUEUE.
GENERICSET, *GENERICSETA set of fixed size data items. Elements are slab allocated, and linked together to keep consistant pointers. Data element availability is tracked with a set of bits. This set is often aliased with a set of user defined macros. C++ encapsulation was elegant.
TEXT, PTEXTA text item. It contains length of string, format of data, possibly posistion data, and next/prior text segments. A sentance is actually a linked list of TEXT elements each often representing a word. Several methods of manipuplation of this type exist.
VARTEXT, PVARTEXTA variable text item. Its emphasis is not so much on format/data, but being able to expand dynamically. Used almost exclusively with vtprintf which is a formatted print to print into these elements. VARTEXT generates PTEXT output. PVARTEXT is a pointer to a VARTEXT type.
PTREEROOTA binary tree. The tree has definable comparison, destruction methods.
PTREENODEA node within a binary tree.

Routines

This section is split into functional groups, based on the type of container structure they relate to.

_Ex methods take debug information parameters. These are then passed into the allocate/deallocation routines, so that the user code is credited for the allocation, not these library modules themselves. The _Ex versions may be called, if a routine wishes to actually credit some other code with the allocate/deallocation. If a non Ex version is used, then the current application file-line(DBG_SRC) will be used, and a call will be generated to the Ex function.

All List, DataList, Stack, DataStack, Queue, DataQueue methods are intended multi-thread and even multi-process safe. There is a problem if a structure expands however while the second accesses may be locked out, it cannot be aware of the new location of the list... There will NEVER occur a time that two threads are able to manipulate the structures. Several threads may be reading the structure, and certain methods(macros) like LIST_FORALL() have no locking, another thread MAY delete a list being traversed by this macro. If only actual routines are used, there should be no conflict.


List Methods

There is no enforcement that a list contains pointers of any specific type. Let the user beware. Templates could solve this problem, at the cost of much bloat, when the user should just be aware enough that a specific list is meant to contain a specific type of data.

PLIST CreateListEx( DBG_VOIDPASS )
PLIST CreateList(void)

Creates a simple list which tracks pointers.

PLIST DeleteListEx( PLIST *ppList DBG_PASS )
PLIST DeleteList( PLIST *ppList )

ppList is a pointer to the PLIST to destroy. The result of this will set the PLIST pointer to NULL. The return should always be NULL being the resulting pointer. However, there may be occasions where the list cannot be deleted, and therefore the result will be returned, and the value kept in PLIST.

PLIST AddLinkEx( PLIST *ppList, POINTER p DBG_PASS )
PLIST AddLink( PLIST *ppList, POINTER p )

Adds a pointer into a list. If the pointer is NULL, it will not be added. No NULL values may be stored in this list structure. PLIST* is a pointer to a PLIST. If the list is expanded, then this list reference pointer will be updated to the newly allocated space. The value set into the PLIST* will also be returned.

PLIST SetLinkEx( PLIST *ppList, INDEX idx, POINTER p DBG_PASS )
PLIST SetLink( PLIST *ppList, INDEX idx, POINTER p )

This sets the value of a pointer into a specific index in the list. If the list is not yet large enough to have that value, it will be automatically expanded to accomodate the new value. A NULL value will effectively erase an entry

POINTER GetLink( PLIST *ppList, INDEX idx )

Returns the linked stored in the list at the specified index.

INDEX FindLink( PLIST *ppList, POINTER value )

Searches for all entries in the list, and returns the index of the first item which matches the value specified.

int DeleteLink( PLIST *ppList, POINTER value )

This is effectively the same as SetLink( ppList, FindLink( ppList, value ), NULL ); The result of this call is a boolean TRUE if the value was found and deleted and FALSE if the value was not found to delete.

typedef PTRSVAL (*ForProc)( PTRSZVAL user, INDEX idx, POINTER *item );
PTRSZVAL ForAllLinks( PLIST *ppList, ForProc func, PTRSZVAL psv )

The ForProc callback paramters gets the value specified in (psv) from the call to ForAllLinks; the current index of the item; and a pointer to the memory containing the pointer data for the current link. This allows the callback to set directly into the list any new value. If the callback returns any non-zero value, the looping is aborted, and that value is returned to the caller of ForAllLinks.
A list is passed to be searched, a callback function specified, and a user data value. The result is either 0, or the non-zero result of a call to ForProc().

LIST_FORALL(list, index, type, var)

This is not a function per-se, but a macro wrapper to go through all items in a list. It basically produces a for() loop construct inline. At this time LIST_ENDFORALL() may be omitted, once upon a time it contained closing }'s which were left open by the LIST_FORALL() portion.

list is a PLIST type to go through.
index is a variable of type INDEX which is declared by the caller
type is the type of variable var (for C++ where typecasting must be explicitly done)
var is the name of a variable to get the current value from the list

At the end of the list, (var) SHOULD be NULL. unless there was a break within the loop. If the list is NULL, the variable (var) may not be NULL, and under certain other conditions....

{
   PLIST list;
   INDEX idx;
   P_MY_TYPE myvar;
   LIST_FORALL( list, idx, P_MY_TYPE, myvar )
   {
      // code here can check myvar, which will never be NULL.
   }
}

Data List Methods

PDATALIST CreateDataListEx( int nSize DBG_PASS )
PDATALIST CreateDataList( int nSize )

PDATALIST DeleteDataListEx( PDATALIST *ppDataList DBG_PASS )
PDATALIST DeleteDataList( PDATALIST *ppDataList )

PDATALIST AddDataItemEx( PDATALIST *ppDataList, POINTER data DBG_PASS )
PDATALIST AddDataItem( PDATALIST *ppDataList, POINTER data )

PDATALIST SetDataItemEx( PDATALIST *ppDataList, INDEX idx, POINTER data DBG_PASS )
PDATALIST SetDataItem( PDATALIST *ppDataList, INDEX idx, POINTER data )

POINTER GetDataItem( PDATALIST *ppDataList, INDEX idx )

DATA_FORALL( list, index, type, var )


Link Stack Methods


Data Stack Methods


Link Queue Methods


Data Queue Methods


Binary Tree Methods


Generic Set Methods


Text Data Methods


Variable Text Methods

PVARTEXT VarTextCreate( void );

Creates a variable text structure...Some extended