itemarr.h File Reference

---

Detailed Description

Item Arrays, by Peter O., Public domain.

This module implements item arrays and string trees. It also contains implementations of memory arrays and item stacks, which utilize item arrays in their implementation. Item arrays are dynamic data structures for storing related data, which can grow as items are added to them. String trees are like hash tables; their functions allow strings to be referenced as keys which can be used for very fast lookup and retrieval of strings. Each string can also store pieces of data associated with them, making them act like hash tables.

Definition in file itemarr.h.

#include "user.h"

Go to the source code of this file.

Data Structures
struct	_ITEMLINK
struct	ITEMARRAY
	Item array structure. More...
struct	ITEMSTACK
	Item stack structure. More...
struct	STRINGTREEITEM
struct	STRINGTREE
	String tree structure. More...
Defines
#define	ISARRAY(a, type)   (a && (a)->szItem==sizeof(type))
	Determines whether the item array's item size is equal to that of _type_.
#define	ItemArrayClear(a)   ((a) ? 0 : ((a)->length=0))
	Clears an item array by setting its length to 0.
#define	ItemArrayInit(ia, sz)   ItemArrayInitEx(ia,sz,0,0)
	Initializes an item array of the specified size.
#define	ItemArrayInitFixed(ia, sz)   ItemArrayInitFixedEx(ia,sz,128,256)
	Initializes an item array of the specified size, where each item occupies a fixed position in memory and doesn't move even when the array grows in size.
#define	StringTreeInit(ia, init, grow)   StringTreeInitEx(ia,0,init,grow,FALSE)
	Initializes a new string tree with initial size _init_ and growth size _grow_.
#define	MemArrayAlloc(ia, sz)   MemArrayReAlloc(ia,NULL,sz)
	Allocates memory and stores the memory pointer in a memory array.
Typedefs
typedef _ITEMLINK	ITEMLINK
Functions
LPVOID	ItemArrayPtr (ITEMARRAY *ia, int i)
	Returns a pointer to an item within the item array.
BOOL	ItemArrayInitEx (ITEMARRAY *ia, DWORD sz, DWORD init, DWORD grow)
	Initializes an item array of the specified size.
BOOL	ItemArrayInitFixedEx (ITEMARRAY *ia, DWORD sz, DWORD init, DWORD grow)
	Initializes an item array of the specified size, where each item occupies a fixed position in memory and doesn't move even when the array grows in size.
void	ItemArrayRemoveItem (ITEMARRAY *ia, LONG idx)
	Removes an item from an item array.
LPVOID	ItemArraySearch (ITEMARRAY *ia, LPVOID key, int(*cmp)(LPVOID, LPVOID))
	Searches for an item within an item array and returns a pointer to the first item found.
LONG	ItemArraySearchIndex (ITEMARRAY *ia, LPVOID key, int(*cmp)(LPVOID, LPVOID))
	Searches for an item within an item array and returns the index to the first item found.
LPVOID	ItemArrayAllocOnePtr (ITEMARRAY *ia)
	Adds a single item to the item array and returns a pointer to that item.
LONG	ItemArrayAllocOne (ITEMARRAY *ia)
	Adds a single item to the item array and returns an index to that item.
LPVOID	ItemArrayAllocManyPtr (ITEMARRAY *ia, DWORD sz)
	Adds a number of items at once to the item array and returns a pointer to those items.
LONG	ItemArrayAllocMany (ITEMARRAY *ia, DWORD sz)
	Adds a number of items at once to the item array.
void	ItemArrayFree (ITEMARRAY *ia)
	Frees an item array.
LPVOID	StringTreeGetData (STRINGTREE *st, LONG i)
	Gets a pointer to the data in a string tree in index _i_.
LPVOID	StringTreeFindData (STRINGTREE *st, LPCTSTR str)
	Finds the item with the string _str_ in a string tree and returns its data.
BOOL	StringTreeInitEx (STRINGTREE *st, DWORD szItem, DWORD init, DWORD grow, BOOL ignoreCase)
	Initializes a new string tree with data size _szItem_, initial size _init_ and growth size _grow_.
LONG	StringTreeFindString (STRINGTREE *st, LPCTSTR str)
	Finds the item with the string _str_ in a string tree and returns its index.
LPBYTE	StringTreeGetString (STRINGTREE *st, LONG i)
	Finds the string with the index _i_ in a string tree.
LONG	StringTreeAddString (STRINGTREE *st, LPCTSTR str)
	Adds a string to a string tree and returns its index.
BOOL	StringTreeFree (STRINGTREE *st)
	Frees a string tree's memory.
void	ItemArraySort (ITEMARRAY *ia, int(*cmp)(LPVOID, LPVOID))
	Sorts the items found in an item array.
LPVOID	MemArrayReAlloc (ITEMARRAY *ia, LPVOID pv, DWORD sz)
	Changes the size of a memory pointer within a memory array.
void	MemArrayFreePtr (ITEMARRAY *ia, LPVOID pv)
	Frees a memory pointer within a memory array.
void	MemArrayFreeAll (ITEMARRAY *ia)
	Frees all memory pointers within a memory array.
BOOL	ItemStackInit (ITEMSTACK *stack, DWORD sz)
	Initializes an item stack, a special kind of item array.
LPVOID	ItemStackGet (ITEMSTACK *stack)
	Gets a pointer to the last item in the item stack.
LPVOID	ItemStackPush (ITEMSTACK *stack, LPVOID p)
	Pushes memory to the item stack.
void	ItemStackPop (ITEMSTACK *stack)
	Frees the last item stored in the item stack and pops it out of it.
void	ItemStackFree (ITEMSTACK *stack)
	Frees the item stack and all its pointers.

---

Define Documentation

#define ISARRAY (  a, type   )     (a && (a)->szItem==sizeof(type))

Determines whether the item array's item size is equal to that of _type_. Definition at line 59 of file itemarr.h.

#define ItemArrayClear (  a   )     ((a) ? 0 : ((a)->length=0))

Clears an item array by setting its length to 0. Definition at line 63 of file itemarr.h.

#define ItemArrayInit (  ia, sz   )     ItemArrayInitEx(ia,sz,0,0)

Initializes an item array of the specified size. Parameters: ia  A pointer to the array. sz  Size of each element in the array. Returns: FALSE if ia is NULL, TRUE otherwise. Definition at line 70 of file itemarr.h.

#define ItemArrayInitFixed (  ia, sz   )     ItemArrayInitFixedEx(ia,sz,128,256)

Initializes an item array of the specified size, where each item occupies a fixed position in memory and doesn't move even when the array grows in size. Parameters: ia  A pointer to the array. sz  Size of each element in the array. Returns: FALSE if ia is NULL, TRUE otherwise. Definition at line 79 of file itemarr.h.

#define MemArrayAlloc (  ia, sz   )     MemArrayReAlloc(ia,NULL,sz)

Allocates memory and stores the memory pointer in a memory array. Parameters: ia  A pointer (ITEMARRAY*) to an item array. sz  Size in bytes of the amount of memory to allocate. Returns: A pointer to the allocated memory, or NULL if out of memory. Definition at line 288 of file itemarr.h.

#define StringTreeInit (  ia, init, grow   )     StringTreeInitEx(ia,0,init,grow,FALSE)

Initializes a new string tree with initial size _init_ and growth size _grow_. Strings in the tree will be case sensitive. A string tree is a multipurpose binary tree of strings, like a hash table. Definition at line 219 of file itemarr.h.

---

Typedef Documentation

typedef struct _ITEMLINK ITEMLINK

---

Function Documentation

LONG ItemArrayAllocMany (  ITEMARRAY *  ia, DWORD  sz )

Adds a number of items at once to the item array. Parameters: ia  A pointer to the array. sz  Number of items to add. sz  Returns the index to the first item added to the array, or -1 if out of memory. The items' memory will be initialized with zeros. Definition at line 173 of file itemarr.c.

LPVOID ItemArrayAllocManyPtr (  ITEMARRAY *  ia, DWORD  sz )

Adds a number of items at once to the item array and returns a pointer to those items. Parameters: ia  A pointer to the array. sz  Number of items to add. Returns: Returns a pointer to the items added, or NULL if out of memory. The items' memory will be initialized with zeros. Definition at line 169 of file itemarr.c.

LONG ItemArrayAllocOne (  ITEMARRAY *  ia  )

Adds a single item to the item array and returns an index to that item. Parameters: ia  A pointer to the array. Returns: Returns the index to the item added, or -1 if out of memory. The item's memory will be initialized with zeros. Definition at line 166 of file itemarr.c.

LPVOID ItemArrayAllocOnePtr (  ITEMARRAY *  ia  )

Adds a single item to the item array and returns a pointer to that item. Parameters: ia  A pointer to the array. Returns: Returns a pointer to the item added, or -1 if out of memory. The item's memory will be initialized with zeros. Definition at line 162 of file itemarr.c.

void ItemArrayFree (  ITEMARRAY *  ia  )

Frees an item array. Parameters: ia  A pointer to the array. Definition at line 176 of file itemarr.c.

BOOL ItemArrayInitEx (  ITEMARRAY *  ia, DWORD  sz, DWORD  init, DWORD  grow )

Initializes an item array of the specified size. Parameters: ia  A pointer to the array. sz  Size of each element in the array. init  Initial number of elements in the array. grow  Number of elements to increase the array by when no room exists to fit new items. Returns: FALSE if ia is NULL, TRUE otherwise. Definition at line 14 of file itemarr.c.

BOOL ItemArrayInitFixedEx (  ITEMARRAY *  ia, DWORD  sz, DWORD  init, DWORD  grow )

Initializes an item array of the specified size, where each item occupies a fixed position in memory and doesn't move even when the array grows in size. Parameters: ia  A pointer to the array. sz  Size of each element in the array. init  Initial number of elements in the array. grow  Number of elements to increase the array by when no room exists to fit new items. Returns: FALSE if ia is NULL, TRUE otherwise. Definition at line 29 of file itemarr.c.

LPVOID ItemArrayPtr (  ITEMARRAY *  ia, int  i )

Returns a pointer to an item within the item array. Parameters: ia  A pointer to the array. i  Index within the array. Returns: A pointer to the item, or NULL if the index is out of the array's range. Definition at line 155 of file itemarr.c.

void ItemArrayRemoveItem (  ITEMARRAY *  ia, LONG  idx )

Removes an item from an item array. This function has no effect on a fixed-memory array. The size of the array will also be adjusted and any items after the removed item shifted in position. Parameters: ia  A pointer to an item array. cmp  Index of the item to be removed. Definition at line 221 of file itemarr.c.

LPVOID ItemArraySearch (  ITEMARRAY *  ia, LPVOID  key, int(*)(LPVOID, LPVOID)  cmp )

Searches for an item within an item array and returns a pointer to the first item found. Parameters: ia  A pointer to an item array. key  A search key which is passed to the comparison function. cmp  A comparison function. It should return 0 if the items are equal, -1 if the first item is less than the second, or 1 if the first item is greater. Returns: A pointer of the first item found for which the comparison function returns 0, or -1 if not found or _ia_ is empty or NULL. Definition at line 258 of file itemarr.c.

LONG ItemArraySearchIndex (  ITEMARRAY *  ia, LPVOID  key, int(*)(LPVOID, LPVOID)  cmp )

Searches for an item within an item array and returns the index to the first item found. Parameters: ia  A pointer to an item array. key  A search key which is passed to the comparison function. cmp  A comparison function. See ItemArraySearch. Returns: The index of the first item found for which the comparison function returns 0, or -1 if not found or _ia_ is empty or NULL. Definition at line 234 of file itemarr.c.

void ItemArraySort (  ITEMARRAY *  ia, int(*)(LPVOID, LPVOID)  cmp )

Sorts the items found in an item array. This function has no effect on a fixed-memory array. Parameters: ia  A pointer to an item array. cmp  A comparison function for each item in the array. It should return 0 if the items are equal, -1 if the first item is less than the second, or 1 if the first item is greater. Definition at line 213 of file itemarr.c.

void ItemStackFree (  ITEMSTACK *  stack  )

Frees the item stack and all its pointers. Parameters: stack  A pointer to the item stack. Definition at line 490 of file itemarr.c.

LPVOID ItemStackGet (  ITEMSTACK *  stack  )

Gets a pointer to the last item in the item stack. Parameters: stack  A pointer to the item stack. Returns: A pointer to the last item in the stack, or NULL if the stack is empty or stack is NULL. Definition at line 449 of file itemarr.c.

BOOL ItemStackInit (  ITEMSTACK *  stack, DWORD  sz )

