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