MOAB: Mesh Oriented datABase  (version 5.1.1)
iBase.h
Go to the documentation of this file.
00001 #ifndef _ITAPS_iBase
00002 #define _ITAPS_iBase
00003 
00004 /***************************************************************************//**
00005  * \ingroup VersionNumbers
00006  * \brief Compile time version number digits
00007  *
00008  * iBase maintains a major, minor and patch digit in its version number.
00009  * Technically speaking, there is not much practical value in patch digit
00010  * for an interface specification. A patch release is typically only used
00011  * for bug fix releases. Although it is rare, sometimes a bug fix
00012  * necessitates an API change. So, we define a patch digit for iBase.
00013  *
00014  * Although each interface in ITAPS has been designed to support its own
00015  * unique version numbers, apart from other ITAPS interfaces, as currently
00016  * used, we require all ITAPS interfaces to use the same ITAPS-wide version
00017  * number derived from the version number defined by these three digits.
00018  ******************************************************************************/
00019 #define IBASE_VERSION_MAJOR 1
00020 #define IBASE_VERSION_MINOR 4
00021 #define IBASE_VERSION_PATCH 1
00022 
00023 /***************************************************************************//**
00024  * \ingroup VersionNumbers
00025  * \brief Version Comparison
00026  *
00027  * Evaluates to true at CPP time if the version of iBase currently being
00028  * compiled is greater than or equal to the version specified.
00029  ******************************************************************************/
00030 #define IBASE_VERSION_GE(Maj,Min,Pat) \
00031     (((IBASE_VERSION_MAJOR==(Maj)) && (IBASE_VERSION_MINOR==(Min)) && (IBASE_VERSION_PATCH>=(Pat))) || \
00032      ((IBASE_VERSION_MAJOR==(Maj)) && (IBASE_VERSION_MINOR>(Min))) || \
00033       (IBASE_VERSION_MAJOR>(Maj)))
00034 
00035 /***************************************************************************//**
00036  * \ingroup VersionNumbers
00037  * \brief Compose compile-time string represention of the version number
00038  ******************************************************************************/
00039 #define IBASE_VERSION_STRING___(I,X,Y,Z) #I "_Version_" #X "." #Y "." #Z
00040 #define IBASE_VERSION_STRING__(I,X,Y,Z) IBASE_VERSION_STRING___(I,X,Y,Z)
00041 #define IBASE_VERSION_STRING_(I) IBASE_VERSION_STRING__(I,IBASE_VERSION_MAJOR,IBASE_VERSION_MINOR,IBASE_VERSION_PATCH)
00042 #define IBASE_VERSION_STRING IBASE_VERSION_STRING_(iBase)
00043 
00044 /***************************************************************************//**
00045  * \ingroup VersionNumbers
00046  * \brief Compose compile-time symbol name derived from the version number.
00047  ******************************************************************************/
00048 #define IBASE_VERSION_TAG__(I,X,Y,Z) I##_Version_##X##_##Y##_##Z
00049 #define IBASE_VERSION_TAG_(I,X,Y,Z) IBASE_VERSION_TAG__(I,X,Y,Z)
00050 #define IBASE_VERSION_TAG(I) IBASE_VERSION_TAG_(I,IBASE_VERSION_MAJOR,IBASE_VERSION_MINOR,IBASE_VERSION_PATCH)
00051 
00052 /***************************************************************************//**
00053  * \ingroup VersionNumbers
00054  * \brief ITAPS-wide (across all ITAPS APIs) version handling
00055  ******************************************************************************/
00056 #define ITAPS_VERSION_MAJOR IBASE_VERSION_MAJOR
00057 #define ITAPS_VERSION_MINOR IBASE_VERSION_MINOR
00058 #define ITAPS_VERSION_PATCH IBASE_VERSION_PATCH
00059 #define ITAPS_VERSION_GE(Maj,Min,Pat) IBASE_VERSION_GE(Maj,Min,Pat)
00060 #define ITAPS_VERSION_STRING_(I) IBASE_VERSION_STRING_(I)
00061 #define ITAPS_VERSION_STRING ITAPS_VERSION_STRING_(ITAPS)
00062 #define ITAPS_VERSION_TAG_(I) IBASE_VERSION_TAG(I)
00063 #define ITAPS_VERSION_TAG ITAPS_VERSION_TAG_(I)
00064 
00065 /***************************************************************************//**
00066  * \defgroup EnumIterators Enum-Iterators
00067  * \ingroup iBase
00068  * \brief Convenience macros for iterating over all possible values in an enum
00069  *
00070  * These convenience macros are provided to facilitate iterating over all
00071  * possible values in an enumerated type. To use these macros, for example...
00072  * \code 
00073  * for (iBase_EntityType i  = IBASE_MINENUM(iBase_EntityType);
00074  *                       i <= IBASE_MAXENUM(iBase_EntityType);
00075  *                            IBASE_INCENUM(i,iBase_EntityType))
00076  * {
00077  * }
00078  * \endcode
00079  * Be aware that some enumerated types include a <em>wild card</em> often used
00080  * in queries to represent all possible values and you may or may not want to
00081  * include such a value in your iteration.
00082  ******************************************************************************/
00083 
00084 /***************************************************************************//**
00085  * \ingroup EnumIterators
00086  * @{
00087  ******************************************************************************/
00088 #define IBASE_MINENUM(enumName) enumName ## _MIN
00089 #define IBASE_MAXENUM(enumName) enumName ## _MAX
00090 #define IBASE_NUMENUM(enumName) ((int)IBASE_MAXENUM(enumName) - (int)IBASE_MINENUM(enumName) + 1)
00091 #define IBASE_INCENUM(enumName,I) (I = (enum enumName)((int)I+1))
00092 /** @} */
00093 
00094 #ifdef __cplusplus
00095 extern "C" {
00096 #endif
00097 
00098 typedef void* iBase_Instance;
00099 typedef struct iBase_EntityHandle_Private* iBase_EntityHandle;
00100 typedef struct iBase_EntitySetHandle_Private* iBase_EntitySetHandle;
00101 typedef struct iBase_TagHandle_Private* iBase_TagHandle;
00102 typedef struct iBase_EntityIterator_Private* iBase_EntityIterator;
00103 typedef struct iBase_EntityArrIterator_Private* iBase_EntityArrIterator;
00104 
00105 enum iBase_EntityType {
00106     iBase_EntityType_MIN = 0,
00107         /**< facilitates iteration over all values */
00108     iBase_VERTEX = iBase_EntityType_MIN,
00109         /**< A topological dimension 0 entity */
00110     iBase_EDGE,
00111         /**< A topological dimension 1 entity */
00112     iBase_FACE,
00113         /**< A topological dimension 2 entity */
00114     iBase_REGION,
00115         /**< A topological dimension 3 entity */
00116     iBase_ALL_TYPES,
00117         /**< used only in queries to request information about all types */
00118     iBase_EntityType_MAX = iBase_ALL_TYPES
00119         /**< facilitates iteration over all values */
00120 };
00121 
00122 enum iBase_AdjacencyCost {
00123     iBase_AdjacencyCost_MIN = 0,
00124         /**< facilitates iteration over all values */
00125     iBase_UNAVAILABLE = iBase_AdjacencyCost_MIN,
00126         /**< Adjacency information not supported */
00127     iBase_ALL_ORDER_1,
00128         /**< No more than local mesh traversal required (i!=j) */
00129     iBase_ALL_ORDER_LOGN,
00130         /**< Global tree search (i!=j) */
00131     iBase_ALL_ORDER_N,
00132         /**< Global exhaustive search (i!=j) */
00133     iBase_SOME_ORDER_1,
00134         /**< Only some adjacency info, local (i!=j) */
00135     iBase_SOME_ORDER_LOGN,
00136         /**< Only some adjacency info, tree (i!=j) */
00137     iBase_SOME_ORDER_N,
00138         /**< Only some adjacency info, exhaustive (i!=j) */
00139     iBase_AVAILABLE,
00140         /**< ALL (intermediate) entities available. (i==j) */
00141     iBase_AdjacencyCost_MAX = iBase_AVAILABLE
00142         /**< facilitates iteration over all values */
00143 };
00144 
00145 enum iBase_CreationStatus {
00146     iBase_CreationStatus_MIN = 0,
00147         /**< facilitates iteration over all values */
00148     iBase_NEW = iBase_CreationStatus_MIN,
00149         /**< The entity was newly created */
00150     iBase_ALREADY_EXISTED,
00151         /**< The entity already existed and the handle for that
00152              already existing handle was returned */
00153     iBase_CREATED_DUPLICATE,
00154         /**< The entity already existed but a new, duplicate entity was
00155              nevertheless created */
00156     iBase_CREATION_FAILED,
00157         /**< Creation of the entity did not succeed */
00158     iBase_CreationStatus_MAX = iBase_CREATION_FAILED
00159         /**< facilitates iteration over all values */
00160 };
00161 
00162 enum iBase_ErrorType {
00163     iBase_ErrorType_MIN = 0,
00164         /**< facilitates iteration over all values */
00165     iBase_SUCCESS = iBase_ErrorType_MIN,
00166     iBase_MESH_ALREADY_LOADED,
00167     iBase_FILE_NOT_FOUND,
00168     iBase_FILE_WRITE_ERROR,
00169     iBase_NIL_ARRAY,
00170     iBase_BAD_ARRAY_SIZE,
00171     iBase_BAD_ARRAY_DIMENSION,
00172     iBase_INVALID_ENTITY_HANDLE,
00173     iBase_INVALID_ENTITY_COUNT,
00174     iBase_INVALID_ENTITY_TYPE,
00175     iBase_INVALID_ENTITY_TOPOLOGY,
00176     iBase_BAD_TYPE_AND_TOPO,
00177     iBase_ENTITY_CREATION_ERROR,
00178     iBase_INVALID_TAG_HANDLE,
00179     iBase_TAG_NOT_FOUND,
00180     iBase_TAG_ALREADY_EXISTS,
00181     iBase_TAG_IN_USE,
00182     iBase_INVALID_ENTITYSET_HANDLE,
00183     iBase_INVALID_ITERATOR_HANDLE,
00184     iBase_INVALID_ARGUMENT,
00185     iBase_MEMORY_ALLOCATION_FAILED,
00186     iBase_NOT_SUPPORTED,
00187     iBase_FAILURE,
00188     iBase_ErrorType_MAX = iBase_FAILURE
00189         /**< facilitates iteration over all values */
00190   };
00191 
00192 /***************************************************************************//**
00193  * \details
00194  * Many of the functions in iMesh can return arrays of tuples; that is, arrays
00195  * of multi-valued type. For example, the function iMesh_getVtxArrCoords,
00196  * returns an array of xyz coordinate 3-tuples (or, perhaps for geometrically
00197  * 2D meshes, xy 2-tuples). In these situations, there are multiple ways the
00198  * data can be organized in memory. For example, it could be stored xyz,xyz,xyz
00199  * or xxx...,yyy...,zzz.... These two different storage orders are referred
00200  * to as INTERLEAVED and BLOCKED, respectively. For some functions in iMesh,
00201  * the storage order is explicitly specified as an argument to the function.
00202  * For other functions, the storage order is not explicitly specified. And,
00203  * in these cases, it shall always be implicitly assumed to be INTERLEAVED.
00204  * This fact will be mentioned in the documentation for each specific function
00205  * where it applies. For example, in case of iMesh_getEntArrAdj, the returned
00206  * array of adjacent entities is multi-valued in that it stores for each
00207  * entity queried, all its adjacent entities. Such an array will be stored
00208  * INTERLEAVED with all adjacent entities for the first entity in the query
00209  * followed by all adjacent entities for the second entity in the query and
00210  * so forth.
00211  ******************************************************************************/
00212 enum iBase_StorageOrder {
00213     iBase_StorageOrder_MIN = 0,
00214         /**< facilitates iteration over all values */
00215     iBase_BLOCKED = iBase_StorageOrder_MIN,
00216         /**< xxx...yyy...zzz... */
00217     iBase_INTERLEAVED,
00218         /**< xyzxyzxyz... */
00219     iBase_StorageOrder_MAX = iBase_INTERLEAVED
00220         /**< facilitates iteration over all values */
00221 };
00222 
00223 enum iBase_TagValueType {
00224     iBase_TagValueType_MIN = 0,
00225         /**< facilitates iteration over all values */
00226     iBase_BYTES = iBase_TagValueType_MIN,
00227         /**< An opaque sequence of bytes, size always measured in bytes */
00228     iBase_INTEGER,
00229         /**< A value of type \c int */
00230     iBase_DOUBLE,
00231         /**< A value of type \c double */
00232     iBase_ENTITY_HANDLE,
00233         /**< A value of type \c iBase_EntityHandle */
00234     iBase_ENTITY_SET_HANDLE,
00235         /**< A value of type \c iBase_EntitySetHandle */
00236     iBase_TagValueType_MAX = iBase_ENTITY_SET_HANDLE
00237         /**< facilitates iteration over all values */
00238 };
00239 
00240 /***************************************************************************//**
00241  * \page ibase iBase: ITAPS Base Interface
00242  ******************************************************************************/
00243 
00244 /***************************************************************************//**
00245  * \defgroup iBase iBase
00246  ******************************************************************************/
00247 
00248 /***************************************************************************//**
00249  * \defgroup VersionNumbers Version Numbers
00250  * \ingroup iBase
00251  ******************************************************************************/
00252 
00253 /***************************************************************************//**
00254  * \defgroup ErrorHandling Error Handling
00255  * \ingroup iBase
00256  ******************************************************************************/
00257 
00258 /***************************************************************************//**
00259  * \defgroup Datatypes Datatypes
00260  * \ingroup iBase
00261  ******************************************************************************/
00262 
00263 /***************************************************************************//**
00264  * \page The ITAPS Interfaces
00265  *
00266  * \subpage ibase
00267  *
00268  * \subpage imesh
00269  *
00270  * \subpage imeshp
00271  * 
00272  * \subpage error
00273  *
00274  * \subpage trio
00275  *
00276  * \subpage strlen
00277  *
00278  * \subpage options
00279  *
00280  * \subpage numhops
00281  *
00282  * \subpage resilient
00283  *
00284  * \page error Error Handling
00285  *
00286  * With few exceptions, every iMesh function includes an output argument,
00287  * 'int *err', which returns an error code indicating if the function call
00288  * may have failed. If the value returned for the 'err' argument is NOT
00289  * iBase_SUCCESS, the caller should NOT attempt to interpret (read the
00290  * values in) any of the other return arguments of the call. While some
00291  * implementations may actually return valid/useful results in other
00292  * return arguments of a call that has failed, there is no guarentee that
00293  * ALL implementations will do similarly and so depending on such behavior
00294  * is neither portable nor safe. This is true even if the returned values
00295  * are different from the values of the arguments before the call was
00296  * made.
00297  *
00298  * \page trio Array pointer, allocated and occupied sizes argument trio
00299  *
00300  * Many of the functions in iMesh have arguments corresponding to lists of 
00301  * objects.  In-type arguments for lists consist of a pointer to an array and
00302  * a list size.  Lists returned from functions are passed in three arguments,
00303  * a pointer to the array representing the list, and pointers to the
00304  * allocated and occupied lengths of the array.  These three arguments are 
00305  * inout-type arguments, because they can be allocated by the application and
00306  * passed into the interface to hold the results of the function.  Lists
00307  * which are pre-allocated must be large enough to hold the results of the
00308  * function; if this is not the case, an error is generated.  Otherwise, the
00309  * occupied size is changed to the size output from the function.  If a list
00310  * argument is unallocated (the list pointer points to a NULL value) or if
00311  * the incoming value of the allocated size is zero, the list storage will be
00312  * allocated by the implementation.
00313  *
00314  * IN ALL CASES, MEMORY ALLOCATED BY ITAPS INTERFACE IMPLEMENTATIONS IS DONE
00315  * USING THE C MALLOC FUNCTION, AND MUST BE DE-ALLOCATED USING THE C FREE
00316  * FUNCTION.
00317  *
00318  * \page strlen String Length Arguments
00319  *
00320  * Many of the functions in iMesh involve passing a string and also the length
00321  * of that string. How is the null character is handled?
00322  * For users of the iMesh interface calling iMesh functions, it is optional
00323  * as to whether or not to include the null character in computing the length
00324  * of the string. So, for example, calling iMesh from a C program, users could
00325  * pass strlen(my_string) or strlen(my_string)+1 as the length of the string.
00326  *
00327  * <em>Note to implementors</em>: However, it should be noted that the situation
00328  * is different for implementers of the iMesh interface. In implementing an
00329  * iMesh interface function, there can be no assumption that the string is
00330  * indeed null terminated. The length argument the caller passes in may or may
00331  * NOT include the null character and implementations must be coded to
00332  * accommodate this. This requirement is primarily due to differences in how
00333  * Fortran and C/C++ handle passing of strings as function arguments.
00334  * Furthermore, because of the way Fortran clients pass strings (Fortran always
00335  * passes the length of the string as declared in the source code), there
00336  * may be trailing spaces in the string that need to be truncated.
00337  *
00338  * \page numhops Indirection in Set-Inclusion and Parent-Child structures
00339  *
00340  * Various functions to query entities, entity sets and parent or child sets 
00341  * as well as the numbers of these involve a num_hops argument. If the set
00342  * upon which the query is originated is the root set, the num_hops argument
00343  * is irrelevant and is ignored by the implementation. Otherwise, the num_hops
00344  * argument represents the maximum number of levels of indirection employed in
00345  * satisfying the query not including the originating set. For example, using
00346  * value for num_hops of 0 (zero) in iMesh_getEntSets will return all the 
00347  * entity sets that are immediately contained in a given set. Likewise, a
00348  * value for num_hops of 1 (one) will return all entity sets that are 
00349  * immediately contained in the given set plus all entity sets that
00350  * are contained in those immediately contained sets (e.g. one level of
00351  * indirection). Using a value of -1 for num_hops will return results for
00352  * all possible levels of indirection. In other words, using a value of
00353  * -1 for num_hops is equivalent to setting the maximum number of levels
00354  * of indirection to infinity.
00355  *
00356  * \page options Option Strings
00357  *
00358  * A few of the functions in iMesh support arbitrary options passed as a
00359  * character string, called an 'Option String'. The format of and handling
00360  * of an Option String is as follows...
00361  *
00362  * 1. Option Strings are INsensitive to case.
00363  *
00364  * 2. Each option in an Option String is pre-pended with the implementation
00365  * name followed by a special character called the separator character.
00366  *
00367  * 3. The separator is a colon, ':'.
00368  *
00369  * 4. Multiple options existing in a single Option String are separated by a
00370  * special character called the delimiter character.
00371  *
00372  * 5. The delimiter character is a space, ' '.
00373  *
00374  * 6. The effect of multiple options in a single Option String is 
00375  * INsensitive to order of occurrence in the string.
00376  *
00377  * 7. By default, implementations silently ignore any options that
00378  * do not match on the implementation name part (everything before
00379  * the separator character). This way, a caller may included options
00380  * in a single string intended for multiple different implementations.
00381  *
00382  * 8. Implementations may (or may not) warn or error for option strings
00383  * that match on implementation name part but are found to be in error
00384  * for other reasons the implementation decides.
00385  *
00386  * 9. Whenever either the separator character, ':', or delimiter character,
00387  * ' ', need to appear in an option, they must be escaped with the
00388  * backslash character, '\'.
00389  *
00390  * For example, consider the Options String
00391  *
00392  *     "grummp:silant FMDB:TwoPhaseIO moab:mpiio_hints\ foo\:bar"
00393  *
00394  * In the above example, the space serves as the delimiter character
00395  * between multiple options in the string. The colon serves as the
00396  * implementation-name/option separator character. Because options are
00397  * required to be insensitive to case, the caller is free to use case as a
00398  * word separator as in 'TwoPhaseIO' and even in the implementation name,
00399  * as in 'FMDB:', although 'fmdb:twophaseio' and 'fmdb:TWOPHASEIO' would
00400  * all have the same effect. In the moab option, both the separator
00401  * character and delimiter character appear in the option and so are
00402  * pre-pended (e.g. escaped) with the backslash character.
00403  
00404  * GRUMMP will silently ignore the FMDB: and moab: options because they do
00405  * NOT match on the implementation name part. However, GRUMMP may
00406  * optionally error out, or warn or silently ignore 'grummp:silant' (it was
00407  * supposed to be spelled 'silent') as an invalid option.
00408  *
00409  * Note that iMesh itself currently does not define any options. In order
00410  * to discover options a given implementation defines, users are directed
00411  * to the developers of the respective implementations.
00412  *
00413  * \page resilient Resilient and Non-Resilient Iterators
00414  *
00415  * A resilient iterator is one that can deal with modifications to the container
00416  * it is iterating over.
00417  *
00418  * A common concern about an iterator is how it behaves when the container
00419  * over which it is iterating is modified. For example, in STL, iterators
00420  * for std::set<> and std::map<> and std::list<> containers are guaranteed
00421  * to <em>work</em> in the presence of modifications to the associated
00422  * containers with one exception; they don't handle the case when the
00423  * container member the iterator is currently pointed at is deleted. However,
00424  * iterators for std::vector<> are not guaranteed to work under any kinds of
00425  * modification.
00426  *
00427  * In the ITAPS interfaces, a <em>resilient</em> iterator is one that makes
00428  * certain guarantees (described below) about how it behaves when the
00429  * container being iterated is modified. On the other hand, a
00430  * <em>non-resilient</em> is one that does not make such guarantees.
00431  *
00432  * In all cases, the <em>container</em> associated with an iterator in the
00433  * ITAPS interfaces is an entity set of some sort. This is the only container
00434  * type for which iterators are defined.
00435  *
00436  * Here, we characterize the behavior of iterators in the presence of
00437  * container modifications. There are a number of (subtle) aspects to
00438  * keep in mind.
00439  *
00440  * 1. There are set-type (<em>duplicate preventing</em>) sets and list-type
00441  * (<em>order preserving</em>) sets and iterators behave differently for each.
00442  *
00443  * 2. Sets can have <em>set</em> members and <em>entity</em> members. However,
00444  * iterators are currently defined to iterate over <em>only</em> the entity
00445  * members. That said, the question arises as to whether modifications that
00446  * involve only set members nonetheless <em>effect</em> iterator behavior.
00447  *
00448  * 3. There are array-type iterators that upon each step in the iteration
00449  * return a whole array of entity member handles and single entity iterators
00450  * that upon each step return just a single entity member handle.
00451  *
00452  * 4. The iterators support type/topology <em>filtering</em>. Iterators do not
00453  * (always) strictly iterate over <em>all</em> entities in a set; just
00454  * <em>all</em> entities matching the type/topology criteria. When
00455  * type/topology specifies either all types or all topologies, then indeed
00456  * the iterator will iterate over all entities.
00457  *
00458  * 5. There are add/remove operations that add/remove <em>entity members</em> or
00459  * <em>set members</em> to a set.
00460  *
00461  * 6. There are create/delete operations that create and delete
00462  * <em>entities</em> from the whole iMesh_Instance.
00463  *
00464  * 7. There are create/destroy operations that create and destroy
00465  * <em>sets</em> from the whole interface instance. 
00466  *
00467  * 8. There is the <em>root set</em> which is special and may have different
00468  * iterator behavior than all other sets. By definition, the root set is a set-type
00469  * (<em>duplicate prevent</em>) set.
00470  *
00471  * Modification means addition/removal and/or create/destroy and/or create/delete
00472  * <em>after</em> iterator initialization. When we talk about
00473  * <em>container modification</em> here, we are talking about any of the
00474  * following operations.
00475  *
00476  * A. addition and removal of entity members
00477  * \code
00478  * void iMesh_rmvEntFromSet(iMesh_Instance instance,
00479  * void iMesh_rmvEntArrFromSet(iMesh_Instance instance,
00480  * void iMesh_addEntToSet(iMesh_Instance instance,
00481  * void iMesh_addEntArrToSet(iMesh_Instance instance,
00482  * \endcode
00483  * B. addition and removal of set members
00484  * \code
00485  * void iMesh_rmvEntSet(iMesh_Instance instance,
00486  * void iMesh_addEntSet(iMesh_Instance instance,
00487  * \endcode
00488  * C. deletion of entities from whole iMesh_Instance
00489  * \code
00490  * void iMesh_deleteEntArr(iMesh_Instance instance,
00491  * void iMesh_deleteEnt(iMesh_Instance instance,
00492  * \endcode
00493  * D. creation of entities (effects root set)
00494  * \code
00495  * void iMesh_createEntSet(iMesh_Instance instance,
00496  * void iMesh_createVtxArr(iMesh_Instance instance,
00497  * void iMesh_createEntArr(iMesh_Instance instance,
00498  * void iMesh_createVtx(iMesh_Instance instance,
00499  * void iMesh_createEnt(iMesh_Instance instance,
00500  * \endcode
00501  * E. destruction of entity sets
00502  * \code
00503  * void iMesh_destroyEntSet(iMesh_Instance instance,
00504  * \endcode
00505 
00506  * By container modification, we mean that of the above operations occur on
00507  * the container between iterator initialization and reset.
00508  *
00509  * For purposes of this discussion, there is no distinction between any of
00510  * these <em>kinds of</em> modifications. What is true for any is true for
00511  * all. Below, the words <em>add</em> and <em>remove</em> are used to
00512  * represent any of the modifications that add members or remove members
00513  * regardless of the <em>kind of operation</em> above.
00514  *
00515  * Resilient iterators are not effected by modifications involving set members:
00516  *
00517  * Iterators are currently defined to iterate over *only* the entity members
00518  * of a container. In particular, if the container is modified by
00519  * adding/removing sets from the container, this will have no impact on
00520  * the iterator.  This is true for set-type sets and list-type sets.
00521  *
00522  * Resilient iterator's <em>current position</em> not effected by modification:
00523  *
00524  * If the container is modified, the iterator will continue to properly
00525  * <em>keep track of</em> the member it was currently pointing at. If a
00526  * modification occurs that removes the member it was currently pointing at,
00527  * the iterator will be advanced to the <em>next</em> (not already deleted)
00528  * member it would have proceeded to. In this way, the iterator is guaranteed
00529  * to always point at a valid member or to the end of the set, in the case
00530  * that the member being removed is the last one.
00531  *
00532  * A resilient iterator must skip over removed members:
00533  *
00534  * If the container is modified by removing members, the iterator will guarantee
00535  * not to <em>land on</em> (e.g. return) those members as iteration proceeds.
00536  * This is true of set-type sets and list-type sets.
00537  *
00538  * A resilient iterator on set-type sets <em>may</em> fail to return added members:
00539  *
00540  * If the container is a set-type (<em>duplicate preventing</em>) container and
00541  * it is modified by adding members, the iterator <em>may</em> skip over (e.g.
00542  * fail to return) members that have been added. In other words, there is no
00543  * guarantee in this circumstance that an iterator will return added members.
00544  *
00545  * A resilient iterator on list-type sets <em>must</em> return added members.
00546  * If it is a list-type (<em>order preserving</em>) container, then the iterator
00547  * <em>must</em> guarantee to return the added members.
00548  *
00549  * A non-resilient iterator may or may not behave like a resilient iterator in 
00550  * some or all of the circumstances described above. There are no guarantees
00551  * about how a non-resilient iterator will behave. The behavior of a non-resilient
00552  * iterator in the presence of container modifications is left entirely up
00553  * to the implementation.
00554  *
00555  * If upon initializing an iterator, an application requests it be resilient and
00556  * the implementation is unable to support that, the iterator initialization
00557  * request shall fail and return error iBase_NOT_SUPPORTED.
00558  ******************************************************************************/
00559 
00560 #ifdef __cplusplus
00561 }
00562 #endif
00563 
00564 #endif /* #ifndef _ITAPS_iBase */
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines