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