Mesh Oriented datABase  (version 5.5.1)
An array-based unstructured mesh library
TagInfo.hpp
Go to the documentation of this file.
1 #ifndef TAG_INFO_HPP
2 #define TAG_INFO_HPP
3 
4 #include "moab/Range.hpp"
5 #include <string>
6 
7 namespace moab
8 {
9 
10 class SequenceManager;
11 class Range;
12 class Error;
13 
14 // ! stores information about a tag
15 class TagInfo
16 {
17  public:
18  //! constructor
20  : mDefaultValue( NULL ), mMeshValue( NULL ), mDefaultValueSize( 0 ), mMeshValueSize( 0 ), mDataSize( 0 ),
22  {
23  }
24 
25  //! constructor that takes all parameters
26  TagInfo( const char* name, int size, DataType type, const void* default_value, int default_value_size );
27 
28  virtual ~TagInfo();
29 
30  /**\brief Remove/clear tag data for all entities
31  *
32  * Remove tag values from entities.
33  *
34  *\param tag_delete_pending If true, then release any global
35  * data associated with the tag in preparation for deleting
36  * the tag itself.
37  *
38  *\Note Invalidates tag if \c tag_delete_pending is true. The only
39  * valid method that can be invoked that is is the destructor.
40  *
41  *\param seqman Pointer to mesh entity database
42  */
43  virtual ErrorCode release_all_data( SequenceManager* seqman, Error* error_handler, bool tag_delete_pending ) = 0;
44 
45  //! set the name of the tag
46  void set_name( const std::string& name )
47  {
48  mTagName = name;
49  }
50 
51  //! get the name of the tag
52  const std::string& get_name() const
53  {
54  return mTagName;
55  }
56 
57  //! get length of default value
59  {
60  return mDefaultValueSize;
61  }
62 
63  //! get the default data
64  const void* get_default_value() const
65  {
66  return mDefaultValue;
67  }
68 
69  //! compare the passed value to the default value.
70  //! returns false if no default value.
71  bool equals_default_value( const void* data, int size = -1 ) const;
72 
73  inline DataType get_data_type() const
74  {
75  return dataType;
76  }
77 
78  //! get the size of the data in bytes
79  int get_size() const
80  {
81  return mDataSize;
82  }
83 
84  //! Check if variable-length tag
85  bool variable_length() const
86  {
87  return get_size() == MB_VARIABLE_LENGTH;
88  }
89 
90  static int size_from_data_type( DataType t );
91 
92  // Check that all lengths are valid multiples of the type size.
93  // Returns true if all lengths are valid, false otherwise.
94  bool check_valid_sizes( const int* sizes, int num_sizes ) const;
95 
96  /**\return MB_VARIABLE_LENGTH_DATA If variable_length() && lengths is NULL
97  * MB_INVALID_SIZE If variable_length() && lengths is not
98  * NULL && any size is not a multiple of
99  * type size.
100  * MB_INVALID_SIZE If !variable_length() && lengths is not
101  * NULL && any size is not the tag size.
102  * MB_SUCCESS Otherwise.
103  */
104  ErrorCode validate_lengths( Error* error_handler, const int* lengths, size_t num_lengths ) const;
105 
106  virtual TagType get_storage_type() const = 0;
107 
108  /**\brief Get tag value for passed entities
109  *
110  * Get tag values for specified entities.
111  *
112  *\Note Will fail for variable-length data.
113  *\param seqman Pointer to mesh entity database
114  *\param entities Entity handles for which to retrieve tag data
115  *\param num_entities Length of \c entities array
116  *\param data Pointer to memory in which to store consecutive tag values,
117  * one for each passed entity.
118  */
119  virtual ErrorCode get_data( const SequenceManager* seqman,
120  Error* error_handler,
121  const EntityHandle* entities,
122  size_t num_entities,
123  void* data ) const = 0;
124 
125  /**\brief Get tag value for passed entities
126  *
127  * Get tag values for specified entities.
128  *
129  *\Note Will fail for variable-length data.
130  *\param seqman Pointer to mesh entity database
131  *\param entities Entity handles for which to retrieve tag data
132  *\param data Pointer to memory in which to store consecutive tag values,
133  * one for each passed entity.
134  */
135  virtual ErrorCode get_data( const SequenceManager* seqman,
136  Error* error_handler,
137  const Range& entities,
138  void* data ) const = 0;
139 
140  /**\brief Get tag value for passed entities
141  *
142  * Get tag values for specified entities.
143  *
144  *\param seqman Pointer to mesh entity database
145  *\param entities Entity handles for which to retrieve tag data
146  *\param num_entities Length of \c entities array
147  *\param data_ptrs Array of pointers to tag values, one pointer
148  * for each passed entity.
149  *\param data_lengths One value for each entity specifying the
150  * length of the tag value for the corresponding
151  * entity.
152  */
153  virtual ErrorCode get_data( const SequenceManager* seqman,
154  Error* error_handler,
155  const EntityHandle* entities,
156  size_t num_entities,
157  const void** data_ptrs,
158  int* data_lengths ) const = 0;
159 
160  /**\brief Get tag value for passed entities
161  *
162  * Get tag values for specified entities.
163  *
164  *\param seqman Pointer to mesh entity database
165  *\param entities Entity handles for which to retrieve tag data
166  *\param data_ptrs Array of pointers to tag values, one pointer
167  * for each passed entity.
168  *\param data_lengths One value for each entity specifying the
169  * length of the tag value for the corresponding
170  * entity.
171  */
172  virtual ErrorCode get_data( const SequenceManager* seqman,
173  Error* error_handler,
174  const Range& entities,
175  const void** data_ptrs,
176  int* data_lengths ) const = 0;
177 
178  /**\brief Set tag value for passed entities
179  *
180  * Store tag data or update stored tag values
181  *\Note Will fail for variable-length data.
182  *\param seqman Pointer to mesh entity database
183  *\param entities Entity handles for which to store tag data
184  *\param num_entities Length of \c entities array
185  *\param data Pointer to memory holding consecutive tag values,
186  * one for each passed entity.
187  */
189  Error* error_handler,
190  const EntityHandle* entities,
191  size_t num_entities,
192  const void* data ) = 0;
193 
194  /**\brief Set tag value for passed entities
195  *
196  * Store tag data or update stored tag values
197  *\Note Will fail for variable-length data.
198  *\param seqman Pointer to mesh entity database
199  *\param entities Entity handles for which to store tag data
200  *\param data Pointer to memory holding consecutive tag values,
201  * one for each passed entity.
202  */
204  Error* error_handler,
205  const Range& entities,
206  const void* data ) = 0;
207 
208  /**\brief Set tag value for passed entities
209  *
210  * Store tag data or update stored tag values
211  *
212  *\param seqman Pointer to mesh entity database
213  *\param entities Entity handles for which to store tag data
214  *\param num_entities Length of \c entities array
215  *\param data_ptrs Array of pointers to tag values, one pointer
216  * for each passed entity.
217  *\param data_lengths One value for each entity specifying the
218  * length of the tag value for the corresponding
219  * entity. Array is required for variable-length
220  * tags and is ignored for fixed-length tags.
221  */
223  Error* error_handler,
224  const EntityHandle* entities,
225  size_t num_entities,
226  void const* const* data_ptrs,
227  const int* data_lengths ) = 0;
228 
229  /**\brief Set tag value for passed entities
230  *
231  * Store tag data or update stored tag values
232  *
233  *\param seqman Pointer to mesh entity database
234  *\param entities Entity handles for which to store tag data
235  *\param data_ptrs Array of pointers to tag values, one pointer
236  * for each passed entity.
237  *\param data_lengths One value for each entity specifying the
238  * length of the tag value for the corresponding
239  * entity. Array is required for variable-length
240  * tags and is ignored for fixed-length tags.
241  */
243  Error* error_handler,
244  const Range& entities,
245  void const* const* data_ptrs,
246  const int* data_lengths ) = 0;
247 
248  /**\brief Set tag value for passed entities
249  *
250  * Store tag data or update stored tag values.
251  *
252  *\param seqman Pointer to mesh entity database
253  *\param entities Entity handles for which to store tag data
254  *\param num_entities Length of \c entities array
255  *\param value_ptr Pointer to a single tag value which is to be
256  * stored for each of the passed entities.
257  *\param value_len Length of tag value in bytes. Ignored for
258  * fixed-length tags. Required for variable-
259  * length tags.
260  */
262  Error* error_handler,
263  const EntityHandle* entities,
264  size_t num_entities,
265  const void* value_ptr,
266  int value_len = 0 ) = 0;
267 
268  /**\brief Set tag value for passed entities
269  *
270  * Store tag data or update stored tag values.
271  *
272  *\param seqman Pointer to mesh entity database
273  *\param entities Entity handles for which to store tag data
274  *\param value_ptr Pointer to a single tag value which is to be
275  * stored for each of the passed entities.
276  *\param value_len Length of tag value in bytes. Ignored for
277  * fixed-length tags. Required for variable-
278  * length tags.
279  */
281  Error* error_handler,
282  const Range& entities,
283  const void* value_ptr,
284  int value_len = 0 ) = 0;
285 
286  /**\brief Remove/clear tag data for entities
287  *
288  * Remove tag values from entities.
289  *
290  *\param seqman Pointer to mesh entity database
291  *\param entities Entity handles for which to store tag data
292  *\param num_entities Length of \c entities array
293  */
295  Error* error_handler,
296  const EntityHandle* entities,
297  size_t num_entities ) = 0;
298 
299  /**\brief Remove/clear tag data for entities
300  *
301  * Remove tag values from entities.
302  *
303  *\param seqman Pointer to mesh entity database
304  *\param entities Entity handles for which to store tag data
305  */
306  virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const Range& entities ) = 0;
307 
308  /**\brief Access tag data via direct pointer into contiguous blocks
309  *
310  * Iteratively obtain direct access to contiguous blocks of tag
311  * storage. This function cannot be used with bit tags because
312  * of the compressed bit storage. This function cannot be used
313  * with variable length tags because it does not provide a mechanism
314  * to determine the length of the value for each entity. This
315  * function may be used with sparse tags, but if it is used, it
316  * will return data for a single entity at a time.
317  *
318  *\param iter As input, the first entity for which to return
319  * data. As output, one past the last entity for
320  * which data was returned.
321  *\param end One past the last entity for which data is desired
322  *\param data_ptr Output: pointer to tag storage.
323  *\param allocate If true, space for this tag will be allocated, if not it wont
324  *
325  *\Note If this function is called for entities for which no tag value
326  * has been set, but for which a default value exists, it will
327  * force the allocation of explicit storage for each such entity
328  * even though MOAB would normally not explicitly store tag values
329  * for such entities.
330  */
332  Error* error_handler,
333  Range::iterator& iter,
334  const Range::iterator& end,
335  void*& data_ptr,
336  bool allocate = true ) = 0;
337 
338  /**\brief Get all tagged entities
339  *
340  * Get the list of entities for which the a tag value has been set,
341  * or a close approximation if the tag storage scheme cannot
342  * accurately determine exactly which entities have explicit values.
343  *
344  *\param seqman Pointer to entity storage database
345  *\param output_entities Results *appended* to this range
346  *\param type Optional entity type. If specified, search is
347  * limited to entities of specified type.
348  *\param intersect Optional intersect list. If specified,
349  * search is restricted to entities in this list.
350  */
352  Range& output_entities,
353  EntityType type = MBMAXTYPE,
354  const Range* intersect = 0 ) const = 0;
355 
356  /**\brief Count all tagged entities
357  *
358  * Count the entities for which the a tag value has been set,
359  * or a close approximation if the tag storage scheme cannot
360  * accurately determine exactly which entities have explicit values.
361  *
362  *\param seqman Pointer to entity storage database
363  *\param output_count This is *incremented* for each detected entity.
364  *\param type Optional entity type. If specified, search is
365  * limited to entities of specified type.
366  *\param intersect Optional intersect list. If specified,
367  * search is restricted to entities in this list.
368  */
370  size_t& output_count,
371  EntityType type = MBMAXTYPE,
372  const Range* intersect = 0 ) const = 0;
373 
374  /**\brief Get all tagged entities with tag value
375  *
376  * Get the list of entities which have the specified tag value.
377  *
378  *\param seqman Pointer to entity storage database
379  *\param output_entities Results *appended* to this range
380  *\param value Pointer to tag value
381  *\param value_bytes Size of tag value in bytes.
382  *\param type Optional entity type. If specified, search is
383  * limited to entities of specified type.
384  *\param intersect_entities Optional intersect list. If specified,
385  * search is restricted to entities in this list.
386  */
388  Error* error_handler,
389  Range& output_entities,
390  const void* value,
391  int value_bytes = 0,
392  EntityType type = MBMAXTYPE,
393  const Range* intersect_entities = 0 ) const = 0;
394 
395  /**\brief Check if entity is tagged */
396  virtual bool is_tagged( const SequenceManager* seqman, EntityHandle entity ) const = 0;
397 
398  /**\brief Get memory use for tag data.
399  *
400  */
401  virtual ErrorCode get_memory_use( const SequenceManager* seqman,
402  unsigned long& total,
403  unsigned long& per_entity ) const = 0;
404 
405  protected:
406  unsigned long get_memory_use() const
407  {
408  return get_default_value_size() + get_name().size();
409  }
410 
411  private:
412  TagInfo( const TagInfo& copy );
413 
414  TagInfo& operator=( const TagInfo& copy );
415 
416  //! stores the default data, if any
418 
419  //! store the mesh value, if any
420  void* mMeshValue;
421 
422  //! Size of mDefaultValue and mMeshValue, in bytes
423  //! NOTE: These sizes differ from mDataSize in two cases:
424  //! a) Variable-length tags
425  //! b) Bit tags (where mDataSize is bits, not bytes.)
427 
428  //! stores the size of the data for this tag
430 
431  //! type of tag data
433 
434  //! stores the tag name
435  std::string mTagName;
436 };
437 
438 } // namespace moab
439 
440 #endif // TAG_INFO_HPP