Home Libraries Author Links

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

Collaboration diagram for Abstract Set Type Example:

Detailed Description

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


Files

file  intStmSetDoc.h
 Documentation of the abstract set type intStmSet.

intStmSet Representation

Objects of abstract set type intStmSet and their iterators of type intStmSetIterator are represented by pointers to their implementation structures of type intStmSetImpl_ and intStmSetIteratorImpl_, respectively.

typedef struct intStmSetImpl_ * intStmSet
 A valid intStmSet object is represented as a pointer to its implementation structure intStmSetImpl_.
typedef struct
intStmSetIteratorImpl_ * 
intStmSetIterator
 A valid intStmSetIterator object is represented as a pointer to its implementation structure intStmSetIteratorImpl_.
#define StmSetDoc_

intStmSet Creation and Destruction

static intStmSet intStmSetCreate (void)
 Creation of a new intStmSet object.
static void intStmSetDestroy (intStmSet ac)
 Destruction of the intStmSet object ac.

intStmSet Iterators

static intStmSetIterator intStmSetBegin (intStmSet ac)
 Return an iterator to the first element of the intStmSet object ac.
static intStmSetIterator intStmSetEnd (intStmSet ac)
 Return an iterator to one past the last element of the intStmSet object ac.
static intStmSetIterator intStmSetRBegin (intStmSet ac)
 Return an iterator to the last element of the intStmSet object ac.
static intStmSetIterator intStmSetREnd (intStmSet ac)
 Return an iterator to one before the first element of the intStmSet object ac.
static intStmSetIterator intStmSetIteratorNext (intStmSetIterator iter)
 Return an iterator to the element following the one referenced by iter.
static intStmSetIterator intStmSetIteratorPrev (intStmSetIterator iter)
 Return an iterator to the element preceding the one referenced by iter.
static StmBool intStmSetIteratorDereferenceable (intStmSetIterator iter)
 Return StmTrue, if iter is dereferenceable.
static StmBool intStmSetIteratorDereferencable (intStmSetIterator iter)
 Return StmTrue, if iter is dereferenceable.
static const int * intStmSetIteratorElem (intStmSetIterator iter)
 Return a pointer to the constant element referenced by iter.
static int intStmSetIteratorKey (intStmSetIterator iter)
 Return a copy of the element referenced by iter.

intStmSet Capacity

static int intStmSetSize (intStmSet ac)
 Return the element count of the intStmSet object ac.
static int intStmSetMaxSize (intStmSet ac)
 Return the maximal possible element count of the intStmSet object ac.
static StmBool intStmSetEmpty (intStmSet ac)
 Return StmTrue, if the intStmSet object ac is empty.

intStmSet Modifiers

static intStmSetIterator intStmSetInsert (intStmSet ac, const int *elem, StmBool *inserted)
 Insert the element pointed to by elem into the intStmSet object ac.
static int intStmSetErase (intStmSet ac, intStmSetIterator iter)
 Erase the element referenced by iter from the intStmSet object ac.
static int intStmSetEraseRange (intStmSet ac, intStmSetIterator first, intStmSetIterator last)
 Erase the elements referenced by the half open interval [first, last) from the intStmSet object ac.
static int intStmSetEraseElem (intStmSet ac, const int *elem)
 Erase all elements equivalent to the element pointed to by elem from the intStmSet object ac.
static int intStmSetEraseKey (intStmSet ac, int key)
 Erase all elements with value key from the intStmSet object ac.
static int intStmSetClear (intStmSet ac)
 Erase all elements from the intStmSet ac.

intStmSet Operations

static intStmSetIterator intStmSetFind (intStmSet ac, const int *elem)
 Find an element in the intStmSet object ac equivalent to the element pointed to by elem.
static intStmSetIterator intStmSetFindKey (intStmSet ac, int key)
 Find an element in the intStmSet object ac with value key.
