Mesh Oriented datABase  (version 5.5.1)
An array-based unstructured mesh library
MeshTag.hpp
Go to the documentation of this file.
1 /** \file MeshTag.hpp
2  * \author Jason Kraftcheck
3  * \date 2010-12-14
4  */
5 
6 #ifndef MESH_TAG_HPP
7 #define MESH_TAG_HPP
8 
9 #include "TagInfo.hpp"
10 
11 namespace moab
12 {
13 
14 /**\brief Tag with only a global/mesh value
15  *
16  * Trivial tag implementation. No per-entity values. Only
17  * the global mesh value which is handled by the \c TagInfo
18  * base class.
19  */
20 class MeshTag : public TagInfo
21 {
22  public:
23  //! constructor that takes all parameters
24  MeshTag( const char* name, int size, DataType type, const void* default_value, int default_value_size );
25 
26  virtual ~MeshTag();
27 
28  virtual TagType get_storage_type() const;
29 
30  /**\brief Remove/clear tag data for all entities
31  *
32  * Remove tag values from entities.
33  *
34  *\param 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 delete_pending );
44 
45  /**\brief Get tag value for passed entities
46  *
47  * Get tag values for specified entities.
48  *
49  *\Note Will fail for variable-length data.
50  *\param seqman Pointer to mesh entity database
51  *\param entities Entity handles for which to retrieve tag data
52  *\param num_entities Length of \c entities array
53  *\param data Pointer to memory in which to store consecutive tag values,
54  * one for each passed entity.
55  */
56  virtual ErrorCode get_data( const SequenceManager* seqman,
57  Error* error_handler,
58  const EntityHandle* entities,
59  size_t num_entities,
60  void* data ) const;
61 
62  /**\brief Get tag value for passed entities
63  *
64  * Get tag values for specified entities.
65  *
66  *\Note Will fail for variable-length data.
67  *\param seqman Pointer to mesh entity database
68  *\param entities Entity handles for which to retrieve tag data
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 Range& entities,
75  void* data ) const;
76 
77  /**\brief Get tag value for passed entities
78  *
79  * Get tag values for specified entities.
80  *
81  *\param seqman Pointer to mesh entity database
82  *\param entities Entity handles for which to retrieve tag data
83  *\param num_entities Length of \c entities array
84  *\param data_ptrs Array of pointers to tag values, one pointer
85  * for each passed entity.
86  *\param data_lengths One value for each entity specifying the
87  * length of the tag value for the corresponding
88  * entity.
89  */
90  virtual ErrorCode get_data( const SequenceManager* seqman,
91  Error* error_handler,
92  const EntityHandle* entities,
93  size_t num_entities,
94  const void** data_ptrs,
95  int* data_lengths ) const;
96 
97  /**\brief Get tag value for passed entities
98  *
99  * Get tag values for specified entities.
100  *
101  *\param seqman Pointer to mesh entity database
102  *\param entities Entity handles for which to retrieve tag data
103  *\param data_ptrs Array of pointers to tag values, one pointer
104  * for each passed entity.
105  *\param data_lengths One value for each entity specifying the
106  * length of the tag value for the corresponding
107  * entity.
108  */
109  virtual ErrorCode get_data( const SequenceManager* seqman,
110  Error* error_handler,
111  const Range& entities,
112  const void** data_ptrs,
113  int* data_lengths ) const;
114 
115  /**\brief Set tag value for passed entities
116  *
117  * Store tag data or update stored tag values
118  *\Note Will fail for variable-length data.
119  *\param seqman Pointer to mesh entity database
120  *\param entities Entity handles for which to store tag data
121  *\param num_entities Length of \c entities array
122  *\param data Pointer to memory holding consecutive tag values,
123  * one for each passed entity.
124  */
125  virtual ErrorCode set_data( SequenceManager* seqman,
126  Error* error_handler,
127  const EntityHandle* entities,
128  size_t num_entities,
129  const void* data );
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 data Pointer to memory holding consecutive tag values,
138  * one for each passed entity.
139  */
140  virtual ErrorCode set_data( SequenceManager* seqman,
141  Error* error_handler,
142  const Range& entities,
143  const void* data );
144 
145  /**\brief Set tag value for passed entities
146  *
147  * Store tag data or update stored tag values
148  *
149  *\param seqman Pointer to mesh entity database
150  *\param entities Entity handles for which to store tag data
151  *\param num_entities Length of \c entities array
152  *\param data_ptrs Array of pointers to tag values, one pointer
153  * for each passed entity.
154  *\param data_lengths One value for each entity specifying the
155  * length of the tag value for the corresponding
156  * entity. Array is required for variable-length
157  * tags and is ignored for fixed-length tags.
158  */
159  virtual ErrorCode set_data( SequenceManager* seqman,
160  Error* error_handler,
161  const EntityHandle* entities,
162  size_t num_entities,
163  void const* const* data_ptrs,
164  const int* data_lengths );
165 
166  /**\brief Set tag value for passed entities
167  *
168  * Store tag data or update stored tag values
169  *
170  *\param seqman Pointer to mesh entity database
171  *\param entities Entity handles for which to store tag data
172  *\param data_ptrs Array of pointers to tag values, one pointer
173  * for each passed entity.
174  *\param data_lengths One value for each entity specifying the
175  * length of the tag value for the corresponding
176  * entity. Array is required for variable-length
177  * tags and is ignored for fixed-length tags.
178  */
179  virtual ErrorCode set_data( SequenceManager* seqman,
180  Error* error_handler,
181  const Range& entities,
182  void const* const* data_ptrs,
183  const int* data_lengths );
184 
185  /**\brief Set tag value for passed entities
186  *
187  * Store tag data or update stored tag values.
188  *
189  *\param seqman Pointer to mesh entity database
190  *\param entities Entity handles for which to store tag data
191  *\param num_entities Length of \c entities array
192  *\param value_ptr Pointer to a single tag value which is to be
193  * stored for each of the passed entities.
194  *\param value_len Length of tag value in bytes. Ignored for
195  * fixed-length tags. Required for variable-
196  * length tags.
197  */
198  virtual ErrorCode clear_data( SequenceManager* seqman,
199  Error* error_handler,
200  const EntityHandle* entities,
201  size_t num_entities,
202  const void* value_ptr,
203  int value_len = 0 );
204 
205  /**\brief Set tag value for passed entities
206  *
207  * Store tag data or update stored tag values.
208  *
209  *\param seqman Pointer to mesh entity database
210  *\param entities Entity handles for which to store tag data
211  *\param value_ptr Pointer to a single tag value which is to be
212  * stored for each of the passed entities.
213  *\param value_len Length of tag value in bytes. Ignored for
214  * fixed-length tags. Required for variable-
215  * length tags.
216  */
217  virtual ErrorCode clear_data( SequenceManager* seqman,
218  Error* error_handler,
219  const Range& entities,
220  const void* value_ptr,
221  int value_len = 0 );
222 
223  /**\brief Remove/clear tag data for entities
224  *
225  * Remove tag values from entities.
226  *
227  *\param seqman Pointer to mesh entity database
228  *\param entities Entity handles for which to store tag data
229  *\param num_entities Length of \c entities array
230  */
231  virtual ErrorCode remove_data( SequenceManager* seqman,
232  Error* error_handler,
233  const EntityHandle* entities,
234  size_t num_entities );
235 
236  /**\brief Remove/clear tag data for entities
237  *
238  * Remove tag values from entities.
239  *
240  *\param seqman Pointer to mesh entity database
241  *\param entities Entity handles for which to store tag data
242  */
243  virtual ErrorCode remove_data( SequenceManager* seqman, Error* error_handler, const Range& entities );
244 
245  /**\brief Access tag data via direct pointer into contiguous blocks
246  *
247  * Iteratively obtain direct access to contiguous blocks of tag
248  * storage. This function cannot be used with bit tags because
249  * of the compressed bit storage. This function cannot be used
250  * with variable length tags because it does not provide a mechanism
251  * to determine the length of the value for each entity. This
252  * function may be used with sparse tags, but if it is used, it
253  * will return data for a single entity at a time.
254  *
255  *\param iter As input, the first entity for which to return
256  * data. As output, one past the last entity for
257  * which data was returned.
258  *\param end One past the last entity for which data is desired
259  *\param data_ptr Output: pointer to tag storage.
260  *\param allocate If true, allocate space for this tag as part of this call, else don't
261  *
262  *\Note If this function is called for entities for which no tag value
263  * has been set, but for which a default value exists, it will
264  * force the allocation of explicit storage for each such entity
265  * even though MOAB would normally not explicitly store tag values
266  * for such entities.
267  */
268  virtual ErrorCode tag_iterate( SequenceManager* seqman,
269  Error* error_handler,
270  Range::iterator& iter,
271  const Range::iterator& end,
272  void*& data_ptr,
273  bool allocate = true );
274 
275  /**\brief Get all tagged entities
276  *
277  * Get the list of entities for which the a tag value has been set,
278  * or a close approximation if the tag storage scheme cannot
279  * accurately determine exactly which entities have explicit values.
280  *
281  *\param seqman Pointer to entity storage database
282  *\param output_entities Results *appended* to this range
283  *\param type Optional entity type. If specified, search is
284  * limited to entities of specified type.
285  *\param intersect Optional intersect list. If specified,
286  * search is restricted to entities in this list.
287  */
288  virtual ErrorCode get_tagged_entities( const SequenceManager* seqman,
289  Range& output_entities,
290  EntityType type = MBMAXTYPE,
291  const Range* intersect = 0 ) const;
292 
293  /**\brief Count all tagged entities
294  *
295  * Count the entities for which the a tag value has been set,
296  * or a close approximation if the tag storage scheme cannot
297  * accurately determine exactly which entities have explicit values.
298  *
299  *\param seqman Pointer to entity storage database
300  *\param output_count This is *incremented* for each detected entity.
301  *\param type Optional entity type. If specified, search is
302  * limited to entities of specified type.
303  *\param intersect Optional intersect list. If specified,
304  * search is restricted to entities in this list.
305  */
306  virtual ErrorCode num_tagged_entities( const SequenceManager* seqman,
307  size_t& output_count,
308  EntityType type = MBMAXTYPE,
309  const Range* intersect = 0 ) const;
310 
311  /**\brief Get all tagged entities with tag value
312  *
313  * Get the list of entities which have the specified tag value.
314  *
315  *\param seqman Pointer to entity storage database
316  *\param output_entities Results *appended* to this range
317  *\param value Pointer to tag value
318  *\param value_bytes Size of tag value in bytes.
319  *\param type Optional entity type. If specified, search is
320  * limited to entities of specified type.
321  *\param intersect_entities Optional intersect list. If specified,
322  * search is restricted to entities in this list.
323  */
324  virtual ErrorCode find_entities_with_value( const SequenceManager* seqman,
325  Error* error_handler,
326  Range& output_entities,
327  const void* value,
328  int value_bytes = 0,
329  EntityType type = MBMAXTYPE,
330  const Range* intersect_entities = 0 ) const;
331 
332  /**\brief Check if entity is tagged */
333  virtual bool is_tagged( const SequenceManager*, EntityHandle h ) const;
334 
335  /**\brief Get memory use for tag data.
336  *
337  */
338  virtual ErrorCode get_memory_use( const SequenceManager* seqman,
339  unsigned long& total,
340  unsigned long& per_entity ) const;
341 
342  private:
343  MeshTag( const MeshTag& );
344  MeshTag& operator=( const MeshTag& );
345  std::vector< unsigned char > mValue;
346 };
347 
348 } // namespace moab
349 
350 #endif // MESH_TAG_HPP