iBase.h

Go to the documentation of this file.

#ifndef _ITAPS_iBase
#define _ITAPS_iBase
 
/***************************************************************************/ /**
 * \ingroup
 *VersionNumbers
 * \brief Compile time
 *version number
 *digits
 *
 * iBase maintains a
 *major, minor and
 *patch digit in its
 *version number.
 * Technically
 *speaking, there is
 *not much practical
 *value in patch digit
 * for an interface
 *specification. A
 *patch release is
 *typically only used
 * for bug fix
 *releases. Although
 *it is rare,
 *sometimes a bug fix
 * necessitates an API
 *change. So, we
 *define a patch digit
 *for iBase.
 *
 * Although each
 *interface in ITAPS
 *has been designed to
 *support its own
 * unique version
 *numbers, apart from
 *other ITAPS
 *interfaces, as
 *currently used, we
 *require all ITAPS
 *interfaces to use
 *the same ITAPS-wide
 *version number
 *derived from the
 *version number
 *defined by these
 *three digits.
 ******************************************************************************/
#define IBASE_VERSION_MAJOR 1
#define IBASE_VERSION_MINOR 4
#define IBASE_VERSION_PATCH 1
 
/***************************************************************************/ /**
 * \ingroup
 *VersionNumbers
 * \brief Version
 *Comparison
 *
 * Evaluates to true
 *at CPP time if the
 *version of iBase
 *currently being
 * compiled is greater
 *than or equal to the
 *version specified.
 ******************************************************************************/
#define IBASE_VERSION_GE( Maj, Min, Pat ) \
 ( ( ( IBASE_VERSION_MAJOR == ( Maj ) ) && ( IBASE_VERSION_MINOR == ( Min ) ) && \
 ( IBASE_VERSION_PATCH >= ( Pat ) ) ) || \
 ( ( IBASE_VERSION_MAJOR == ( Maj ) ) && ( IBASE_VERSION_MINOR > ( Min ) ) ) || \
 ( IBASE_VERSION_MAJOR > ( Maj ) ) )
 
/***************************************************************************/ /**
 * \ingroup
 *VersionNumbers
 * \brief Compose
 *compile-time string
 *represention of the
 *version number
 ******************************************************************************/
#define IBASE_VERSION_STRING___( I, X, Y, Z ) #I "_Version_" #X "." #Y "." #Z
#define IBASE_VERSION_STRING__( I, X, Y, Z ) IBASE_VERSION_STRING___( I, X, Y, Z )
#define IBASE_VERSION_STRING_( I ) \
 IBASE_VERSION_STRING__( I, IBASE_VERSION_MAJOR, IBASE_VERSION_MINOR, IBASE_VERSION_PATCH )
#define IBASE_VERSION_STRING IBASE_VERSION_STRING_( iBase )
 
/***************************************************************************/ /**
 * \ingroup
 *VersionNumbers
 * \brief Compose
 *compile-time symbol
 *name derived from
 *the version number.
 ******************************************************************************/
#define IBASE_VERSION_TAG__( I, X, Y, Z ) I##_Version_##X##_##Y##_##Z
#define IBASE_VERSION_TAG_( I, X, Y, Z ) IBASE_VERSION_TAG__( I, X, Y, Z )
#define IBASE_VERSION_TAG( I ) IBASE_VERSION_TAG_( I, IBASE_VERSION_MAJOR, IBASE_VERSION_MINOR, IBASE_VERSION_PATCH )
 
/***************************************************************************/ /**
 * \ingroup
 *VersionNumbers
 * \brief ITAPS-wide
 *(across all ITAPS
 *APIs) version
 *handling
 ******************************************************************************/
#define ITAPS_VERSION_MAJOR IBASE_VERSION_MAJOR
#define ITAPS_VERSION_MINOR IBASE_VERSION_MINOR
#define ITAPS_VERSION_PATCH IBASE_VERSION_PATCH
#define ITAPS_VERSION_GE( Maj, Min, Pat ) IBASE_VERSION_GE( Maj, Min, Pat )
#define ITAPS_VERSION_STRING_( I ) IBASE_VERSION_STRING_( I )
#define ITAPS_VERSION_STRING ITAPS_VERSION_STRING_( ITAPS )
#define ITAPS_VERSION_TAG_( I ) IBASE_VERSION_TAG( I )
#define ITAPS_VERSION_TAG ITAPS_VERSION_TAG_( I )
 
/***************************************************************************/ /**
 * \defgroup
 *EnumIterators
 *Enum-Iterators
 * \ingroup iBase
 * \brief Convenience
 *macros for iterating
 *over all possible
 *values in an enum
 *
 * These convenience
 *macros are provided
 *to facilitate
 *iterating over all
 * possible values in
 *an enumerated type.
 *To use these macros,
 *for example... \code
 * for
 *(iBase_EntityType i
 *=
 *IBASE_MINENUM(iBase_EntityType);
 * i
 *<=
 *IBASE_MAXENUM(iBase_EntityType);
 * IBASE_INCENUM(i,iBase_EntityType))
 * {
 * }
 * \endcode
 * Be aware that some
 *enumerated types
 *include a <em>wild
 *card</em> often used
 * in queries to
 *represent all
 *possible values and
 *you may or may not
 *want to include such
 *a value in your
 *iteration.
 ******************************************************************************/
 
/***************************************************************************/ /**
 * \ingroup
 *EnumIterators
 * @{
 ******************************************************************************/
#define IBASE_MINENUM( enumName ) enumName##_MIN
#define IBASE_MAXENUM( enumName ) enumName##_MAX
#define IBASE_NUMENUM( enumName ) ( (int)IBASE_MAXENUM( enumName ) - (int)IBASE_MINENUM( enumName ) + 1 )
#define IBASE_INCENUM( enumName, I ) ( ( I ) = ( enum( enumName ) )( (int)( I ) + 1 ) )
/** @} */
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef void* iBase_Instance;
typedef struct iBase_EntityHandle_Private* iBase_EntityHandle;
typedef struct iBase_EntitySetHandle_Private* iBase_EntitySetHandle;
typedef struct iBase_TagHandle_Private* iBase_TagHandle;
typedef struct iBase_EntityIterator_Private* iBase_EntityIterator;
typedef struct iBase_EntityArrIterator_Private* iBase_EntityArrIterator;
 
enum iBase_EntityType
{
 iBase_EntityType_MIN = 0,
 /**< facilitates iteration over all values */
 iBase_VERTEX = iBase_EntityType_MIN,
 /**< A topological dimension 0 entity */
 iBase_EDGE,
 /**< A topological dimension 1 entity */
 iBase_FACE,
 /**< A topological dimension 2 entity */
 iBase_REGION,
 /**< A topological dimension 3 entity */
 iBase_ALL_TYPES,
 /**< used only in queries to request information about all types */
 iBase_EntityType_MAX = iBase_ALL_TYPES
 /**< facilitates iteration over all values */
};
 
enum iBase_AdjacencyCost
{
 iBase_AdjacencyCost_MIN = 0,
 /**< facilitates iteration over all values */
 iBase_UNAVAILABLE = iBase_AdjacencyCost_MIN,
 /**< Adjacency information not supported */
 iBase_ALL_ORDER_1,
 /**< No more than local mesh traversal required (i!=j) */
 iBase_ALL_ORDER_LOGN,
 /**< Global tree search (i!=j) */
 iBase_ALL_ORDER_N,
 /**< Global exhaustive search (i!=j) */
 iBase_SOME_ORDER_1,
 /**< Only some adjacency info, local (i!=j) */
 iBase_SOME_ORDER_LOGN,
 /**< Only some adjacency info, tree (i!=j) */
 iBase_SOME_ORDER_N,
 /**< Only some adjacency info, exhaustive (i!=j) */
 iBase_AVAILABLE,
 /**< ALL (intermediate) entities available. (i==j) */
 iBase_AdjacencyCost_MAX = iBase_AVAILABLE
 /**< facilitates iteration over all values */
};
 
enum iBase_CreationStatus
{
 iBase_CreationStatus_MIN = 0,
 /**< facilitates iteration over all values */
 iBase_NEW = iBase_CreationStatus_MIN,
 /**< The entity was newly created */
 iBase_ALREADY_EXISTED,
 /**< The entity already existed and the handle for that
 already existing handle was returned */
 iBase_CREATED_DUPLICATE,
 /**< The entity already existed but a new, duplicate entity was
 nevertheless created */
 iBase_CREATION_FAILED,
 /**< Creation of the entity did not succeed */
 iBase_CreationStatus_MAX = iBase_CREATION_FAILED
 /**< facilitates iteration over all values */
};
 
enum iBase_ErrorType
{
 iBase_ErrorType_MIN = 0,
 /**< facilitates iteration over all values */
 iBase_SUCCESS = iBase_ErrorType_MIN,
 iBase_MESH_ALREADY_LOADED,
 iBase_FILE_NOT_FOUND,
 iBase_FILE_WRITE_ERROR,
 iBase_NIL_ARRAY,
 iBase_BAD_ARRAY_SIZE,
 iBase_BAD_ARRAY_DIMENSION,
 iBase_INVALID_ENTITY_HANDLE,
 iBase_INVALID_ENTITY_COUNT,
 iBase_INVALID_ENTITY_TYPE,
 iBase_INVALID_ENTITY_TOPOLOGY,
 iBase_BAD_TYPE_AND_TOPO,
 iBase_ENTITY_CREATION_ERROR,
 iBase_INVALID_TAG_HANDLE,
 iBase_TAG_NOT_FOUND,
 iBase_TAG_ALREADY_EXISTS,
 iBase_TAG_IN_USE,
 iBase_INVALID_ENTITYSET_HANDLE,
 iBase_INVALID_ITERATOR_HANDLE,
 iBase_INVALID_ARGUMENT,
 iBase_MEMORY_ALLOCATION_FAILED,
 iBase_NOT_SUPPORTED,
 iBase_FAILURE,
 iBase_ErrorType_MAX = iBase_FAILURE
 /**< facilitates iteration over all values */
};
 
/***************************************************************************/ /**
 * \details
 * Many of the
 *functions in iMesh
 *can return arrays of
 *tuples; that is,
 *arrays of
 *multi-valued type.
 *For example, the
 *function
 *iMesh_getVtxArrCoords,
 * returns an array of
 *xyz coordinate
 *3-tuples (or,
 *perhaps for
 *geometrically 2D
 *meshes, xy
 *2-tuples). In these
 *situations, there
 *are multiple ways
 *the data can be
 *organized in memory.
 *For example, it
 *could be stored
 *xyz,xyz,xyz or
 *xxx...,yyy...,zzz....
 *These two different
 *storage orders are
 *referred to as
 *INTERLEAVED and
 *BLOCKED,
 *respectively. For
 *some functions in
 *iMesh, the storage
 *order is explicitly
 *specified as an
 *argument to the
 *function. For other
 *functions, the
 *storage order is not
 *explicitly
 *specified. And, in
 *these cases, it
 *shall always be
 *implicitly assumed
 *to be INTERLEAVED.
 * This fact will be
 *mentioned in the
 *documentation for
 *each specific
 *function where it
 *applies. For
 *example, in case of
 *iMesh_getEntArrAdj,
 *the returned array
 *of adjacent entities
 *is multi-valued in
 *that it stores for
 *each entity queried,
 *all its adjacent
 *entities. Such an
 *array will be stored
 * INTERLEAVED with
 *all adjacent
 *entities for the
 *first entity in the
 *query followed by
 *all adjacent
 *entities for the
 *second entity in the
 *query and so forth.
 ******************************************************************************/
enum iBase_StorageOrder
{
 iBase_StorageOrder_MIN = 0,
 /**< facilitates iteration over all values */
 iBase_BLOCKED = iBase_StorageOrder_MIN,
 /**< xxx...yyy...zzz... */
 iBase_INTERLEAVED,
 /**< xyzxyzxyz... */
 iBase_StorageOrder_MAX = iBase_INTERLEAVED
 /**< facilitates iteration over all values */
};
 
enum iBase_TagValueType
{
 iBase_TagValueType_MIN = 0,
 /**< facilitates iteration over all values */
 iBase_BYTES = iBase_TagValueType_MIN,
 /**< An opaque sequence of bytes, size always measured in bytes */
 iBase_INTEGER,
 /**< A value of type \c int */
 iBase_DOUBLE,
 /**< A value of type \c double */
 iBase_ENTITY_HANDLE,
 /**< A value of type \c iBase_EntityHandle */
 iBase_ENTITY_SET_HANDLE,
 /**< A value of type \c iBase_EntitySetHandle */
 iBase_TagValueType_MAX = iBase_ENTITY_SET_HANDLE
 /**< facilitates iteration over all values */
};
 
/***************************************************************************/ /**
 * \page ibase iBase:
 *ITAPS Base Interface
 ******************************************************************************/
 
/***************************************************************************/ /**
 * \defgroup iBase
 *iBase
 ******************************************************************************/
 
/***************************************************************************/ /**
 * \defgroup
 *VersionNumbers
 *Version Numbers
 * \ingroup iBase
 ******************************************************************************/
 
/***************************************************************************/ /**
 * \defgroup
 *ErrorHandling Error
 *Handling \ingroup
 *iBase
 ******************************************************************************/
 
/***************************************************************************/ /**
 * \defgroup Datatypes
 *Datatypes \ingroup
 *iBase
 ******************************************************************************/
 
/***************************************************************************/ /**
 * \page The ITAPS Interfaces
 *
 * \subpage ibase
 *
 * \subpage imesh
 *
 * \subpage imeshp
 *
 * \subpage error
 *
 * \subpage trio
 *
 * \subpage strlen
 *
 * \subpage options
 *
 * \subpage numhops
 *
 * \subpage resilient
 *
 * \page error Error Handling
 *
 * With few exceptions, every iMesh function includes an output argument,
 * 'int *err', which returns an error code indicating if the function call
 * may have failed. If the value returned for the 'err' argument is NOT
 * iBase_SUCCESS, the caller should NOT attempt to interpret (read the
 * values in) any of the other return arguments of the call. While some
 * implementations may actually return valid/useful results in other
 * return arguments of a call that has failed, there is no guarentee that
 * ALL implementations will do similarly and so depending on such behavior
 * is neither portable nor safe. This is true even if the returned values
 * are different from the values of the arguments before the call was
 * made.
 *
 * \page trio Array pointer, allocated and occupied sizes argument trio
 *
 * Many of the functions in iMesh have arguments corresponding to lists of
 * objects. In-type arguments for lists consist of a pointer to an array and
 * a list size. Lists returned from functions are passed in three arguments,
 * a pointer to the array representing the list, and pointers to the
 * allocated and occupied lengths of the array. These three arguments are
 * inout-type arguments, because they can be allocated by the application and
 * passed into the interface to hold the results of the function. Lists
 * which are pre-allocated must be large enough to hold the results of the
 * function; if this is not the case, an error is generated. Otherwise, the
 * occupied size is changed to the size output from the function. If a list
 * argument is unallocated (the list pointer points to a NULL value) or if
 * the incoming value of the allocated size is zero, the list storage will be
 * allocated by the implementation.
 *
 * IN ALL CASES, MEMORY ALLOCATED BY ITAPS INTERFACE IMPLEMENTATIONS IS DONE
 * USING THE C MALLOC FUNCTION, AND MUST BE DE-ALLOCATED USING THE C FREE
 * FUNCTION.
 *
 * \page strlen String Length Arguments
 *
 * Many of the functions in iMesh involve passing a string and also the length
 * of that string. How is the null character is handled?
 * For users of the iMesh interface calling iMesh functions, it is optional
 * as to whether or not to include the null character in computing the length
 * of the string. So, for example, calling iMesh from a C program, users could
 * pass strlen(my_string) or strlen(my_string)+1 as the length of the string.
 *
 * <em>Note to implementors</em>: However, it should be noted that the situation
 * is different for implementers of the iMesh interface. In implementing an
 * iMesh interface function, there can be no assumption that the string is
 * indeed null terminated. The length argument the caller passes in may or may
 * NOT include the null character and implementations must be coded to
 * accommodate this. This requirement is primarily due to differences in how
 * Fortran and C/C++ handle passing of strings as function arguments.
 * Furthermore, because of the way Fortran clients pass strings (Fortran always
 * passes the length of the string as declared in the source code), there
 * may be trailing spaces in the string that need to be truncated.
 *
 * \page numhops Indirection in Set-Inclusion and Parent-Child structures
 *
 * Various functions to query entities, entity sets and parent or child sets
 * as well as the numbers of these involve a num_hops argument. If the set
 * upon which the query is originated is the root set, the num_hops argument
 * is irrelevant and is ignored by the implementation. Otherwise, the num_hops
 * argument represents the maximum number of levels of indirection employed in
 * satisfying the query not including the originating set. For example, using
 * value for num_hops of 0 (zero) in iMesh_getEntSets will return all the
 * entity sets that are immediately contained in a given set. Likewise, a
 * value for num_hops of 1 (one) will return all entity sets that are
 * immediately contained in the given set plus all entity sets that
 * are contained in those immediately contained sets (e.g. one level of
 * indirection). Using a value of -1 for num_hops will return results for
 * all possible levels of indirection. In other words, using a value of
 * -1 for num_hops is equivalent to setting the maximum number of levels
 * of indirection to infinity.
 *
 * \page options Option Strings
 *
 * A few of the functions in iMesh support arbitrary options passed as a
 * character string, called an 'Option String'. The format of and handling
 * of an Option String is as follows...
 *
 * 1. Option Strings are INsensitive to case.
 *
 * 2. Each option in an Option String is pre-pended with the implementation
 * name followed by a special character called the separator character.
 *
 * 3. The separator is a colon, ':'.
 *
 * 4. Multiple options existing in a single Option String are separated by a
 * special character called the delimiter character.
 *
 * 5. The delimiter character is a space, ' '.
 *
 * 6. The effect of multiple options in a single Option String is
 * INsensitive to order of occurrence in the string.
 *
 * 7. By default, implementations silently ignore any options that
 * do not match on the implementation name part (everything before
 * the separator character). This way, a caller may included options
 * in a single string intended for multiple different implementations.
 *
 * 8. Implementations may (or may not) warn or error for option strings
 * that match on implementation name part but are found to be in error
 * for other reasons the implementation decides.
 *
 * 9. Whenever either the separator character, ':', or delimiter character,
 * ' ', need to appear in an option, they must be escaped with the
 * backslash character, '\'.
 *
 * For example, consider the Options String
 *
 * "grummp:silant FMDB:TwoPhaseIO moab:mpiio_hints\ foo\:bar"
 *
 * In the above example, the space serves as the delimiter character
 * between multiple options in the string. The colon serves as the
 * implementation-name/option separator character. Because options are
 * required to be insensitive to case, the caller is free to use case as a
 * word separator as in 'TwoPhaseIO' and even in the implementation name,
 * as in 'FMDB:', although 'fmdb:twophaseio' and 'fmdb:TWOPHASEIO' would
 * all have the same effect. In the moab option, both the separator
 * character and delimiter character appear in the option and so are
 * pre-pended (e.g. escaped) with the backslash character.
 
 * GRUMMP will silently ignore the FMDB: and moab: options because they do
 * NOT match on the implementation name part. However, GRUMMP may
 * optionally error out, or warn or silently ignore 'grummp:silant' (it was
 * supposed to be spelled 'silent') as an invalid option.
 *
 * Note that iMesh itself currently does not define any options. In order
 * to discover options a given implementation defines, users are directed
 * to the developers of the respective implementations.
 *
 * \page resilient Resilient and Non-Resilient Iterators
 *
 * A resilient iterator is one that can deal with modifications to the container
 * it is iterating over.
 *
 * A common concern about an iterator is how it behaves when the container
 * over which it is iterating is modified. For example, in STL, iterators
 * for std::set<> and std::map<> and std::list<> containers are guaranteed
 * to <em>work</em> in the presence of modifications to the associated
 * containers with one exception; they don't handle the case when the
 * container member the iterator is currently pointed at is deleted. However,
 * iterators for std::vector<> are not guaranteed to work under any kinds of
 * modification.
 *
 * In the ITAPS interfaces, a <em>resilient</em> iterator is one that makes
 * certain guarantees (described below) about how it behaves when the
 * container being iterated is modified. On the other hand, a
 * <em>non-resilient</em> is one that does not make such guarantees.
 *
 * In all cases, the <em>container</em> associated with an iterator in the
 * ITAPS interfaces is an entity set of some sort. This is the only container
 * type for which iterators are defined.
 *
 * Here, we characterize the behavior of iterators in the presence of
 * container modifications. There are a number of (subtle) aspects to
 * keep in mind.
 *
 * 1. There are set-type (<em>duplicate preventing</em>) sets and list-type
 * (<em>order preserving</em>) sets and iterators behave differently for each.
 *
 * 2. Sets can have <em>set</em> members and <em>entity</em> members. However,
 * iterators are currently defined to iterate over <em>only</em> the entity
 * members. That said, the question arises as to whether modifications that
 * involve only set members nonetheless <em>effect</em> iterator behavior.
 *
 * 3. There are array-type iterators that upon each step in the iteration
 * return a whole array of entity member handles and single entity iterators
 * that upon each step return just a single entity member handle.
 *
 * 4. The iterators support type/topology <em>filtering</em>. Iterators do not
 * (always) strictly iterate over <em>all</em> entities in a set; just
 * <em>all</em> entities matching the type/topology criteria. When
 * type/topology specifies either all types or all topologies, then indeed
 * the iterator will iterate over all entities.
 *
 * 5. There are add/remove operations that add/remove <em>entity members</em> or
 * <em>set members</em> to a set.
 *
 * 6. There are create/delete operations that create and delete
 * <em>entities</em> from the whole iMesh_Instance.
 *
 * 7. There are create/destroy operations that create and destroy
 * <em>sets</em> from the whole interface instance.
 *
 * 8. There is the <em>root set</em> which is special and may have different
 * iterator behavior than all other sets. By definition, the root set is a set-type
 * (<em>duplicate prevent</em>) set.
 *
 * Modification means addition/removal and/or create/destroy and/or create/delete
 * <em>after</em> iterator initialization. When we talk about
 * <em>container modification</em> here, we are talking about any of the
 * following operations.
 *
 * A. addition and removal of entity members
 * \code
 * void iMesh_rmvEntFromSet(iMesh_Instance instance,
 * void iMesh_rmvEntArrFromSet(iMesh_Instance instance,
 * void iMesh_addEntToSet(iMesh_Instance instance,
 * void iMesh_addEntArrToSet(iMesh_Instance instance,
 * \endcode
 * B. addition and removal of set members
 * \code
 * void iMesh_rmvEntSet(iMesh_Instance instance,
 * void iMesh_addEntSet(iMesh_Instance instance,
 * \endcode
 * C. deletion of entities from whole iMesh_Instance
 * \code
 * void iMesh_deleteEntArr(iMesh_Instance instance,
 * void iMesh_deleteEnt(iMesh_Instance instance,
 * \endcode
 * D. creation of entities (effects root set)
 * \code
 * void iMesh_createEntSet(iMesh_Instance instance,
 * void iMesh_createVtxArr(iMesh_Instance instance,
 * void iMesh_createEntArr(iMesh_Instance instance,
 * void iMesh_createVtx(iMesh_Instance instance,
 * void iMesh_createEnt(iMesh_Instance instance,
 * \endcode
 * E. destruction of entity sets
 * \code
 * void iMesh_destroyEntSet(iMesh_Instance instance,
 * \endcode
 
 * By container modification, we mean that of the above operations occur on
 * the container between iterator initialization and reset.
 *
 * For purposes of this discussion, there is no distinction between any of
 * these <em>kinds of</em> modifications. What is true for any is true for
 * all. Below, the words <em>add</em> and <em>remove</em> are used to
 * represent any of the modifications that add members or remove members
 * regardless of the <em>kind of operation</em> above.
 *
 * Resilient iterators are not effected by modifications involving set members:
 *
 * Iterators are currently defined to iterate over *only* the entity members
 * of a container. In particular, if the container is modified by
 * adding/removing sets from the container, this will have no impact on
 * the iterator. This is true for set-type sets and list-type sets.
 *
 * Resilient iterator's <em>current position</em> not effected by modification:
 *
 * If the container is modified, the iterator will continue to properly
 * <em>keep track of</em> the member it was currently pointing at. If a
 * modification occurs that removes the member it was currently pointing at,
 * the iterator will be advanced to the <em>next</em> (not already deleted)
 * member it would have proceeded to. In this way, the iterator is guaranteed
 * to always point at a valid member or to the end of the set, in the case
 * that the member being removed is the last one.
 *
 * A resilient iterator must skip over removed members:
 *
 * If the container is modified by removing members, the iterator will guarantee
 * not to <em>land on</em> (e.g. return) those members as iteration proceeds.
 * This is true of set-type sets and list-type sets.
 *
 * A resilient iterator on set-type sets <em>may</em> fail to return added members:
 *
 * If the container is a set-type (<em>duplicate preventing</em>) container and
 * it is modified by adding members, the iterator <em>may</em> skip over (e.g.
 * fail to return) members that have been added. In other words, there is no
 * guarantee in this circumstance that an iterator will return added members.
 *
 * A resilient iterator on list-type sets <em>must</em> return added members.
 * If it is a list-type (<em>order preserving</em>) container, then the iterator
 * <em>must</em> guarantee to return the added members.
 *
 * A non-resilient iterator may or may not behave like a resilient iterator in
 * some or all of the circumstances described above. There are no guarantees
 * about how a non-resilient iterator will behave. The behavior of a non-resilient
 * iterator in the presence of container modifications is left entirely up
 * to the implementation.
 *
 * If upon initializing an iterator, an application requests it be resilient and
 * the implementation is unable to support that, the iterator initialization
 * request shall fail and return error iBase_NOT_SUPPORTED.
 ******************************************************************************/
 
#ifdef __cplusplus
}
#endif
 
#endif /* #ifndef _ITAPS_iBase */