static int intStmSetCount (intStmSet ac, const int *elem, intStmSetIterator *first, intStmSetIterator *last)
 Return the number of elements in the intStmSet object ac being equivalent to the element pointed to by elem and optionally determine the range of the elements found.
static int intStmSetCountKey (intStmSet ac, int key, intStmSetIterator *first, intStmSetIterator *last)
 Return the number of elements in the intStmSet object ac having value key and optionally determine the range of the elements found.


Typedef Documentation

typedef struct intStmSetImpl_* intStmSet

A valid intStmSet object is represented as a pointer to its implementation structure intStmSetImpl_.

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

Examples:
dsettst.c.

Definition at line 77 of file intStmSetDoc.h.

typedef struct intStmSetIteratorImpl_* intStmSetIterator

A valid intStmSetIterator object is represented as a pointer to its implementation structure intStmSetIteratorImpl_.

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

Examples:
dsettst.c.

Definition at line 88 of file intStmSetDoc.h.


Function Documentation

static intStmSet intStmSetCreate ( void   )  [static]

Creation of a new intStmSet object.

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

The intStmSet object created on success.

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

static void intStmSetDestroy ( intStmSet  ac  )  [static]

Destruction of the intStmSet object ac.

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

static intStmSetIterator intStmSetBegin ( intStmSet  ac  )  [static]

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

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

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

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

See also:
intStmSetEmpty(), intStmSetIteratorDereferenceable(), intStmSetEnd().
Examples:
dsettst.c.

static intStmSetIterator intStmSetEnd ( intStmSet  ac  )  [static]

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

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

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

See also:
intStmSetEmpty(), intStmSetIteratorDereferenceable(), intStmSetBegin().
Examples:
dsettst.c.

static intStmSetIterator intStmSetRBegin ( intStmSet  ac  )  [static]

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

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

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

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

See also:
intStmSetEmpty(), intStmSetIteratorDereferenceable(), intStmSetREnd().

static intStmSetIterator intStmSetREnd ( intStmSet  ac  )  [static]

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

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

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

See also:
intStmSetEmpty(), intStmSetIteratorDereferenceable(), intStmSetRBegin().

static intStmSetIterator intStmSetIteratorNext ( intStmSetIterator  iter  )  [static]

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

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

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

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

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

See also:
intStmSetIteratorDereferenceable(), intStmSetBegin (), intStmSetIteratorPrev().
Examples:
dsettst.c.

static intStmSetIterator intStmSetIteratorPrev ( intStmSetIterator  iter  )  [static]

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

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

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

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

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

See also:
intStmSetIteratorDereferenceable(), intStmSetEnd (), intStmSetIteratorNext().

static StmBool intStmSetIteratorDereferenceable ( intStmSetIterator  iter  )  [static]

Return StmTrue, if iter is dereferenceable.

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

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

static StmBool intStmSetIteratorDereferencable ( intStmSetIterator  iter  )  [static]

Return StmTrue, if iter is dereferenceable.

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

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

static const int* intStmSetIteratorElem ( intStmSetIterator  iter  )  [static]

Return a pointer to the constant element referenced by iter.

Parameters:
[in] iter The intStmSetIterator 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:
intStmSetIteratorDereferenceable(), intStmSetIteratorKey ().
Examples:
dsettst.c.

static int intStmSetIteratorKey ( intStmSetIterator  iter  )  [static]

Return a copy of the element referenced by iter.

Parameters:
[in] iter The intStmSetIterator 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:
intStmSetIteratorDereferenceable(), intStmSetIteratorElem ().

static int intStmSetSize ( intStmSet  ac  )  [static]

Return the element count of the intStmSet object ac.

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

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

See also:
intStmSetMaxSize (), intStmSetEmpty ().
Examples:
dsettst.c.

static int intStmSetMaxSize ( intStmSet  ac  )  [static]

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

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

See also:
intStmSetSize (), intStmSetEmpty ().

static StmBool intStmSetEmpty ( intStmSet  ac  )  [static]

Return StmTrue, if the intStmSet object ac is empty.

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

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

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

See also:
intStmSetSize (), intStmSetMaxSize ().

static intStmSetIterator intStmSetInsert ( intStmSet  ac,
const int *  elem,
StmBool inserted 
) [static]

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

Parameters:
[in] ac The intStmSet object.
[in] elem A pointer to the constant int 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 intStmSet 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 intStmSetIterator object referencing that element of ac being equivalent to the int object pointed to by elem.

See also:
intStmSetErase(), intStmSetFind(), intStmSetCount().
Examples:
dsettst.c.

static int intStmSetErase ( intStmSet  ac,
intStmSetIterator  iter 
) [static]

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

Parameters:
[in] ac The intStmSet object.
[in] iter The intStmSetIterator 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:
intStmSetIteratorDereferenceable(), intStmSetInsert(), intStmSetFind(), intStmSetCount().

static int intStmSetEraseRange ( intStmSet  ac,
intStmSetIterator  first,
intStmSetIterator  last 
) [static]

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

Parameters:
[in] ac The intStmSet object.
[in] first The intStmSetIterator object referencing the first element to be erased.
[in] last The intStmSetIterator 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:
intStmSetIteratorDereferenceable(), intStmSetInsert(), intStmSetFind(), intStmSetCount().

static int intStmSetEraseElem ( intStmSet  ac,
const int *  elem 
) [static]

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

Parameters:
[in] ac The intStmSet 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:
intStmSetInsert(), intStmSetFind(), intStmSetCount().

static int intStmSetEraseKey ( intStmSet  ac,
int  key 
) [static]

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

Parameters:
[in] ac The intStmSet 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:
intStmSetInsert(), intStmSetFindKey(), intStmSetCountKey().
Examples:
dsettst.c.

static int intStmSetClear ( intStmSet  ac  )  [static]

Erase all elements from the intStmSet ac.

Parameters:
[in] ac The intStmSet 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:
intStmSetErase(), intStmSetEraseRange().
Examples:
dsettst.c.

static intStmSetIterator intStmSetFind ( intStmSet  ac,
const int *  elem 
) [static]

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

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

A intStmSetIterator 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 intStmSetIterator object returned. If that is an issue, consider to use intStmSetCount() instead.
See also:
intStmSetIteratorDereferenceable(), intStmSetInsert(), intStmSetErase(), intStmSetCount().

static intStmSetIterator intStmSetFindKey ( intStmSet  ac,
int  key 
) [static]

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

Parameters:
[in] ac The intStmSet 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 intStmSetIterator object, if no element equivalent to key is contained in ac.

A intStmSetIterator 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 intStmSetIterator object returned. If that is an issue, consider to use intStmSetCountKey() instead.
See also:
intStmSetIteratorDereferenceable(), intStmSetInsert(), intStmSetEraseKey(), intStmSetCountKey().

static int intStmSetCount ( intStmSet  ac,
const int *  elem,
intStmSetIterator first,
intStmSetIterator last 
) [static]

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

Parameters:
[in] ac The intStmSet 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 intStmSetIterator object expected to reference the first element found.
[out] last If not NULL, the address of the intStmSetIterator 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 intStmSetIterator 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:
intStmSetInsert(), intStmSetErase(), intStmSetFind().

static int intStmSetCountKey ( intStmSet  ac,
int  key,
intStmSetIterator first,
intStmSetIterator last 
) [static]

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

Parameters:
[in] ac The intStmSet object.
[in] key The int object being equivalent to the elements to be found.
[out] first If not NULL, the address of the intStmSetIterator object expected to reference the first element found.
[out] last If not NULL, the address of the intStmSetIterator 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 intStmSetIterator 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:
intStmSetInsert(), intStmSetEraseKey(), intStmSetFindKey().


© Copyright Tom Michaelis 2002-2007

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