MOAB: Mesh Oriented datABase  (version 5.3.0)
DenseTag.hpp
Go to the documentation of this file.
00001 /** \file   DenseTag.hpp
00002  *  \author Jason Kraftcheck
00003  *  \date   2010-12-14
00004  */
00005 
00006 #ifndef DENSE_TAG_HPP
00007 #define DENSE_TAG_HPP
00008 
00009 #include "TagInfo.hpp"
00010 
00011 namespace moab
00012 {
00013 
00014 class EntitySequence;
00015 
00016 /**\brief Dense storage of fixed-length tag data
00017  *
00018  * Implement normal dense tag.
00019  */
00020 class DenseTag : public TagInfo
00021 {
00022   private:
00023     int mySequenceArray;  //!< Array index in SequenceManager used to store tag data.
00024 
00025     unsigned char* meshValue;
00026 
00027     DenseTag( int array_index, const char* name, int size, DataType type, const void* default_value );
00028 
00029   public:
00030     static DenseTag* create_tag( SequenceManager* seqman, Error* error, const char* name, int bytes, DataType type,
00031                                  const void* default_value );
00032 
00033     virtual ~DenseTag();
00034 
00035     virtual TagType get_storage_type() const;
00036 
00037     /**\brief Remove/clear tag data for all entities
00038      *
00039      * Remove tag values from entities.
00040      *
00041      *\param delete_pending  If true, then release any global
00042      *          data associated with the tag in preparation for deleting
00043      *          the tag itself.
00044      *
00045      *\Note Invalidates tag if \c tag_delete_pending is true.  The only
00046      *        valid method that can be invoked that is is the destructor.
00047      *
00048      *\param seqman    Pointer to mesh entity database
00049      */
00050     virtual ErrorCode release_all_data( SequenceManager* seqman, Error* error_handler, bool delete_pending );
00051 
00052     /**\brief Get tag value for passed entities
00053      *
00054      * Get tag values for specified entities.
00055      *
00056      *\Note Will fail for variable-length data.
00057      *\param seqman Pointer to mesh entity database
00058      *\param entities Entity handles for which to retrieve tag data
00059      *\param num_entities Length of \c entities array
00060      *\param data Pointer to memory in which to store consecutive tag values,
00061      *            one for each passed entity.
00062      */
00063     virtual ErrorCode get_data( const SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
00064                                 size_t num_entities, void* data ) const;
00065 
00066     /**\brief Get tag value for passed entities
00067      *
00068      * Get tag values for specified entities.
00069      *
00070      *\Note Will fail for variable-length data.
00071      *\param seqman Pointer to mesh entity database
00072      *\param entities Entity handles for which to retrieve tag data
00073      *\param data Pointer to memory in which to store consecutive tag values,
00074      *            one for each passed entity.
00075      */
00076     virtual ErrorCode get_data( const SequenceManager* seqman, Error* error_handler, const Range& entities,
00077                                 void* data ) const;
00078 
00079     /**\brief Get tag value for passed entities
00080      *
00081      * Get tag values for specified entities.
00082      *
00083      *\param seqman    Pointer to mesh entity database
00084      *\param entities  Entity handles for which to retrieve tag data
00085      *\param num_entities Length of \c entities array
00086      *\param data_ptrs Array of pointers to tag values, one pointer
00087      *                 for each passed entity.
00088      *\param data_lengths One value for each entity specifying the
00089      *                length of the tag value for the corresponding
00090      *                entity.
00091      */
00092     virtual ErrorCode get_data( const SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
00093                                 size_t num_entities, const void** data_ptrs, int* data_lengths ) const;
00094 
00095     /**\brief Get tag value for passed entities
00096      *
00097      * Get tag values for specified entities.
00098      *
00099      *\param seqman    Pointer to mesh entity database
00100      *\param entities  Entity handles for which to retrieve tag data
00101      *\param data_ptrs Array of pointers to tag values, one pointer
00102      *                 for each passed entity.
00103      *\param data_lengths One value for each entity specifying the
00104      *                length of the tag value for the corresponding
00105      *                entity.
00106      */
00107     virtual ErrorCode get_data( const SequenceManager* seqman, Error* error_handler, const Range& entities,
00108                                 const void** data_ptrs, int* data_lengths ) const;
00109 
00110     /**\brief Set tag value for passed entities
00111      *
00112      * Store tag data or update stored tag values
00113      *\Note Will fail for variable-length data.
00114      *\param seqman Pointer to mesh entity database
00115      *\param entities Entity handles for which to store tag data
00116      *\param num_entities Length of \c entities array
00117      *\param data Pointer to memory holding consecutive tag values,
00118      *            one for each passed entity.
00119      */
00120     virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
00121                                 size_t num_entities, const void* data );
00122 
00123     /**\brief Set tag value for passed entities
00124      *
00125      * Store tag data or update stored tag values
00126      *\Note Will fail for variable-length data.
00127      *\param seqman Pointer to mesh entity database
00128      *\param entities Entity handles for which to store tag data
00129      *\param data Pointer to memory holding consecutive tag values,
00130      *            one for each passed entity.
00131      */
00132     virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const Range& entities,
00133                                 const void* data );
00134 
00135     /**\brief Set tag value for passed entities
00136      *
00137      * Store tag data or update stored tag values
00138      *
00139      *\param seqman    Pointer to mesh entity database
00140      *\param entities  Entity handles for which to store 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.  Array is required for variable-length
00147      *                tags and is ignored for fixed-length tags.
00148      */
00149     virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
00150                                 size_t num_entities, void const* const* data_ptrs, const int* data_lengths );
00151 
00152     /**\brief Set tag value for passed entities
00153      *
00154      * Store tag data or update stored tag values
00155      *
00156      *\param seqman    Pointer to mesh entity database
00157      *\param entities  Entity handles for which to store tag data
00158      *\param data_ptrs Array of pointers to tag values, one pointer
00159      *                 for each passed entity.
00160      *\param data_lengths One value for each entity specifying the
00161      *                length of the tag value for the corresponding
00162      *                entity.  Array is required for variable-length
00163      *                tags and is ignored for fixed-length tags.
00164      */
00165     virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const Range& entities,
00166                                 void const* const* data_ptrs, const int* data_lengths );
00167 
00168     /**\brief Set tag value for passed entities
00169      *
00170      * Store tag data or update stored tag values.
00171      *
00172      *\param seqman    Pointer to mesh entity database
00173      *\param entities  Entity handles for which to store tag data
00174      *\param num_entities Length of \c entities array
00175      *\param value_ptr Pointer to a single tag value which is to be
00176      *                 stored for each of the passed entities.
00177      *\param value_len Length of tag value in bytes.  Ignored for
00178      *                 fixed-length tags.  Required for variable-
00179      *                 length tags.
00180      */
00181     virtual ErrorCode clear_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
00182                                   size_t num_entities, const void* value_ptr, int value_len = 0 );
00183 
00184     /**\brief Set tag value for passed entities
00185      *
00186      * Store tag data or update stored tag values.
00187      *
00188      *\param seqman    Pointer to mesh entity database
00189      *\param entities  Entity handles for which to store tag data
00190      *\param value_ptr Pointer to a single tag value which is to be
00191      *                 stored for each of the passed entities.
00192      *\param value_len Length of tag value in bytes.  Ignored for
00193      *                 fixed-length tags.  Required for variable-
00194      *                 length tags.
00195      */
00196     virtual ErrorCode clear_data( SequenceManager* seqman, Error* error_handler, const Range& entities,
00197                                   const void* value_ptr, int value_len = 0 );
00198 
00199     /**\brief Remove/clear tag data for entities
00200      *
00201      * Remove tag values from entities.
00202      *
00203      *\param seqman    Pointer to mesh entity database
00204      *\param entities  Entity handles for which to store tag data
00205      *\param num_entities Length of \c entities array
00206      */
00207     virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
00208                                    size_t num_entities );
00209 
00210     /**\brief Remove/clear tag data for entities
00211      *
00212      * Remove tag values from entities.
00213      *
00214      *\param seqman    Pointer to mesh entity database
00215      *\param entities  Entity handles for which to store tag data
00216      */
00217     virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const Range& entities );
00218 
00219     /**\brief Access tag data via direct pointer into contiguous blocks
00220      *
00221      * Iteratively obtain direct access to contiguous blocks of tag
00222      * storage.  This function cannot be used with bit tags because
00223      * of the compressed bit storage.  This function cannot be used
00224      * with variable length tags because it does not provide a mechanism
00225      * to determine the length of the value for each entity.  This
00226      * function may be used with sparse tags, but if it is used, it
00227      * will return data for a single entity at a time.
00228      *
00229      *\param iter        As input, the first entity for which to return
00230      *                   data.  As output, one past the last entity for
00231      *                   which data was returned.
00232      *\param end         One past the last entity for which data is desired
00233      *\param data_ptr    Output: pointer to tag storage.
00234      *
00235      *\Note If this function is called for entities for which no tag value
00236      *      has been set, but for which a default value exists, it will
00237      *      force the allocation of explicit storage for each such entity
00238      *      even though MOAB would normally not explicitly store tag values
00239      *      for such entities.
00240      */
00241     virtual ErrorCode tag_iterate( SequenceManager* seqman, Error* error_handler, Range::iterator& iter,
00242                                    const Range::iterator& end, void*& data_ptr, bool allocate = true );
00243 
00244     /**\brief Get all tagged entities
00245      *
00246      * Get the list of entities for which the a tag value has been set,
00247      * or a close approximation if the tag storage scheme cannot
00248      * accurately determine exactly which entities have explicit values.
00249      *
00250      *\param seqman   Pointer to entity storage database
00251      *\param output_entities Results *appended* to this range
00252      *\param type     Optional entity type.  If specified, search is
00253      *                limited to entities of specified type.
00254      *\param intersect Optional intersect list.  If specified,
00255      *                search is restricted to entities in this list.
00256      */
00257     virtual ErrorCode get_tagged_entities( const SequenceManager* seqman, Range& output_entities,
00258                                            EntityType type = MBMAXTYPE, const Range* intersect = 0 ) const;
00259 
00260     /**\brief Count all tagged entities
00261      *
00262      * Count the entities for which the a tag value has been set,
00263      * or a close approximation if the tag storage scheme cannot
00264      * accurately determine exactly which entities have explicit values.
00265      *
00266      *\param seqman   Pointer to entity storage database
00267      *\param output_count This is *incremented* for each detected entity.
00268      *\param type     Optional entity type.  If specified, search is
00269      *                limited to entities of specified type.
00270      *\param intersect Optional intersect list.  If specified,
00271      *                search is restricted to entities in this list.
00272      */
00273     virtual ErrorCode num_tagged_entities( const SequenceManager* seqman, size_t& output_count,
00274                                            EntityType type = MBMAXTYPE, const Range* intersect = 0 ) const;
00275 
00276     /**\brief Get all tagged entities with tag value
00277      *
00278      * Get the list of entities which have the specified tag value.
00279      *
00280      *\param seqman   Pointer to entity storage database
00281      *\param output_entities Results *appended* to this range
00282      *\param value    Pointer to tag value
00283      *\param value_bytes Size of tag value in bytes.
00284      *\param type     Optional entity type.  If specified, search is
00285      *                limited to entities of specified type.
00286      *\param intersect_entities Optional intersect list.  If specified,
00287      *                search is restricted to entities in this list.
00288      */
00289     virtual ErrorCode find_entities_with_value( const SequenceManager* seqman, Error* error_handler,
00290                                                 Range& output_entities, const void* value, int value_bytes = 0,
00291                                                 EntityType type                 = MBMAXTYPE,
00292                                                 const Range* intersect_entities = 0 ) const;
00293 
00294     /**\brief Check if entity is tagged */
00295     virtual bool is_tagged( const SequenceManager*, EntityHandle h ) const;
00296 
00297     /**\brief Get memory use for tag data.
00298      *
00299      */
00300     virtual ErrorCode get_memory_use( const SequenceManager* seqman, unsigned long& total,
00301                                       unsigned long& per_entity ) const;
00302 
00303     /**\brief Get read-only tag storage
00304      *
00305      *\param seqman  Sequence manager
00306      *\param error   Error object through which to report errors
00307      *\param h       First entity for which to return storage.
00308      *\param ptr     Pointer to dag storage.  This pointer will be set
00309      *               to null and \c MB_SUCCESS will be returned if the handle
00310      *               is valid but no tag storage has been allocated.
00311      *\param count   Number of consecutive entities for which tag storage
00312      *               is returned.  This value will be valid even if null
00313      *               is returned for \c ptr and indicates the number of
00314      *               consecutive entities for which no tag storage has been
00315      *               allocated.
00316      *\return        MB_SUCCESS if handle is valid (regardless of whether
00317      *               or not any tag storage is allocated).
00318      */
00319     ErrorCode get_array( const SequenceManager* seqman, Error* error, EntityHandle h, const unsigned char* const& ptr,
00320                          size_t& count ) const;
00321 
00322     /**\brief Get read-only tag storage for entire sequence
00323      *
00324      *\param seq     Sequence
00325      *\param ptr     Pointer to dag storage.  This pointer will be set
00326      *               to null and \c MB_SUCCESS will be returned if no tag storage has been
00327      *allocated. \return        MB_SUCCESS if sequence is valid (regardless of whether or not any
00328      *tag storage is allocated).
00329      */
00330     ErrorCode get_array( const EntitySequence* seq, const unsigned char* const& ptr ) const;
00331 
00332   private:
00333     DenseTag( const DenseTag& );
00334     DenseTag& operator=( const DenseTag& );
00335 
00336     /**\brief Get or allocated tag storage
00337      *
00338      *\param h       First entity for which to return storage.
00339      *\param ptr     Pointer to dag storage.  This pointer will be set
00340      *               to null and \c MB_SUCCESS will be returned if the handle
00341      *               is valid but no tag storage has been allocated.
00342      *\param count   Number of consecutive entities for which tag storage
00343      *               is returned.  This value will be valid even if null
00344      *               is returned for \c ptr and indicates the number of
00345      *               consecutive entities for which no tag storage has been
00346      *               allocated.
00347      *\param allocate If true storage will be allocated and initialized
00348      *               if it has not already been allocated.
00349      *\return        MB_SUCCESS if handle is valid (regardless of whether
00350      *               or not any tag storage is allocated).
00351      */
00352     inline ErrorCode get_array_private( SequenceManager* seqman, Error* error, EntityHandle h, unsigned char*& ptr,
00353                                         size_t& count, bool allocate );
00354 
00355     /**\brief Get tag storage
00356      *
00357      *\param h       First entity for which to return storage.
00358      *\param ptr     Pointer to dag storage.  This pointer will be set
00359      *               to null and \c MB_SUCCESS will be returned if the handle
00360      *               is valid but no tag storage has been allocated.
00361      *\param count   Number of consecutive entities for which tag storage
00362      *               is returned.  This value will be valid even if null
00363      *               is returned for \c ptr and indicates the number of
00364      *               consecutive entities for which no tag storage has been
00365      *               allocated.
00366      *\return        MB_SUCCESS if handle is valid (regardless of whether
00367      *               or not any tag storage is allocated).
00368      */
00369     inline ErrorCode get_array_private( const SequenceManager* seqman, Error* error, EntityHandle h,
00370                                         const unsigned char*& ptr, size_t& count ) const;
00371 
00372     /**\brief Get non-read-only tag storage for entire sequence
00373      *
00374      *\param seq     Sequence
00375      *\param ptr     Pointer to dag storage.  This pointer will be set
00376      *               to null and \c MB_SUCCESS will be returned if no tag storage has been
00377      *allocated. \return        MB_SUCCESS if sequence is valid (regardless of whether or not any
00378      *tag storage is allocated).
00379      */
00380     ErrorCode get_array_private( const EntitySequence* seq, const unsigned char*& ptr ) const;
00381 
00382     /**\brief Common implementation of public clear_data and remove_data */
00383     ErrorCode clear_data( bool allocate, SequenceManager* seqman, Error* error, const EntityHandle* entities,
00384                           size_t num_entities, const void* value_ptr );
00385 
00386     /**\brief Common implementation of public clear_data and remove_data */
00387     ErrorCode clear_data( bool allocate, SequenceManager* seqman, Error* error, const Range& entities,
00388                           const void* value_ptr );
00389 };
00390 
00391 }  // namespace moab
00392 
00393 #endif  // DENSE_TAG_HPP
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines