Home Libraries Author Links

Abstract Multiset Type Example
[Dset TestAbstract Set Types ElemTypeStmSet and ElemTypeStmMultiSet]

Collaboration diagram for Abstract Multiset Type Example:

Detailed Description

intStmMultiSet is an example of an abstract multiset type with int elements and the element comparison function elemCmp().


Files

file  intStmMultiSetDoc.h
 Documentation of the abstract multiset type intStmMultiSet.

intStmMultiSet Representation

Objects of abstract multiset type intStmMultiSet and their iterators of type intStmMultiSetIterator are represented by pointers to their implementation structures of type intStmMultiSetImpl_ and intStmMultiSetIteratorImpl_, respectively.

typedef struct
intStmMultiSetImpl_ * 
intStmMultiSet
 A valid intStmMultiSet object is represented as a pointer to its implementation structure intStmMultiSetImpl_.
typedef struct
intStmMultiSetIteratorImpl_ * 
intStmMultiSetIterator
 A valid intStmMultiSetIterator object is represented as a pointer to its implementation structure intStmMultiSetIteratorImpl_.
#define StmMultiSetDoc_

intStmMultiSet Creation and Destruction

static intStmMultiSet intStmMultiSetCreate (void)
 Creation of a new intStmMultiSet object.
static void intStmMultiSetDestroy (intStmMultiSet ac)
 Destruction of the intStmMultiSet object ac.

intStmMultiSet Iterators

static intStmMultiSetIterator intStmMultiSetBegin (intStmMultiSet ac)
 Return an iterator to the first element of the intStmMultiSet object ac.
static intStmMultiSetIterator intStmMultiSetEnd (intStmMultiSet ac)
 Return an iterator to one past the last element of the intStmMultiSet object ac.
static intStmMultiSetIterator intStmMultiSetRBegin (intStmMultiSet ac)
 Return an iterator to the last element of the intStmMultiSet object ac.
static intStmMultiSetIterator intStmMultiSetREnd (intStmMultiSet ac)
 Return an iterator to one before the first element of the intStmMultiSet object ac.
static intStmMultiSetIterator intStmMultiSetIteratorNext (intStmMultiSetIterator iter)
 Return an iterator to the element following the one referenced by iter.
static intStmMultiSetIterator intStmMultiSetIteratorPrev (intStmMultiSetIterator iter)
 Return an iterator to the element preceding the one referenced by iter.
static StmBool intStmMultiSetIteratorDereferenceable (intStmMultiSetIterator iter)
 Return StmTrue, if iter is dereferenceable.
static StmBool intStmMultiSetIteratorDereferencable (intStmMultiSetIterator iter)
 Return StmTrue, if iter is dereferenceable.
static const int * intStmMultiSetIteratorElem (intStmMultiSetIterator iter)
 Return a pointer to the constant element referenced by iter.
static int intStmMultiSetIteratorKey (intStmMultiSetIterator iter)
 Return a copy of the element referenced by iter.

intStmMultiSet Capacity

static int intStmMultiSetSize (intStmMultiSet ac)
 Return the element count of the intStmMultiSet object ac.
static int intStmMultiSetMaxSize (intStmMultiSet ac)
 Return the maximal possible element count of the intStmMultiSet object ac.
static StmBool intStmMultiSetEmpty (intStmMultiSet ac)
 Return StmTrue, if the intStmMultiSet object ac is empty.

intStmMultiSet Modifiers

static intStmMultiSetIterator intStmMultiSetInsert (intStmMultiSet ac, const int *elem)
 Insert the element pointed to by elem into the intStmMultiSet object ac.
static int intStmMultiSetErase (intStmMultiSet ac, intStmMultiSetIterator iter)
 Erase the element referenced by iter from the intStmMultiSet object ac.
static int intStmMultiSetEraseRange (intStmMultiSet ac, intStmMultiSetIterator first, intStmMultiSetIterator last)
 Erase the elements referenced by the half open interval [first, last) from the intStmMultiSet object ac.
static int intStmMultiSetEraseElem (intStmMultiSet ac, const int *elem)
 Erase all elements equivalent to the element pointed to by elem from the intStmMultiSet object ac.
static int intStmMultiSetEraseKey (intStmMultiSet ac, int key)
 Erase all elements with value key from the intStmMultiSet object ac.
static int intStmMultiSetClear (intStmMultiSet ac)
 Erase all elements from the intStmMultiSet ac.

intStmMultiSet Operations

static intStmMultiSetIterator intStmMultiSetFind (intStmMultiSet ac, const int *elem)
 Find an element in the intStmMultiSet object ac equivalent to the element pointed to by elem.
static intStmMultiSetIterator intStmMultiSetFindKey (intStmMultiSet ac, int key)
 Find an element in the intStmMultiSet object ac with value key.
static int intStmMultiSetCount (intStmMultiSet ac, const int *elem, intStmMultiSetIterator *first, intStmMultiSetIterator *last)
 Return the number of elements in the intStmMultiSet object ac being equivalent to the element pointed to by elem and optionally determine the range of the elements found.
static int intStmMultiSetCountKey (intStmMultiSet ac, int key, intStmMultiSetIterator *first, intStmMultiSetIterator *last)
 Return the number of elements in the intStmMultiSet object ac having value key and optionally determine the range of the elements found.


Typedef Documentation

typedef struct intStmMultiSetImpl_* intStmMultiSet

A valid intStmMultiSet object is represented as a pointer to its implementation structure intStmMultiSetImpl_.

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

Examples:
dsettst.c.

Definition at line 77 of file intStmMultiSetDoc.h.

typedef struct intStmMultiSetIteratorImpl_* intStmMultiSetIterator

A valid intStmMultiSetIterator object is represented as a pointer to its implementation structure intStmMultiSetIteratorImpl_.

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

Examples:
dsettst.c.

Definition at line 88 of file intStmMultiSetDoc.h.


Function Documentation

static intStmMultiSet intStmMultiSetCreate ( void   )  [static]

Creation of a new intStmMultiSet object.

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

The intStmMultiSet object created on success.

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

static void intStmMultiSetDestroy ( intStmMultiSet  ac  )  [static]

Destruction of the intStmMultiSet object ac.

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

static intStmMultiSetIterator intStmMultiSetBegin ( intStmMultiSet  ac  )  [static]

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

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

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

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

See also:
intStmMultiSetEmpty(), intStmMultiSetIteratorDereferenceable(), intStmMultiSetEnd().
Examples:
dsettst.c.

static intStmMultiSetIterator intStmMultiSetEnd ( intStmMultiSet  ac  )  [static]

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

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

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

See also:
intStmMultiSetEmpty(), intStmMultiSetIteratorDereferenceable(), intStmMultiSetBegin().
Examples:
dsettst.c.

static intStmMultiSetIterator intStmMultiSetRBegin ( intStmMultiSet  ac  )  [static]

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

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

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

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

See also:
intStmMultiSetEmpty(), intStmMultiSetIteratorDereferenceable(), intStmMultiSetREnd().

static intStmMultiSetIterator intStmMultiSetREnd ( intStmMultiSet  ac  )  [static]

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

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

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

See also:
intStmMultiSetEmpty(), intStmMultiSetIteratorDereferenceable(), intStmMultiSetRBegin().

static intStmMultiSetIterator intStmMultiSetIteratorNext ( intStmMultiSetIterator  iter  )  [static]

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

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

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

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

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

See also:
intStmMultiSetIteratorDereferenceable(), intStmMultiSetBegin (), intStmMultiSetIteratorPrev().
Examples:
dsettst.c.

static intStmMultiSetIterator intStmMultiSetIteratorPrev ( intStmMultiSetIterator  iter  )  [static]

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

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

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

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

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

See also:
intStmMultiSetIteratorDereferenceable(), intStmMultiSetEnd (), intStmMultiSetIteratorNext().

static StmBool intStmMultiSetIteratorDereferenceable ( intStmMultiSetIterator  iter  )  [static]

Return StmTrue, if iter is dereferenceable.

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

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

static StmBool intStmMultiSetIteratorDereferencable ( intStmMultiSetIterator  iter  )  [static]

Return StmTrue, if iter is dereferenceable.

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

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

static const int* intStmMultiSetIteratorElem ( intStmMultiSetIterator  iter  )  [static]

Return a pointer to the constant element referenced by iter.

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

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

See also:
intStmMultiSetIteratorDereferenceable(), intStmMultiSetIteratorKey ().
Examples:
dsettst.c.

static int intStmMultiSetIteratorKey ( intStmMultiSetIterator  iter  )  [static]

Return a copy of the element referenced by iter.

Parameters:
[in] iter The intStmMultiSetIterator 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 copy of the element referenced by iter, if iter is dereferenceable.
See also:
intStmMultiSetIteratorDereferenceable(), intStmMultiSetIteratorElem ().

static int intStmMultiSetSize ( intStmMultiSet  ac  )  [static]

Return the element count of the intStmMultiSet object ac.

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

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

See also:
intStmMultiSetMaxSize (), intStmMultiSetEmpty ().
Examples:
dsettst.c.

static int intStmMultiSetMaxSize ( intStmMultiSet  ac  )  [static]

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

Parameters:
[in] ac The intStmMultiSet 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 intStmMultiSet object ac, if ac is valid.

See also:
intStmMultiSetSize (), intStmMultiSetEmpty ().

static StmBool intStmMultiSetEmpty ( intStmMultiSet  ac  )  [static]

Return StmTrue, if the intStmMultiSet object ac is empty.

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

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

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

See also:
intStmMultiSetSize (), intStmMultiSetMaxSize ().

static intStmMultiSetIterator intStmMultiSetInsert ( intStmMultiSet  ac,
const int *  elem 
) [static]

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

Parameters:
[in] ac The intStmMultiSet object.
[in] elem A pointer to the constant int object to be inserted.
Effects:
The function inserts a copy of the element pointed to by elem into the intStmMultiSet object ac.
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 intStmMultiSetIterator object referencing the element of ac which was inserted.

See also:
intStmMultiSetErase(), intStmMultiSetFind(), intStmMultiSetCount().
Examples:
dsettst.c.

static int intStmMultiSetErase ( intStmMultiSet  ac,
intStmMultiSetIterator  iter 
) [static]

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

Parameters:
[in] ac The intStmMultiSet object.
[in] iter The intStmMultiSetIterator 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:
intStmMultiSetIteratorDereferenceable(), intStmMultiSetInsert(), intStmMultiSetFind(), intStmMultiSetCount().
Examples:
dsettst.c.

static int intStmMultiSetEraseRange ( intStmMultiSet  ac,
intStmMultiSetIterator  first,
intStmMultiSetIterator  last 
) [static]

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

Parameters:
[in] ac The intStmMultiSet object.
[in] first The intStmMultiSetIterator object referencing the first element to be erased.
[in] last The intStmMultiSetIterator 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:
intStmMultiSetIteratorDereferenceable(), intStmMultiSetInsert(), intStmMultiSetFind(), intStmMultiSetCount().

static int intStmMultiSetEraseElem ( intStmMultiSet  ac,
const int *  elem 
) [static]

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

Parameters:
[in] ac The intStmMultiSet object.
[in] elem A pointer to the int 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:
intStmMultiSetInsert(), intStmMultiSetFind(), intStmMultiSetCount().

static int intStmMultiSetEraseKey ( intStmMultiSet  ac,
int  key 
) [static]

Erase all elements with value key from the intStmMultiSet object ac.

Parameters:
[in] ac The intStmMultiSet object.
[in] key The int object being equivalent to the elements to be erased.
Effects:
All elements equivalent to 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:
intStmMultiSetInsert(), intStmMultiSetFindKey(), intStmMultiSetCountKey().

static int intStmMultiSetClear ( intStmMultiSet  ac  )  [static]

Erase all elements from the intStmMultiSet ac.

Parameters:
[in] ac The intStmMultiSet 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:
intStmMultiSetErase(), intStmMultiSetEraseRange().
Examples:
dsettst.c.

static intStmMultiSetIterator intStmMultiSetFind ( intStmMultiSet  ac,
const int *  elem 
) [static]

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

Parameters:
[in] ac The intStmMultiSet object.
[in] elem A pointer to the int 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 intStmMultiSetIterator object, if no element equivalent to the element pointed to by elem is contained in ac.

A intStmMultiSetIterator 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 intStmMultiSetIterator object returned. If that is an issue, consider to use intStmMultiSetCount() instead.
See also:
intStmMultiSetIteratorDereferenceable(), intStmMultiSetInsert(), intStmMultiSetErase(), intStmMultiSetCount().
Examples:
dsettst.c.

static intStmMultiSetIterator intStmMultiSetFindKey ( intStmMultiSet  ac,
int  key 
) [static]

Find an element in the intStmMultiSet object ac with value key.

Parameters:
[in] ac The intStmMultiSet object.
[in] key The int object being equivalent to the element to be found.
Effects:
The function looks for an element contained in ac being equivalent to the element 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 intStmMultiSetIterator object, if no element equivalent to key is contained in ac.

A intStmMultiSetIterator object referencing an element equivalent to key contained in ac.

Note:
If more than one element equivalent to key is contained in ac, it is unspecified which one of them is referenced by the intStmMultiSetIterator object returned. If that is an issue, consider to use intStmMultiSetCountKey() instead.
See also:
intStmMultiSetIteratorDereferenceable(), intStmMultiSetInsert(), intStmMultiSetEraseKey(), intStmMultiSetCountKey().

static int intStmMultiSetCount ( intStmMultiSet  ac,
const int *  elem,
intStmMultiSetIterator first,
intStmMultiSetIterator last 
) [static]

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

Parameters:
[in] ac The intStmMultiSet object.
[in] elem A pointer to the int object being equivalent to the elements to be found.
[out] first If not NULL, the address of the intStmMultiSetIterator object expected to reference the first element found.
[out] last If not NULL, the address of the intStmMultiSetIterator 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 intStmMultiSetIterator 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:
intStmMultiSetInsert(), intStmMultiSetErase(), intStmMultiSetFind().

static int intStmMultiSetCountKey ( intStmMultiSet  ac,
int  key,
intStmMultiSetIterator first,
intStmMultiSetIterator last 
) [static]

Return the number of elements in the intStmMultiSet object ac having value key and optionally determine the range of the elements found.

Parameters:
[in] ac The intStmMultiSet object.
[in] key The int object being equivalent to the elements to be found.
[out] first If not NULL, the address of the intStmMultiSetIterator object expected to reference the first element found.
[out] last If not NULL, the address of the intStmMultiSetIterator 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 key and updates the intStmMultiSetIterator 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 equivalent to key contained in ac.

See also:
intStmMultiSetInsert(), intStmMultiSetEraseKey(), intStmMultiSetFindKey().


© Copyright Tom Michaelis 2002-2007

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