DenseTag.hpp

Go to the documentation of this file.

/** \file   DenseTag.hpp
 *  \author Jason Kraftcheck
 *  \date   2010-12-14
 */

#ifndef DENSE_TAG_HPP
#define DENSE_TAG_HPP

#include "TagInfo.hpp"

namespace moab
{

class EntitySequence;

/**\brief Dense storage of fixed-length tag data
 *
 * Implement normal dense tag.
 */
class DenseTag : public TagInfo
{
  private:
    int mySequenceArray;  //!< Array index in SequenceManager used to store tag data.

    unsigned char* meshValue;

    DenseTag( int array_index, const char* name, int size, DataType type, const void* default_value );

  public:
    static DenseTag* create_tag( SequenceManager* seqman, Error* error, const char* name, int bytes, DataType type,
                                 const void* default_value );

    virtual ~DenseTag();

    virtual TagType get_storage_type() const;

    /**\brief Remove/clear tag data for all entities
     *
     * Remove tag values from entities.
     *
     *\param delete_pending  If true, then release any global
     *          data associated with the tag in preparation for deleting
     *          the tag itself.
     *
     *\Note Invalidates tag if \c tag_delete_pending is true.  The only
     *        valid method that can be invoked that is is the destructor.
     *
     *\param seqman    Pointer to mesh entity database
     */
    virtual ErrorCode release_all_data( SequenceManager* seqman, Error* error_handler, bool delete_pending );

    /**\brief Get tag value for passed entities
     *
     * Get tag values for specified entities.
     *
     *\Note Will fail for variable-length data.
     *\param seqman Pointer to mesh entity database
     *\param entities Entity handles for which to retrieve tag data
     *\param num_entities Length of \c entities array
     *\param data Pointer to memory in which to store consecutive tag values,
     *            one for each passed entity.
     */
    virtual ErrorCode get_data( const SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
                                size_t num_entities, void* data ) const;

    /**\brief Get tag value for passed entities
     *
     * Get tag values for specified entities.
     *
     *\Note Will fail for variable-length data.
     *\param seqman Pointer to mesh entity database
     *\param entities Entity handles for which to retrieve tag data
     *\param data Pointer to memory in which to store consecutive tag values,
     *            one for each passed entity.
     */
    virtual ErrorCode get_data( const SequenceManager* seqman, Error* error_handler, const Range& entities,
                                void* data ) const;

    /**\brief Get tag value for passed entities
     *
     * Get tag values for specified entities.
     *
     *\param seqman    Pointer to mesh entity database
     *\param entities  Entity handles for which to retrieve tag data
     *\param num_entities Length of \c entities array
     *\param data_ptrs Array of pointers to tag values, one pointer
     *                 for each passed entity.
     *\param data_lengths One value for each entity specifying the
     *                length of the tag value for the corresponding
     *                entity.
     */
    virtual ErrorCode get_data( const SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
                                size_t num_entities, const void** data_ptrs, int* data_lengths ) const;

    /**\brief Get tag value for passed entities
     *
     * Get tag values for specified entities.
     *
     *\param seqman    Pointer to mesh entity database
     *\param entities  Entity handles for which to retrieve tag data
     *\param data_ptrs Array of pointers to tag values, one pointer
     *                 for each passed entity.
     *\param data_lengths One value for each entity specifying the
     *                length of the tag value for the corresponding
     *                entity.
     */
    virtual ErrorCode get_data( const SequenceManager* seqman, Error* error_handler, const Range& entities,
                                const void** data_ptrs, int* data_lengths ) const;

    /**\brief Set tag value for passed entities
     *
     * Store tag data or update stored tag values
     *\Note Will fail for variable-length data.
     *\param seqman Pointer to mesh entity database
     *\param entities Entity handles for which to store tag data
     *\param num_entities Length of \c entities array
     *\param data Pointer to memory holding consecutive tag values,
     *            one for each passed entity.
     */
    virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
                                size_t num_entities, const void* data );

    /**\brief Set tag value for passed entities
     *
     * Store tag data or update stored tag values
     *\Note Will fail for variable-length data.
     *\param seqman Pointer to mesh entity database
     *\param entities Entity handles for which to store tag data
     *\param data Pointer to memory holding consecutive tag values,
     *            one for each passed entity.
     */
    virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const Range& entities,
                                const void* data );

    /**\brief Set tag value for passed entities
     *
     * Store tag data or update stored tag values
     *
     *\param seqman    Pointer to mesh entity database
     *\param entities  Entity handles for which to store tag data
     *\param num_entities Length of \c entities array
     *\param data_ptrs Array of pointers to tag values, one pointer
     *                 for each passed entity.
     *\param data_lengths One value for each entity specifying the
     *                length of the tag value for the corresponding
     *                entity.  Array is required for variable-length
     *                tags and is ignored for fixed-length tags.
     */
    virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
                                size_t num_entities, void const* const* data_ptrs, const int* data_lengths );

    /**\brief Set tag value for passed entities
     *
     * Store tag data or update stored tag values
     *
     *\param seqman    Pointer to mesh entity database
     *\param entities  Entity handles for which to store tag data
     *\param data_ptrs Array of pointers to tag values, one pointer
     *                 for each passed entity.
     *\param data_lengths One value for each entity specifying the
     *                length of the tag value for the corresponding
     *                entity.  Array is required for variable-length
     *                tags and is ignored for fixed-length tags.
     */
    virtual ErrorCode set_data( SequenceManager* seqman, Error* error_handler, const Range& entities,
                                void const* const* data_ptrs, const int* data_lengths );

    /**\brief Set tag value for passed entities
     *
     * Store tag data or update stored tag values.
     *
     *\param seqman    Pointer to mesh entity database
     *\param entities  Entity handles for which to store tag data
     *\param num_entities Length of \c entities array
     *\param value_ptr Pointer to a single tag value which is to be
     *                 stored for each of the passed entities.
     *\param value_len Length of tag value in bytes.  Ignored for
     *                 fixed-length tags.  Required for variable-
     *                 length tags.
     */
    virtual ErrorCode clear_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
                                  size_t num_entities, const void* value_ptr, int value_len = 0 );

    /**\brief Set tag value for passed entities
     *
     * Store tag data or update stored tag values.
     *
     *\param seqman    Pointer to mesh entity database
     *\param entities  Entity handles for which to store tag data
     *\param value_ptr Pointer to a single tag value which is to be
     *                 stored for each of the passed entities.
     *\param value_len Length of tag value in bytes.  Ignored for
     *                 fixed-length tags.  Required for variable-
     *                 length tags.
     */
    virtual ErrorCode clear_data( SequenceManager* seqman, Error* error_handler, const Range& entities,
                                  const void* value_ptr, int value_len = 0 );

    /**\brief Remove/clear tag data for entities
     *
     * Remove tag values from entities.
     *
     *\param seqman    Pointer to mesh entity database
     *\param entities  Entity handles for which to store tag data
     *\param num_entities Length of \c entities array
     */
    virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const EntityHandle* entities,
                                   size_t num_entities );

    /**\brief Remove/clear tag data for entities
     *
     * Remove tag values from entities.
     *
     *\param seqman    Pointer to mesh entity database
     *\param entities  Entity handles for which to store tag data
     */
    virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const Range& entities );

    /**\brief Access tag data via direct pointer into contiguous blocks
     *
     * Iteratively obtain direct access to contiguous blocks of tag
     * storage.  This function cannot be used with bit tags because
     * of the compressed bit storage.  This function cannot be used
     * with variable length tags because it does not provide a mechanism
     * to determine the length of the value for each entity.  This
     * function may be used with sparse tags, but if it is used, it
     * will return data for a single entity at a time.
     *
     *\param iter        As input, the first entity for which to return
     *                   data.  As output, one past the last entity for
     *                   which data was returned.
     *\param end         One past the last entity for which data is desired
     *\param data_ptr    Output: pointer to tag storage.
     *
     *\Note If this function is called for entities for which no tag value
     *      has been set, but for which a default value exists, it will
     *      force the allocation of explicit storage for each such entity
     *      even though MOAB would normally not explicitly store tag values
     *      for such entities.
     */
    virtual ErrorCode tag_iterate( SequenceManager* seqman, Error* error_handler, Range::iterator& iter,
                                   const Range::iterator& end, void*& data_ptr, bool allocate = true );

    /**\brief Get all tagged entities
     *
     * Get the list of entities for which the a tag value has been set,
     * or a close approximation if the tag storage scheme cannot
     * accurately determine exactly which entities have explicit values.
     *
     *\param seqman   Pointer to entity storage database
     *\param output_entities Results *appended* to this range
     *\param type     Optional entity type.  If specified, search is
     *                limited to entities of specified type.
     *\param intersect Optional intersect list.  If specified,
     *                search is restricted to entities in this list.
     */
    virtual ErrorCode get_tagged_entities( const SequenceManager* seqman, Range& output_entities,
                                           EntityType type = MBMAXTYPE, const Range* intersect = 0 ) const;

    /**\brief Count all tagged entities
     *
     * Count the entities for which the a tag value has been set,
     * or a close approximation if the tag storage scheme cannot
     * accurately determine exactly which entities have explicit values.
     *
     *\param seqman   Pointer to entity storage database
     *\param output_count This is *incremented* for each detected entity.
     *\param type     Optional entity type.  If specified, search is
     *                limited to entities of specified type.
     *\param intersect Optional intersect list.  If specified,
     *                search is restricted to entities in this list.
     */
    virtual ErrorCode num_tagged_entities( const SequenceManager* seqman, size_t& output_count,
                                           EntityType type = MBMAXTYPE, const Range* intersect = 0 ) const;

    /**\brief Get all tagged entities with tag value
     *
     * Get the list of entities which have the specified tag value.
     *
     *\param seqman   Pointer to entity storage database
     *\param output_entities Results *appended* to this range
     *\param value    Pointer to tag value
     *\param value_bytes Size of tag value in bytes.
     *\param type     Optional entity type.  If specified, search is
     *                limited to entities of specified type.
     *\param intersect_entities Optional intersect list.  If specified,
     *                search is restricted to entities in this list.
     */
    virtual ErrorCode find_entities_with_value( const SequenceManager* seqman, Error* error_handler,
                                                Range& output_entities, const void* value, int value_bytes = 0,
                                                EntityType type                 = MBMAXTYPE,
                                                const Range* intersect_entities = 0 ) const;

    /**\brief Check if entity is tagged */
    virtual bool is_tagged( const SequenceManager*, EntityHandle h ) const;

    /**\brief Get memory use for tag data.
     *
     */
    virtual ErrorCode get_memory_use( const SequenceManager* seqman, unsigned long& total,
                                      unsigned long& per_entity ) const;

    /**\brief Get read-only tag storage
     *
     *\param seqman  Sequence manager
     *\param error   Error object through which to report errors
     *\param h       First entity for which to return storage.
     *\param ptr     Pointer to dag storage.  This pointer will be set
     *               to null and \c MB_SUCCESS will be returned if the handle
     *               is valid but no tag storage has been allocated.
     *\param count   Number of consecutive entities for which tag storage
     *               is returned.  This value will be valid even if null
     *               is returned for \c ptr and indicates the number of
     *               consecutive entities for which no tag storage has been
     *               allocated.
     *\return        MB_SUCCESS if handle is valid (regardless of whether
     *               or not any tag storage is allocated).
     */
    ErrorCode get_array( const SequenceManager* seqman, Error* error, EntityHandle h, const unsigned char* const& ptr,
                         size_t& count ) const;

    /**\brief Get read-only tag storage for entire sequence
     *
     *\param seq     Sequence
     *\param ptr     Pointer to dag storage.  This pointer will be set
     *               to null and \c MB_SUCCESS will be returned if no tag storage has been
     *allocated. \return        MB_SUCCESS if sequence is valid (regardless of whether or not any
     *tag storage is allocated).
     */
    ErrorCode get_array( const EntitySequence* seq, const unsigned char* const& ptr ) const;

  private:
    DenseTag( const DenseTag& );
    DenseTag& operator=( const DenseTag& );

    /**\brief Get or allocated tag storage
     *
     *\param h       First entity for which to return storage.
     *\param ptr     Pointer to dag storage.  This pointer will be set
     *               to null and \c MB_SUCCESS will be returned if the handle
     *               is valid but no tag storage has been allocated.
     *\param count   Number of consecutive entities for which tag storage
     *               is returned.  This value will be valid even if null
     *               is returned for \c ptr and indicates the number of
     *               consecutive entities for which no tag storage has been
     *               allocated.
     *\param allocate If true storage will be allocated and initialized
     *               if it has not already been allocated.
     *\return        MB_SUCCESS if handle is valid (regardless of whether
     *               or not any tag storage is allocated).
     */
    inline ErrorCode get_array_private( SequenceManager* seqman, Error* error, EntityHandle h, unsigned char*& ptr,
                                        size_t& count, bool allocate );

    /**\brief Get tag storage
     *
     *\param h       First entity for which to return storage.
     *\param ptr     Pointer to dag storage.  This pointer will be set
     *               to null and \c MB_SUCCESS will be returned if the handle
     *               is valid but no tag storage has been allocated.
     *\param count   Number of consecutive entities for which tag storage
     *               is returned.  This value will be valid even if null
     *               is returned for \c ptr and indicates the number of
     *               consecutive entities for which no tag storage has been
     *               allocated.
     *\return        MB_SUCCESS if handle is valid (regardless of whether
     *               or not any tag storage is allocated).
     */
    inline ErrorCode get_array_private( const SequenceManager* seqman, Error* error, EntityHandle h,
                                        const unsigned char*& ptr, size_t& count ) const;

    /**\brief Get non-read-only tag storage for entire sequence
     *
     *\param seq     Sequence
     *\param ptr     Pointer to dag storage.  This pointer will be set
     *               to null and \c MB_SUCCESS will be returned if no tag storage has been
     *allocated. \return        MB_SUCCESS if sequence is valid (regardless of whether or not any
     *tag storage is allocated).
     */
    ErrorCode get_array_private( const EntitySequence* seq, const unsigned char*& ptr ) const;

    /**\brief Common implementation of public clear_data and remove_data */
    ErrorCode clear_data( bool allocate, SequenceManager* seqman, Error* error, const EntityHandle* entities,
                          size_t num_entities, const void* value_ptr );

    /**\brief Common implementation of public clear_data and remove_data */
    ErrorCode clear_data( bool allocate, SequenceManager* seqman, Error* error, const Range& entities,
                          const void* value_ptr );
};

}  // namespace moab

#endif  // DENSE_TAG_HPP