MOAB: Mesh Oriented datABase  (version 5.4.0)
TagInfo.hpp
Go to the documentation of this file.
00001 #ifndef TAG_INFO_HPP
00002 #define TAG_INFO_HPP
00003 
00004 #include "moab/Range.hpp"
00005 #include <string>
00006 
00007 namespace moab
00008 {
00009 
00010 class SequenceManager;
00011 class Range;
00012 class Error;
00013 
00014 // ! stores information about a tag
00015 class TagInfo
00016 {
00017   public:
00018     //! constructor
00019     TagInfo()
00020         : mDefaultValue( NULL ), mMeshValue( NULL ), mDefaultValueSize( 0 ), mMeshValueSize( 0 ), mDataSize( 0 ),
00021           dataType( MB_TYPE_OPAQUE )
00022     {
00023     }
00024 
00025     //! constructor that takes all parameters
00026     TagInfo( const char* name, int size, DataType type, const void* default_value, int default_value_size );
00027 
00028     virtual ~TagInfo();
00029 
00030     /**\brief Remove/clear tag data for all entities
00031      *
00032      * Remove tag values from entities.
00033      *
00034      *\param tag_delete_pending  If true, then release any global
00035      *          data associated with the tag in preparation for deleting
00036      *          the tag itself.
00037      *
00038      *\Note Invalidates tag if \c tag_delete_pending is true.  The only
00039      *        valid method that can be invoked that is is the destructor.
00040      *
00041      *\param seqman    Pointer to mesh entity database
00042      */
00043     virtual ErrorCode release_all_data( SequenceManager* seqman, Error* error_handler, bool tag_delete_pending ) = 0;
00044 
00045     //! set the name of the tag
00046     void set_name( const std::string& name )
00047     {
00048         mTagName = name;
00049     }
00050 
00051     //! get the name of the tag
00052     const std::string& get_name() const
00053     {
00054         return mTagName;
00055     }
00056 
00057     //! get length of default value
00058     int get_default_value_size() const
00059     {
00060         return mDefaultValueSize;
00061     }
00062 
00063     //! get the default data
00064     const void* get_default_value() const
00065     {
00066         return mDefaultValue;
00067     }
00068 
00069     //! compare the passed value to the default value.
00070     //! returns false if no default value.
00071     bool equals_default_value( const void* data, int size = -1 ) const;
00072 
00073     inline DataType get_data_type() const
00074     {
00075         return dataType;
00076     }
00077 
00078     //! get the size of the data in bytes
00079     int get_size() const
00080     {
00081         return mDataSize;
00082     }
00083 
00084     //! Check if variable-length tag
00085     bool variable_length() const
00086     {
00087         return get_size() == MB_VARIABLE_LENGTH;
00088     }
00089 
00090     static int size_from_data_type( DataType t );
00091 
00092     // Check that all lengths are valid multiples of the type size.
00093     // Returns true if all lengths are valid, false otherwise.
00094     bool check_valid_sizes( const int* sizes, int num_sizes ) const;
00095 
00096     /**\return MB_VARIABLE_LENGTH_DATA If variable_length() && lengths is NULL
00097      *         MB_INVALID_SIZE         If variable_length() && lengths is not
00098      *                                 NULL && any size is not a multiple of
00099      *                                 type size.
00100      *         MB_INVALID_SIZE         If !variable_length() && lengths is not
00101      *                                 NULL && any size is not the tag size.
00102      *         MB_SUCCESS              Otherwise.
00103      */
00104     ErrorCode validate_lengths( Error* error_handler, const int* lengths, size_t num_lengths ) const;
00105 
00106     virtual TagType get_storage_type() const = 0;
00107 
00108     /**\brief Get tag value for passed entities
00109      *
00110      * Get tag values for specified entities.
00111      *
00112      *\Note Will fail for variable-length data.
00113      *\param seqman Pointer to mesh entity database
00114      *\param entities Entity handles for which to retrieve tag data
00115      *\param num_entities Length of \c entities array
00116      *\param data Pointer to memory in which to store consecutive tag values,
00117      *            one for each passed entity.
00118      */
00119     virtual ErrorCode get_data( const SequenceManager* seqman,
00120                                 Error* error_handler,
00121                                 const EntityHandle* entities,
00122                                 size_t num_entities,
00123                                 void* data ) const = 0;
00124 
00125     /**\brief Get tag value for passed entities
00126      *
00127      * Get tag values for specified entities.
00128      *
00129      *\Note Will fail for variable-length data.
00130      *\param seqman Pointer to mesh entity database
00131      *\param entities Entity handles for which to retrieve tag data
00132      *\param data Pointer to memory in which to store consecutive tag values,
00133      *            one for each passed entity.
00134      */
00135     virtual ErrorCode get_data( const SequenceManager* seqman,
00136                                 Error* error_handler,
00137                                 const Range& entities,
00138                                 void* data ) const = 0;
00139 
00140     /**\brief Get tag value for passed entities
00141      *
00142      * Get tag values for specified entities.
00143      *
00144      *\param seqman    Pointer to mesh entity database
00145      *\param entities  Entity handles for which to retrieve tag data
00146      *\param num_entities Length of \c entities array
00147      *\param data_ptrs Array of pointers to tag values, one pointer
00148      *                 for each passed entity.
00149      *\param data_lengths One value for each entity specifying the
00150      *                length of the tag value for the corresponding
00151      *                entity.
00152      */
00153     virtual ErrorCode get_data( const SequenceManager* seqman,
00154                                 Error* error_handler,
00155                                 const EntityHandle* entities,
00156                                 size_t num_entities,
00157                                 const void** data_ptrs,
00158                                 int* data_lengths ) const = 0;
00159 
00160     /**\brief Get tag value for passed entities
00161      *
00162      * Get tag values for specified entities.
00163      *
00164      *\param seqman    Pointer to mesh entity database
00165      *\param entities  Entity handles for which to retrieve tag data
00166      *\param data_ptrs Array of pointers to tag values, one pointer
00167      *                 for each passed entity.
00168      *\param data_lengths One value for each entity specifying the
00169      *                length of the tag value for the corresponding
00170      *                entity.
00171      */
00172     virtual ErrorCode get_data( const SequenceManager* seqman,
00173                                 Error* error_handler,
00174                                 const Range& entities,
00175                                 const void** data_ptrs,
00176                                 int* data_lengths ) const = 0;
00177 
00178     /**\brief Set tag value for passed entities
00179      *
00180      * Store tag data or update stored tag values
00181      *\Note Will fail for variable-length data.
00182      *\param seqman Pointer to mesh entity database
00183      *\param entities Entity handles for which to store tag data
00184      *\param num_entities Length of \c entities array
00185      *\param data Pointer to memory holding consecutive tag values,
00186      *            one for each passed entity.
00187      */
00188     virtual ErrorCode set_data( SequenceManager* seqman,
00189                                 Error* error_handler,
00190                                 const EntityHandle* entities,
00191                                 size_t num_entities,
00192                                 const void* data ) = 0;
00193 
00194     /**\brief Set tag value for passed entities
00195      *
00196      * Store tag data or update stored tag values
00197      *\Note Will fail for variable-length data.
00198      *\param seqman Pointer to mesh entity database
00199      *\param entities Entity handles for which to store tag data
00200      *\param data Pointer to memory holding consecutive tag values,
00201      *            one for each passed entity.
00202      */
00203     virtual ErrorCode set_data( SequenceManager* seqman,
00204                                 Error* error_handler,
00205                                 const Range& entities,
00206                                 const void* data ) = 0;
00207 
00208     /**\brief Set tag value for passed entities
00209      *
00210      * Store tag data or update stored tag values
00211      *
00212      *\param seqman    Pointer to mesh entity database
00213      *\param entities  Entity handles for which to store tag data
00214      *\param num_entities Length of \c entities array
00215      *\param data_ptrs Array of pointers to tag values, one pointer
00216      *                 for each passed entity.
00217      *\param data_lengths One value for each entity specifying the
00218      *                length of the tag value for the corresponding
00219      *                entity.  Array is required for variable-length
00220      *                tags and is ignored for fixed-length tags.
00221      */
00222     virtual ErrorCode set_data( SequenceManager* seqman,
00223                                 Error* error_handler,
00224                                 const EntityHandle* entities,
00225                                 size_t num_entities,
00226                                 void const* const* data_ptrs,
00227                                 const int* data_lengths ) = 0;
00228 
00229     /**\brief Set tag value for passed entities
00230      *
00231      * Store tag data or update stored tag values
00232      *
00233      *\param seqman    Pointer to mesh entity database
00234      *\param entities  Entity handles for which to store tag data
00235      *\param data_ptrs Array of pointers to tag values, one pointer
00236      *                 for each passed entity.
00237      *\param data_lengths One value for each entity specifying the
00238      *                length of the tag value for the corresponding
00239      *                entity.  Array is required for variable-length
00240      *                tags and is ignored for fixed-length tags.
00241      */
00242     virtual ErrorCode set_data( SequenceManager* seqman,
00243                                 Error* error_handler,
00244                                 const Range& entities,
00245                                 void const* const* data_ptrs,
00246                                 const int* data_lengths ) = 0;
00247 
00248     /**\brief Set tag value for passed entities
00249      *
00250      * Store tag data or update stored tag values.
00251      *
00252      *\param seqman    Pointer to mesh entity database
00253      *\param entities  Entity handles for which to store tag data
00254      *\param num_entities Length of \c entities array
00255      *\param value_ptr Pointer to a single tag value which is to be
00256      *                 stored for each of the passed entities.
00257      *\param value_len Length of tag value in bytes.  Ignored for
00258      *                 fixed-length tags.  Required for variable-
00259      *                 length tags.
00260      */
00261     virtual ErrorCode clear_data( SequenceManager* seqman,
00262                                   Error* error_handler,
00263                                   const EntityHandle* entities,
00264                                   size_t num_entities,
00265                                   const void* value_ptr,
00266                                   int value_len = 0 ) = 0;
00267 
00268     /**\brief Set tag value for passed entities
00269      *
00270      * Store tag data or update stored tag values.
00271      *
00272      *\param seqman    Pointer to mesh entity database
00273      *\param entities  Entity handles for which to store tag data
00274      *\param value_ptr Pointer to a single tag value which is to be
00275      *                 stored for each of the passed entities.
00276      *\param value_len Length of tag value in bytes.  Ignored for
00277      *                 fixed-length tags.  Required for variable-
00278      *                 length tags.
00279      */
00280     virtual ErrorCode clear_data( SequenceManager* seqman,
00281                                   Error* error_handler,
00282                                   const Range& entities,
00283                                   const void* value_ptr,
00284                                   int value_len = 0 ) = 0;
00285 
00286     /**\brief Remove/clear tag data for entities
00287      *
00288      * Remove tag values from entities.
00289      *
00290      *\param seqman    Pointer to mesh entity database
00291      *\param entities  Entity handles for which to store tag data
00292      *\param num_entities Length of \c entities array
00293      */
00294     virtual ErrorCode remove_data( SequenceManager* seqman,
00295                                    Error* error_handler,
00296                                    const EntityHandle* entities,
00297                                    size_t num_entities ) = 0;
00298 
00299     /**\brief Remove/clear tag data for entities
00300      *
00301      * Remove tag values from entities.
00302      *
00303      *\param seqman    Pointer to mesh entity database
00304      *\param entities  Entity handles for which to store tag data
00305      */
00306     virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const Range& entities ) = 0;
00307 
00308     /**\brief Access tag data via direct pointer into contiguous blocks
00309      *
00310      * Iteratively obtain direct access to contiguous blocks of tag
00311      * storage.  This function cannot be used with bit tags because
00312      * of the compressed bit storage.  This function cannot be used
00313      * with variable length tags because it does not provide a mechanism
00314      * to determine the length of the value for each entity.  This
00315      * function may be used with sparse tags, but if it is used, it
00316      * will return data for a single entity at a time.
00317      *
00318      *\param iter        As input, the first entity for which to return
00319      *                   data.  As output, one past the last entity for
00320      *                   which data was returned.
00321      *\param end         One past the last entity for which data is desired
00322      *\param data_ptr    Output: pointer to tag storage.
00323      *\param allocate    If true, space for this tag will be allocated, if not it wont
00324      *
00325      *\Note If this function is called for entities for which no tag value
00326      *      has been set, but for which a default value exists, it will
00327      *      force the allocation of explicit storage for each such entity
00328      *      even though MOAB would normally not explicitly store tag values
00329      *      for such entities.
00330      */
00331     virtual ErrorCode tag_iterate( SequenceManager* seqman,
00332                                    Error* error_handler,
00333                                    Range::iterator& iter,
00334                                    const Range::iterator& end,
00335                                    void*& data_ptr,
00336                                    bool allocate = true ) = 0;
00337 
00338     /**\brief Get all tagged entities
00339      *
00340      * Get the list of entities for which the a tag value has been set,
00341      * or a close approximation if the tag storage scheme cannot
00342      * accurately determine exactly which entities have explicit values.
00343      *
00344      *\param seqman   Pointer to entity storage database
00345      *\param output_entities Results *appended* to this range
00346      *\param type     Optional entity type.  If specified, search is
00347      *                limited to entities of specified type.
00348      *\param intersect Optional intersect list.  If specified,
00349      *                search is restricted to entities in this list.
00350      */
00351     virtual ErrorCode get_tagged_entities( const SequenceManager* seqman,
00352                                            Range& output_entities,
00353                                            EntityType type        = MBMAXTYPE,
00354                                            const Range* intersect = 0 ) const = 0;
00355 
00356     /**\brief Count all tagged entities
00357      *
00358      * Count the entities for which the a tag value has been set,
00359      * or a close approximation if the tag storage scheme cannot
00360      * accurately determine exactly which entities have explicit values.
00361      *
00362      *\param seqman   Pointer to entity storage database
00363      *\param output_count This is *incremented* for each detected entity.
00364      *\param type     Optional entity type.  If specified, search is
00365      *                limited to entities of specified type.
00366      *\param intersect Optional intersect list.  If specified,
00367      *                search is restricted to entities in this list.
00368      */
00369     virtual ErrorCode num_tagged_entities( const SequenceManager* seqman,
00370                                            size_t& output_count,
00371                                            EntityType type        = MBMAXTYPE,
00372                                            const Range* intersect = 0 ) const = 0;
00373 
00374     /**\brief Get all tagged entities with tag value
00375      *
00376      * Get the list of entities which have the specified tag value.
00377      *
00378      *\param seqman   Pointer to entity storage database
00379      *\param output_entities Results *appended* to this range
00380      *\param value    Pointer to tag value
00381      *\param value_bytes Size of tag value in bytes.
00382      *\param type     Optional entity type.  If specified, search is
00383      *                limited to entities of specified type.
00384      *\param intersect_entities Optional intersect list.  If specified,
00385      *                search is restricted to entities in this list.
00386      */
00387     virtual ErrorCode find_entities_with_value( const SequenceManager* seqman,
00388                                                 Error* error_handler,
00389                                                 Range& output_entities,
00390                                                 const void* value,
00391                                                 int value_bytes                 = 0,
00392                                                 EntityType type                 = MBMAXTYPE,
00393                                                 const Range* intersect_entities = 0 ) const = 0;
00394 
00395     /**\brief Check if entity is tagged */
00396     virtual bool is_tagged( const SequenceManager* seqman, EntityHandle entity ) const = 0;
00397 
00398     /**\brief Get memory use for tag data.
00399      *
00400      */
00401     virtual ErrorCode get_memory_use( const SequenceManager* seqman,
00402                                       unsigned long& total,
00403                                       unsigned long& per_entity ) const = 0;
00404 
00405   protected:
00406     unsigned long get_memory_use() const
00407     {
00408         return get_default_value_size() + get_name().size();
00409     }
00410 
00411   private:
00412     TagInfo( const TagInfo& copy );
00413 
00414     TagInfo& operator=( const TagInfo& copy );
00415 
00416     //! stores the default data, if any
00417     void* mDefaultValue;
00418 
00419     //! store the mesh value, if any
00420     void* mMeshValue;
00421 
00422     //! Size of mDefaultValue and mMeshValue, in bytes
00423     //! NOTE: These sizes differ from mDataSize in two cases:
00424     //!    a) Variable-length tags
00425     //!    b) Bit tags (where mDataSize is bits, not bytes.)
00426     int mDefaultValueSize, mMeshValueSize;
00427 
00428     //! stores the size of the data for this tag
00429     int mDataSize;
00430 
00431     //! type of tag data
00432     DataType dataType;
00433 
00434     //! stores the tag name
00435     std::string mTagName;
00436 };
00437 
00438 }  // namespace moab
00439 
00440 #endif  // TAG_INFO_HPP
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines