MOAB: Mesh Oriented datABase  (version 5.2.1)
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, Error* error_handler, const EntityHandle* entities,
00120                                 size_t num_entities, void* data ) const = 0;
00121 
00122     /**\brief Get tag value for passed entities
00123      *
00124      * Get tag values for specified entities.
00125      *
00126      *\Note Will fail for variable-length data.
00127      *\param seqman Pointer to mesh entity database
00128      *\param entities Entity handles for which to retrieve tag data
00129      *\param data Pointer to memory in which to store consecutive tag values,
00130      *            one for each passed entity.
00131      */
00132     virtual ErrorCode get_data( const SequenceManager* seqman, Error* error_handler, const Range& entities,
00133                                 void* data ) const = 0;
00134 
00135     /**\brief Get tag value for passed entities
00136      *
00137      * Get tag values for specified entities.
00138      *
00139      *\param seqman    Pointer to mesh entity database
00140      *\param entities  Entity handles for which to retrieve tag data
00141      *\param num_entities Length of \c entities array
00142      *\param data_ptrs Array of pointers to tag values, one pointer
00143      *                 for each passed entity.
00144      *\param data_lengths One value for each entity specifying the
00145      *                length of the tag value for the corresponding
00146      *                entity.
00147      */
00148     virtual ErrorCode get_data( const SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
00149                                 size_t num_entities, const void** data_ptrs, int* data_lengths ) const = 0;
00150 
00151     /**\brief Get tag value for passed entities
00152      *
00153      * Get tag values for specified entities.
00154      *
00155      *\param seqman    Pointer to mesh entity database
00156      *\param entities  Entity handles for which to retrieve tag data
00157      *\param data_ptrs Array of pointers to tag values, one pointer
00158      *                 for each passed entity.
00159      *\param data_lengths One value for each entity specifying the
00160      *                length of the tag value for the corresponding
00161      *                entity.
00162      */
00163     virtual ErrorCode get_data( const SequenceManager* seqman, Error* error_handler, const Range& entities,
00164                                 const void** data_ptrs, int* data_lengths ) const = 0;
00165 
00166     /**\brief Set tag value for passed entities
00167      *
00168      * Store tag data or update stored tag values
00169      *\Note Will fail for variable-length data.
00170      *\param seqman Pointer to mesh entity database
00171      *\param entities Entity handles for which to store tag data
00172      *\param num_entities Length of \c entities array
00173      *\param data Pointer to memory holding consecutive tag values,
00174      *            one for each passed entity.
00175      */
00176     virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
00177                                 size_t num_entities, const void* data ) = 0;
00178 
00179     /**\brief Set tag value for passed entities
00180      *
00181      * Store tag data or update stored tag values
00182      *\Note Will fail for variable-length data.
00183      *\param seqman Pointer to mesh entity database
00184      *\param entities Entity handles for which to store tag data
00185      *\param data Pointer to memory holding consecutive tag values,
00186      *            one for each passed entity.
00187      */
00188     virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const Range& entities,
00189                                 const void* data ) = 0;
00190 
00191     /**\brief Set tag value for passed entities
00192      *
00193      * Store tag data or update stored tag values
00194      *
00195      *\param seqman    Pointer to mesh entity database
00196      *\param entities  Entity handles for which to store tag data
00197      *\param num_entities Length of \c entities array
00198      *\param data_ptrs Array of pointers to tag values, one pointer
00199      *                 for each passed entity.
00200      *\param data_lengths One value for each entity specifying the
00201      *                length of the tag value for the corresponding
00202      *                entity.  Array is required for variable-length
00203      *                tags and is ignored for fixed-length tags.
00204      */
00205     virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
00206                                 size_t num_entities, void const* const* data_ptrs, const int* data_lengths ) = 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 data_ptrs Array of pointers to tag values, one pointer
00215      *                 for each passed entity.
00216      *\param data_lengths One value for each entity specifying the
00217      *                length of the tag value for the corresponding
00218      *                entity.  Array is required for variable-length
00219      *                tags and is ignored for fixed-length tags.
00220      */
00221     virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const Range& entities,
00222                                 void const* const* data_ptrs, const int* data_lengths ) = 0;
00223 
00224     /**\brief Set tag value for passed entities
00225      *
00226      * Store tag data or update stored tag values.
00227      *
00228      *\param seqman    Pointer to mesh entity database
00229      *\param entities  Entity handles for which to store tag data
00230      *\param num_entities Length of \c entities array
00231      *\param value_ptr Pointer to a single tag value which is to be
00232      *                 stored for each of the passed entities.
00233      *\param value_len Length of tag value in bytes.  Ignored for
00234      *                 fixed-length tags.  Required for variable-
00235      *                 length tags.
00236      */
00237     virtual ErrorCode clear_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
00238                                   size_t num_entities, const void* value_ptr, int value_len = 0 ) = 0;
00239 
00240     /**\brief Set tag value for passed entities
00241      *
00242      * Store tag data or update stored tag values.
00243      *
00244      *\param seqman    Pointer to mesh entity database
00245      *\param entities  Entity handles for which to store tag data
00246      *\param value_ptr Pointer to a single tag value which is to be
00247      *                 stored for each of the passed entities.
00248      *\param value_len Length of tag value in bytes.  Ignored for
00249      *                 fixed-length tags.  Required for variable-
00250      *                 length tags.
00251      */
00252     virtual ErrorCode clear_data( SequenceManager* seqman, Error* error_handler, const Range& entities,
00253                                   const void* value_ptr, int value_len = 0 ) = 0;
00254 
00255     /**\brief Remove/clear tag data for entities
00256      *
00257      * Remove tag values from entities.
00258      *
00259      *\param seqman    Pointer to mesh entity database
00260      *\param entities  Entity handles for which to store tag data
00261      *\param num_entities Length of \c entities array
00262      */
00263     virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
00264                                    size_t num_entities ) = 0;
00265 
00266     /**\brief Remove/clear tag data for entities
00267      *
00268      * Remove tag values from entities.
00269      *
00270      *\param seqman    Pointer to mesh entity database
00271      *\param entities  Entity handles for which to store tag data
00272      */
00273     virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const Range& entities ) = 0;
00274 
00275     /**\brief Access tag data via direct pointer into contiguous blocks
00276      *
00277      * Iteratively obtain direct access to contiguous blocks of tag
00278      * storage.  This function cannot be used with bit tags because
00279      * of the compressed bit storage.  This function cannot be used
00280      * with variable length tags because it does not provide a mechanism
00281      * to determine the length of the value for each entity.  This
00282      * function may be used with sparse tags, but if it is used, it
00283      * will return data for a single entity at a time.
00284      *
00285      *\param iter        As input, the first entity for which to return
00286      *                   data.  As output, one past the last entity for
00287      *                   which data was returned.
00288      *\param end         One past the last entity for which data is desired
00289      *\param data_ptr    Output: pointer to tag storage.
00290      *\param allocate    If true, space for this tag will be allocated, if not it wont
00291      *
00292      *\Note If this function is called for entities for which no tag value
00293      *      has been set, but for which a default value exists, it will
00294      *      force the allocation of explicit storage for each such entity
00295      *      even though MOAB would normally not explicitly store tag values
00296      *      for such entities.
00297      */
00298     virtual ErrorCode tag_iterate( SequenceManager* seqman, Error* error_handler, Range::iterator& iter,
00299                                    const Range::iterator& end, void*& data_ptr, bool allocate = true ) = 0;
00300 
00301     /**\brief Get all tagged entities
00302      *
00303      * Get the list of entities for which the a tag value has been set,
00304      * or a close approximation if the tag storage scheme cannot
00305      * accurately determine exactly which entities have explicit values.
00306      *
00307      *\param seqman   Pointer to entity storage database
00308      *\param output_entities Results *appended* to this range
00309      *\param type     Optional entity type.  If specified, search is
00310      *                limited to entities of specified type.
00311      *\param intersect Optional intersect list.  If specified,
00312      *                search is restricted to entities in this list.
00313      */
00314     virtual ErrorCode get_tagged_entities( const SequenceManager* seqman, Range& output_entities,
00315                                            EntityType type = MBMAXTYPE, const Range* intersect = 0 ) const = 0;
00316 
00317     /**\brief Count all tagged entities
00318      *
00319      * Count the entities for which the a tag value has been set,
00320      * or a close approximation if the tag storage scheme cannot
00321      * accurately determine exactly which entities have explicit values.
00322      *
00323      *\param seqman   Pointer to entity storage database
00324      *\param output_count This is *incremented* for each detected entity.
00325      *\param type     Optional entity type.  If specified, search is
00326      *                limited to entities of specified type.
00327      *\param intersect Optional intersect list.  If specified,
00328      *                search is restricted to entities in this list.
00329      */
00330     virtual ErrorCode num_tagged_entities( const SequenceManager* seqman, size_t& output_count,
00331                                            EntityType type = MBMAXTYPE, const Range* intersect = 0 ) const = 0;
00332 
00333     /**\brief Get all tagged entities with tag value
00334      *
00335      * Get the list of entities which have the specified tag value.
00336      *
00337      *\param seqman   Pointer to entity storage database
00338      *\param output_entities Results *appended* to this range
00339      *\param value    Pointer to tag value
00340      *\param value_bytes Size of tag value in bytes.
00341      *\param type     Optional entity type.  If specified, search is
00342      *                limited to entities of specified type.
00343      *\param intersect_entities Optional intersect list.  If specified,
00344      *                search is restricted to entities in this list.
00345      */
00346     virtual ErrorCode find_entities_with_value( const SequenceManager* seqman, Error* error_handler,
00347                                                 Range& output_entities, const void* value, int value_bytes = 0,
00348                                                 EntityType type                 = MBMAXTYPE,
00349                                                 const Range* intersect_entities = 0 ) const = 0;
00350 
00351     /**\brief Check if entity is tagged */
00352     virtual bool is_tagged( const SequenceManager* seqman, EntityHandle entity ) const = 0;
00353 
00354     /**\brief Get memory use for tag data.
00355      *
00356      */
00357     virtual ErrorCode get_memory_use( const SequenceManager* seqman, unsigned long& total,
00358                                       unsigned long& per_entity ) const = 0;
00359 
00360   protected:
00361     unsigned long get_memory_use() const
00362     {
00363         return get_default_value_size() + get_name().size();
00364     }
00365 
00366   private:
00367     TagInfo( const TagInfo& copy );
00368 
00369     TagInfo& operator=( const TagInfo& copy );
00370 
00371     //! stores the default data, if any
00372     void* mDefaultValue;
00373 
00374     //! store the mesh value, if any
00375     void* mMeshValue;
00376 
00377     //! Size of mDefaultValue and mMeshValue, in bytes
00378     //! NOTE: These sizes differ from mDataSize in two cases:
00379     //!    a) Variable-length tags
00380     //!    b) Bit tags (where mDataSize is bits, not bytes.)
00381     int mDefaultValueSize, mMeshValueSize;
00382 
00383     //! stores the size of the data for this tag
00384     int mDataSize;
00385 
00386     //! type of tag data
00387     DataType dataType;
00388 
00389     //! stores the tag name
00390     std::string mTagName;
00391 };
00392 
00393 }  // namespace moab
00394 
00395 #endif  // TAG_INFO_HPP
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines