Home Libraries Author Links

Abstract Map Type Example
[Dset TestAbstract Map Types ElemTypeStmMap and ElemTypeStmMultiMap]

Collaboration diagram for Abstract Map Type Example:

Detailed Description

NrStmMap is an example of an abstract map type with int both as key type and as mapped type and the key comparison function keyCmp().


Files

file  NrStmMapDoc.h
 Documentation of the abstract map type NrStmMap.

Data Structures

struct  Nr
 Element type of the abstract map type NrStmMap. More...
struct  NrStmMapValueType
 Value type structure of an NrStmMap object. More...

NrStmMap Representation

Objects of abstract map type NrStmMap and their iterators of type NrStmMapIterator are represented by pointers to their implementation structures of type NrStmMapImpl_ and NrStmMapIteratorImpl_, respectively.

typedef struct NrStmMapImpl_ * NrStmMap
 A valid NrStmMap object is represented as a pointer to its implementation structure NrStmMapImpl_.
typedef struct
NrStmMapIteratorImpl_ * 
NrStmMapIterator
 A valid NrStmMapIterator object is represented as a pointer to its implementation structure NrStmMapIteratorImpl_.
typedef struct Nr Nr
 Type name of the element type of the abstract map type NrStmMap.
typedef struct NrStmMapValueType NrStmMapValueType
 Type name of the value type of the abstract map type NrStmMap.
#define StmMapDoc_

NrStmMap Creation and Destruction

static NrStmMap NrStmMapCreate (void)
 Creation of a new NrStmMap object.
static void NrStmMapDestroy (NrStmMap ac)
 Destruction of the NrStmMap object ac.

NrStmMap Iterators

static NrStmMapIterator NrStmMapBegin (NrStmMap ac)
 Return an iterator to the first element of the NrStmMap object ac.
static NrStmMapIterator NrStmMapEnd (NrStmMap ac)
 Return an iterator to one past the last element of the NrStmMap object ac.
static NrStmMapIterator NrStmMapRBegin (NrStmMap ac)
 Return an iterator to the last element of the NrStmMap object ac.
static NrStmMapIterator NrStmMapREnd (NrStmMap ac)
 Return an iterator to one before the first element of the NrStmMap object ac.
static NrStmMapIterator NrStmMapIteratorNext (NrStmMapIterator iter)
 Return an iterator to the element following the one referenced by iter.
static NrStmMapIterator NrStmMapIteratorPrev (NrStmMapIterator iter)
 Return an iterator to the element preceding the one referenced by iter.
static StmBool NrStmMapIteratorDereferenceable (NrStmMapIterator iter)
 Return StmTrue, if iter is dereferenceable.
static StmBool NrStmMapIteratorDereferencable (NrStmMapIterator iter)
 Return StmTrue, if iter is dereferenceable.
static NrStmMapValueTypeNrStmMapIteratorElem (NrStmMapIterator iter)
 Return a pointer to the NrStmMapValueType object accessing the element referenced by iter.
static int NrStmMapIteratorKey (NrStmMapIterator iter)
 Return the key of the element referenced by iter.
static int * NrStmMapIteratorVal (NrStmMapIterator iter)
 Return a pointer to the value mapped to by the element referenced by iter.

NrStmMap Capacity

static int NrStmMapSize (NrStmMap ac)
 Return the element count of the NrStmMap object ac.
static int NrStmMapMaxSize (NrStmMap ac)
 Return the maximal possible element count of the NrStmMap object ac.
static StmBool NrStmMapEmpty (NrStmMap ac)
 Return StmTrue, if the NrStmMap object ac is empty.

NrStmMap Modifiers

static NrStmMapIterator NrStmMapInsert (NrStmMap ac, const Nr *elem, StmBool *inserted)
 Insert the element pointed to by elem into the NrStmMap object ac.
static int NrStmMapErase (NrStmMap ac, NrStmMapIterator iter)
 Erase the element referenced by iter from the NrStmMap object ac.
static int NrStmMapEraseRange (NrStmMap ac, NrStmMapIterator first, NrStmMapIterator last)
 Erase the elements referenced by the half open interval [first, last) from the NrStmMap object ac.
static int NrStmMapEraseElem (NrStmMap ac, const Nr *elem)
 Erase all elements equivalent to the element pointed to by elem from the NrStmMap object ac.
static int NrStmMapEraseKey (NrStmMap ac, int key)
 Erase all elements designated by key from the NrStmMap object ac.
static int NrStmMapClear (NrStmMap ac)
 Erase all elements from the NrStmMap ac.

NrStmMap Operations

static NrStmMapIterator NrStmMapFind (NrStmMap ac, const Nr *elem)
 Find an element in the NrStmMap object ac equivalent to the element pointed to by elem.
static NrStmMapIterator NrStmMapFindKey (NrStmMap ac, int key)
 Find an element in the NrStmMap object ac designated by key.
static int NrStmMapCount (NrStmMap ac, const Nr *elem, NrStmMapIterator *first, NrStmMapIterator *last)
 Return the number of elements in the NrStmMap object ac being equivalent to the element pointed to by elem and optionally determine the range of the elements found.
static int NrStmMapCountKey (NrStmMap ac, int key, NrStmMapIterator *first, NrStmMapIterator *last)
 Return the number of elements in the NrStmMap object ac designated by key and optionally determine the range of the elements found.


Typedef Documentation

typedef struct NrStmMapImpl_* NrStmMap

A valid NrStmMap object is represented as a pointer to its implementation structure NrStmMapImpl_.

Valid objects of type NrStmMap can be achieved only as return values of NrStmMapCreate(). Moreover, variables of type NrStmMap may have the value NULL meaning invalid or undefined.

Examples:
dsettst.c.

Definition at line 77 of file NrStmMapDoc.h.

typedef struct NrStmMapIteratorImpl_* NrStmMapIterator

A valid NrStmMapIterator object is represented as a pointer to its implementation structure NrStmMapIteratorImpl_.

Valid objects of type NrStmMapIterator can be achieved only as return values of NrStmMap or NrStmMapIterator method functions. Moreover, variables of type NrStmMapIterator may have the value NULL meaning invalid or undefined.

Examples:
dsettst.c.

Definition at line 88 of file NrStmMapDoc.h.

typedef struct Nr Nr

Type name of the element type of the abstract map type NrStmMap.

Definition at line 101 of file NrStmMapDoc.h.

typedef struct NrStmMapValueType NrStmMapValueType

Type name of the value type of the abstract map type NrStmMap.

Definition at line 128 of file NrStmMapDoc.h.


Function Documentation

static NrStmMap NrStmMapCreate ( void   )  [static]

Creation of a new NrStmMap object.

Effects:
The function creates a NrStmMap object. This object has to be used as argument of the other NrStmMap functions.
Returns:
NULL on error. Then the variable errno contains the error's cause.

The NrStmMap object created on success.

See also:
NrStmMapDestroy().
Examples:
dsettst.c.

static void NrStmMapDestroy ( NrStmMap  ac  )  [static]

Destruction of the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object to be destroyed.
Effects:
The function destroys the NrStmMap object ac. It is no error to call the function for a NrStmMap object with value NULL in which case the function does nothing.
See also:
NrStmMapCreate().
Examples:
dsettst.c.

static NrStmMapIterator NrStmMapBegin ( NrStmMap  ac  )  [static]

Return an iterator to the first element of the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object.
Returns:
The invalid NrStmMapIterator (NULL), if ac is invalid in which case the variable errno is set to EINVAL.

A valid but not dereferenceable NrStmMapIterator object, if ac is valid but empty.

The NrStmMapIterator object referencing the first element of ac, if ac is valid and not empty.

See also:
NrStmMapEmpty(), NrStmMapIteratorDereferenceable(), NrStmMapEnd().
Examples:
dsettst.c.

static NrStmMapIterator NrStmMapEnd ( NrStmMap  ac  )  [static]

Return an iterator to one past the last element of the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object.
Returns:
The invalid NrStmMapIterator (NULL), if ac is invalid in which case the variable errno is set to EINVAL.

A valid but not dereferenceable NrStmMapIterator object, if ac is valid.

See also:
NrStmMapEmpty(), NrStmMapIteratorDereferenceable(), NrStmMapBegin().
Examples:
dsettst.c.

static NrStmMapIterator NrStmMapRBegin ( NrStmMap  ac  )  [static]

Return an iterator to the last element of the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object.
Returns:
The invalid NrStmMapIterator (NULL), if ac is invalid in which case the variable errno is set to EINVAL.

A valid but not dereferenceable NrStmMapIterator object, if ac is valid but empty.

The NrStmMapIterator object referencing the last element of ac, if ac is valid and not empty.

See also:
NrStmMapEmpty(), NrStmMapIteratorDereferenceable(), NrStmMapREnd().

static NrStmMapIterator NrStmMapREnd ( NrStmMap  ac  )  [static]

Return an iterator to one before the first element of the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object.
Returns:
The invalid NrStmMapIterator (NULL), if ac is invalid in which case the variable errno is set to EINVAL.

A valid but not dereferenceable NrStmMapIterator object, if ac is valid.

See also:
NrStmMapEmpty(), NrStmMapIteratorDereferenceable(), NrStmMapRBegin().

static NrStmMapIterator NrStmMapIteratorNext ( NrStmMapIterator  iter  )  [static]

Return an iterator to the element following the one referenced by iter.

Parameters:
[in] iter The NrStmMapIterator object.
Returns:
The invalid NrStmMapIterator (NULL), if iter is invalid in which case the variable errno is set to EINVAL.

NrStmMapBegin(ac), if iter is a valid but not dereferenceable iterator of a NrStmMap object ac.

A valid but not dereferenceable NrStmMapIterator object, if iter references the last element of a NrStmMap object.

The NrStmMapIterator object referencing the successor element of the element iter references, if iter is dereferenceable.

See also:
NrStmMapIteratorDereferenceable(), NrStmMapBegin (), NrStmMapIteratorPrev().
Examples:
dsettst.c.

static NrStmMapIterator NrStmMapIteratorPrev ( NrStmMapIterator  iter  )  [static]

Return an iterator to the element preceding the one referenced by iter.

Parameters:
[in] iter The NrStmMapIterator object.
Returns:
The invalid NrStmMapIterator (NULL), if iter is invalid in which case the variable errno is set to EINVAL.

NrStmMapEnd(ac), if iter is a valid but not dereferenceable iterator of a NrStmMap object ac.

A valid but not dereferenceable NrStmMapIterator object, if iter references the first element of a NrStmMap object.

The NrStmMapIterator object referencing the predecessor element of the element iter references, if iter is dereferenceable.

See also:
NrStmMapIteratorDereferenceable(), NrStmMapEnd (), NrStmMapIteratorNext().

static StmBool NrStmMapIteratorDereferenceable ( NrStmMapIterator  iter  )  [static]

Return StmTrue, if iter is dereferenceable.

Parameters:
[in] iter The NrStmMapIterator object.
Returns:
StmFalse, if iter is invalid (NULL), or if iter is valid but does not reference an element of a NrStmMap object.

StmTrue, if iter is valid and references an element of a NrStmMap object.

static StmBool NrStmMapIteratorDereferencable ( NrStmMapIterator  iter  )  [static]

Return StmTrue, if iter is dereferenceable.

Deprecated:
Do not use for new code. Use NrStmMapIteratorDereferenceable() instead.
Parameters:
[in] iter The NrStmMapIterator object.
Returns:
StmFalse, if iter is invalid (NULL), or if iter is valid but does not reference an element of a NrStmMap object.

StmTrue, if iter is valid and references an element of a NrStmMap object.

static NrStmMapValueType* NrStmMapIteratorElem ( NrStmMapIterator  iter  )  [static]

Return a pointer to the NrStmMapValueType object accessing the element referenced by iter.

Parameters:
[in] iter The NrStmMapIterator object.
Returns:
NULL, if iter is not dereferenceable in which case the variable errno is set to EINVAL.

A pointer to the NrStmMapValueType object referenced by iter, if iter is dereferenceable.

See also:
NrStmMapIteratorDereferenceable(), NrStmMapIteratorKey (), NrStmMapIteratorVal ().

static int NrStmMapIteratorKey ( NrStmMapIterator  iter  )  [static]

Return the key of the element referenced by iter.

Parameters:
[in] iter The NrStmMapIterator object.
Requires:
iter is dereferenceable.
Effects:
If iter is not dereferenceable, the function calls abort() which normally terminates the calling process as if raise(SIGABRT) was called.
Returns:
A the key of the element referenced by iter, if iter is dereferenceable.
See also:
NrStmMapIteratorDereferenceable(), NrStmMapIteratorElem (), NrStmMapIteratorVal ().
Examples:
dsettst.c.

static int* NrStmMapIteratorVal ( NrStmMapIterator  iter  )  [static]

Return a pointer to the value mapped to by the element referenced by iter.

Parameters:
[in] iter The NrStmMapIterator object.
Returns:
NULL, if iter is not dereferenceable in which case the variable errno is set to EINVAL.

A pointer to the value mapped by the element referenced by iter, if iter is dereferenceable.

See also:
NrStmMapIteratorDereferenceable(), NrStmMapIteratorElem (), NrStmMapIteratorKey ().

static int NrStmMapSize ( NrStmMap  ac  )  [static]

Return the element count of the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object.
Returns:
-1, if ac is invalid (NULL) in which case the variable errno is set to EINVAL.

The element count of the NrStmMap object ac, if ac is valid.

See also:
NrStmMapMaxSize (), NrStmMapEmpty ().
Examples:
dsettst.c.

static int NrStmMapMaxSize ( NrStmMap  ac  )  [static]

Return the maximal possible element count of the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object.
Returns:
-1, if ac is invalid (NULL) in which case the variable errno is set to EINVAL.

INT_MAX as the theoretically maximal possible element count of the NrStmMap object ac, if ac is valid.

See also:
NrStmMapSize (), NrStmMapEmpty ().

static StmBool NrStmMapEmpty ( NrStmMap  ac  )  [static]

Return StmTrue, if the NrStmMap object ac is empty.

Parameters:
[in] ac The NrStmMap object.
Returns:
StmTrue, if ac is invalid (NULL) in which case the variable errno is set to EINVAL.

StmTrue, if the NrStmMap object ac is valid and empty.

StmFalse, if the NrStmMap object ac is valid and not empty.

See also:
NrStmMapSize (), NrStmMapMaxSize ().

static NrStmMapIterator NrStmMapInsert ( NrStmMap  ac,
const Nr elem,
StmBool inserted 
) [static]

Insert the element pointed to by elem into the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object.
[in] elem A pointer to the constant Nr object to be inserted.
[out] inserted If not NULL, a pointer to the StmBool variable expecting the insertion state.
Effects:
The function inserts a copy of the element pointed to by elem into the NrStmMap object ac, unless an element equivalent to that element is already contained in ac. If inserted is not NULL, the variable pointed to by inserted is set to StmTrue, if the element has been inserted, else to StmFalse.
Returns:
NULL on error. Then the variable errno reflects the error's cause. Especially, if ac is invalid or elem is NULL, errno is set to EINVAL.

a NrStmMapIterator object referencing that element of ac being equivalent to the Nr object pointed to by elem.

See also:
NrStmMapErase(), NrStmMapFind(), NrStmMapCount().
Examples:
dsettst.c.

static int NrStmMapErase ( NrStmMap  ac,
NrStmMapIterator  iter 
) [static]

Erase the element referenced by iter from the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object.
[in] iter The NrStmMapIterator object referencing the element to be erased.
Effects:
If iter is dereferenceable, the element referenced by iter is deleted from ac.
Returns:
-1 on error. Then the variable errno reflects the error's cause. Especially, if ac is invalid, errno is set to EINVAL.

0, if iter is not dereferenceable and no element has been erased.

1, if iter is derefereceable and the element referenced by iter has been erased.

See also:
NrStmMapIteratorDereferenceable(), NrStmMapInsert(), NrStmMapFind(), NrStmMapCount().

static int NrStmMapEraseRange ( NrStmMap  ac,
NrStmMapIterator  first,
NrStmMapIterator  last 
) [static]

Erase the elements referenced by the half open interval [first, last) from the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object.
[in] first The NrStmMapIterator object referencing the first element to be erased.
[in] last The NrStmMapIterator object referencing the element one past the last element to be erased.
Effects:
All elements referenced by by the half open interval [first, last) are deleted from ac.
Returns:
-1 on error. Then the variable errno reflects the error's cause. Especially, if ac, first or last is invalid, or if first is not dereferenceable but last is, errno is set to EINVAL.

The number of elements having been erased.

See also:
NrStmMapIteratorDereferenceable(), NrStmMapInsert(), NrStmMapFind(), NrStmMapCount().

static int NrStmMapEraseElem ( NrStmMap  ac,
const Nr elem 
) [static]

Erase all elements equivalent to the element pointed to by elem from the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object.
[in] elem A pointer to the Nr object being equivalent to the elements to be erased.
Effects:
All elements equivalent to the element pointed to by elem are deleted from ac.
Returns:
-1 on error. Then the variable errno reflects the error's cause. Especially, if ac is invalid, or if elem is NULL, errno is set to EINVAL.

The number of elements having been erased.

See also:
NrStmMapInsert(), NrStmMapFind(), NrStmMapCount().

static int NrStmMapEraseKey ( NrStmMap  ac,
int  key 
) [static]

Erase all elements designated by key from the NrStmMap object ac.

Parameters:
[in] ac The NrStmMap object.
[in] key The int object designating the elements to be erased.
Effects:
All elements designated by key are deleted from ac.
Returns:
-1 on error. Then the variable errno reflects the error's cause. Especially, if ac is invalid, errno is set to EINVAL.

The number of elements having been erased.

See also:
NrStmMapInsert(), NrStmMapFindKey(), NrStmMapCountKey().
Examples:
dsettst.c.

static int NrStmMapClear ( NrStmMap  ac  )  [static]

Erase all elements from the NrStmMap ac.

Parameters:
[in] ac The NrStmMap object.
Effects:
All elements are deleted from ac.
Returns:
-1 on error. Then the variable errno reflects the error's cause. Especially, if ac is invalid, errno is set to EINVAL.

The number of elements having been erased.

See also:
NrStmMapErase(), NrStmMapEraseRange().
Examples:
dsettst.c.

static NrStmMapIterator NrStmMapFind ( NrStmMap  ac,
const Nr elem 
) [static]

Find an element in the NrStmMap object ac equivalent to the element pointed to by elem.

Parameters:
[in] ac The NrStmMap object.
[in] elem A pointer to the Nr object being equivalent to the element to be found.
Effects:
The function looks for an element contained in ac being equivalent to the element pointed to by elem.
Returns:
NULL on error. Then the variable errno reflects the error's cause. Especially, if ac is invalid, or if elem is NULL, errno is set to EINVAL.

A valid but not dereferenceable NrStmMapIterator object, if no element equivalent to the element pointed to by elem is contained in ac.

A NrStmMapIterator object referencing an element equivalent to the element pointed to by elem contained in ac.

Note:
If more than one element equivalent to the element pointed to by elem is contained in ac, it is unspecified which one of them is referenced by the NrStmMapIterator object returned. If that is an issue, consider to use NrStmMapCount() instead.
See also:
NrStmMapIteratorDereferenceable(), NrStmMapInsert(), NrStmMapErase(), NrStmMapCount().

static NrStmMapIterator NrStmMapFindKey ( NrStmMap  ac,
int  key 
) [static]

Find an element in the NrStmMap object ac designated by key.

Parameters:
[in] ac The NrStmMap object.
[in] key The int object designating the element to be found.
Effects:
The function looks for an element contained in ac being designated by key.
Returns:
NULL on error. Then the variable errno reflects the error's cause. Especially, if ac is invalid, errno is set to EINVAL.

A valid but not dereferenceable NrStmMapIterator object, if no element designated by key is contained in ac.

A NrStmMapIterator object referencing an element designated by key contained in ac.

Note:
If more than one element designated by key is contained in ac, it is unspecified which one of them is referenced by the NrStmMapIterator object returned. If that is an issue, consider to use NrStmMapCountKey() instead.
See also:
NrStmMapIteratorDereferenceable(), NrStmMapInsert(), NrStmMapEraseKey(), NrStmMapCountKey().

static int NrStmMapCount ( NrStmMap  ac,
const Nr elem,
NrStmMapIterator first,
NrStmMapIterator last 
) [static]

Return the number of elements in the NrStmMap object ac being equivalent to the element pointed to by elem and optionally determine the range of the elements found.

Parameters:
[in] ac The NrStmMap object.
[in] elem A pointer to the Nr object being equivalent to the elements to be found.
[out] first If not NULL, the address of the NrStmMapIterator object expected to reference the first element found.
[out] last If not NULL, the address of the NrStmMapIterator object expected to reference the element one past the last element found.
Effects:
The function looks for all elements contained in ac being equivalent to the element pointed to by elem and updates the NrStmMapIterator objects first and last accordingly, if applicable.
Returns:
-1 on error. Then the variable errno reflects the error's cause. Especially, if ac is invalid, or if elem is NULL, errno is set to EINVAL.

The number of elements equivalent to the element pointed to by elem contained in ac.

See also:
NrStmMapInsert(), NrStmMapErase(), NrStmMapFind().

static int NrStmMapCountKey ( NrStmMap  ac,
int  key,
NrStmMapIterator first,
NrStmMapIterator last 
) [static]

Return the number of elements in the NrStmMap object ac designated by key and optionally determine the range of the elements found.

Parameters:
[in] ac The NrStmMap object.
[in] key The int object designating the elements to be found.
[out] first If not NULL, the address of the NrStmMapIterator object expected to reference the first element found.
[out] last If not NULL, the address of the NrStmMapIterator object expected to reference the element one past the last element found.
Effects:
The function looks for all elements contained in ac designated by key and updates the NrStmMapIterator objects first and last accordingly, if applicable.
Returns:
-1 on error. Then the variable errno reflects the error's cause. Especially, if ac is invalid, errno is set to EINVAL.

The number of elements designated by key contained in ac.

See also:
NrStmMapInsert(), NrStmMapEraseKey(), NrStmMapFindKey().


© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).