Initializes an item stack, a special kind of item array. Parameters: stack  A pointer to the item stack. sz  Size of each element in the stack. Returns: FALSE if ia is NULL, TRUE otherwise. Definition at line 441 of file itemarr.c.

void ItemStackPop (  ITEMSTACK *  stack  )

Frees the last item stored in the item stack and pops it out of it. This function will do nothing if the stack is NULL or is empty. Parameters: stack  A pointer to the item stack. Definition at line 477 of file itemarr.c.

LPVOID ItemStackPush (  ITEMSTACK *  stack, LPVOID  p )

Pushes memory to the item stack. Parameters: stack  A pointer to the item stack. p  If this is NULL, the added memory pointer will be filled with zeros. Otherwise, the added memory pointer will contain a copy of the data on this pointer. Returns: A pointer to the item pushed to the stack, or NULL if out of memory. Definition at line 461 of file itemarr.c.

void MemArrayFreeAll (  ITEMARRAY *  ia  )

Frees all memory pointers within a memory array. The memory array itself is not freed. Parameters: ia  A pointer to an item array. Definition at line 427 of file itemarr.c.

void MemArrayFreePtr (  ITEMARRAY *  ia, LPVOID  pv )

Frees a memory pointer within a memory array. Parameters: ia  A pointer to an item array. pv  The pointer to be freed. Definition at line 413 of file itemarr.c.

LPVOID MemArrayReAlloc (  ITEMARRAY *  ia, LPVOID  pv, DWORD  sz )

Changes the size of a memory pointer within a memory array. Parameters: ia  A pointer (ITEMARRAY*) to an item array. pv  A pointer whose size should be changed. sz  Size in bytes of the amount of memory to allocate. Returns: A pointer to the allocated memory, or NULL if out of memory. If the pointer was not found or is NULL, this function acts like MemArrayAlloc(). Definition at line 387 of file itemarr.c.

LONG StringTreeAddString (  STRINGTREE *  st, LPCTSTR  str )

Adds a string to a string tree and returns its index. Parameters: st  String tree. i  Index within the string tree. Returns: Pointer to the string, or -1 if _st_ is NULL or empty or _i_ is out of range. Definition at line 322 of file itemarr.c.

LPVOID StringTreeFindData (  STRINGTREE *  st, LPCTSTR  str )

Finds the item with the string _str_ in a string tree and returns its data. Parameters: st  String tree. str  String to look for. Returns: A pointer to the item's data, or NULL if _st_ is NULL or empty, _str_ can't be found, or no data is stored in the string tree. Definition at line 298 of file itemarr.c.

LONG StringTreeFindString (  STRINGTREE *  st, LPCTSTR  str )

Finds the item with the string _str_ in a string tree and returns its index. Parameters: st  String tree. str  String to look for. Returns: Index to the item's data, or -1 if _st_ is NULL or empty or _str_ can't be found. Definition at line 278 of file itemarr.c.

BOOL StringTreeFree (  STRINGTREE *  st  )

Frees a string tree's memory. Parameters: st  String tree. Returns: FALSE if _st_ is NULL, TRUE otherwise. Definition at line 377 of file itemarr.c.

LPVOID StringTreeGetData (  STRINGTREE *  st, LONG  i )

Gets a pointer to the data in a string tree in index _i_. Parameters: st  String tree. i  Index within the string tree. Returns: A pointer to the item's data, or NULL if _st_ is NULL or empty, _str_ can't be found, _i_ is out of range, or no data is stored in the string tree. Definition at line 294 of file itemarr.c.

LPBYTE StringTreeGetString (  STRINGTREE *  st, LONG  i )

Finds the string with the index _i_ in a string tree. Parameters: st  String tree. i  Index within the string tree. Returns: Pointer to the string, or -1 if _st_ is NULL or empty or _i_ is out of range. Definition at line 290 of file itemarr.c.

BOOL StringTreeInitEx (  STRINGTREE *  st, DWORD  szItem, DWORD  init, DWORD  grow, BOOL  ignoreCase )

Initializes a new string tree with data size _szItem_, initial size _init_ and growth size _grow_. If _ignoreCase_ is true, strings in the string tree are not case sensitive. Definition at line 355 of file itemarr.c.

---