Debian Codegraph @

include/deal.II/algorithms/any_data.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2014 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_any_data_h
16 #define dealii_any_data_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/enable_observer_pointer.h>
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/types.h>
23
24 #include <algorithm>
25 #include <any>
26 #include <ostream>
27 #include <typeinfo>
28 #include <vector>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 /**
33 * Store any amount of any type of data accessible by an identifier string.
34 *
35 * @todo GK: Deprecate access to AnyData by index and change to a map.
36 */
37 class AnyData : public EnableObserverPointer
38 {
39 public:
40 /// Default constructor for empty object
41 AnyData() = default;
42
43 /// Number of stored data objects.
44 unsigned int
45 size() const;
46
47 /// Add a new data object
48 template <typename type>
49 void
50 add(type entry, const std::string &name);
51
52 /**
53 * @brief Merge the data of another AnyData to the end of this object.
54 */
55 void
56 merge(const AnyData &other);
57
58 /**
59 * @brief Access to stored data object by name.
60 *
61 * Find the object with given name, try to convert it to <tt>type</tt> and
62 * return it. This function throws an exception if either the name does not
63 * exist or if the conversion fails. If such an exception is not desired,
64 * use try_read() instead.
65 */
66 template <typename type>
67 type
68 entry(const std::string &name);
69
70 /**
71 * @brief Read-only access to stored data object by name.
72 *
73 * Find the object with given name, try to convert it to <tt>type</tt> and
74 * return it. This function throws an exception if either the name does not
75 * exist or if the conversion fails. If such an exception is not desired,
76 * use try_read() instead.
77 */
78 template <typename type>
79 type
80 entry(const std::string &name) const;
81
82 /**
83 * @brief Dedicated read only access by name.
84 *
85 * For a constant object, this function equals entry(). For a non-const
86 * object, it forces read only access to the data. In particular, it throws
87 * an exception if the object is not found or cannot be converted to type.
88 * If such an exception is not desired, use try_read() instead.
89 *
90 * @warning Do not use this function for stored objects which are pointers.
91 * Use read_ptr() instead!
92 */
93 template <typename type>
94 type
95 read(const std::string &name) const;
96
97 /**
98 * @brief Dedicated read only access by name for pointer data.
99 *
100 * If the stored data object is a pointer to a constant object, the logic of
101 * access becomes fairly complicated. Namely, the standard read function may
102 * fail, depending on whether it was a const pointer or a regular pointer.
103 * This function fixes the logic and ascertains that the object does not
104 * become mutable by accident.
105 */
106 template <typename type>
107 const type *
108 read_ptr(const std::string &name) const;
109
110 /**
111 * Perform the same action as read_ptr(), but do not throw an exception if
112 * the pointer does not exist. Return a null pointer instead.
113 */
114 template <typename type>
115 const type *
116 try_read_ptr(const std::string &name) const;
117
118 /**
119 * @brief Dedicated read only access by name without exceptions.
120 *
121 * This function tries to find the name in the list and return a pointer to
122 * the associated object. If either the name is not found or the object
123 * cannot be converted to the return type, a null pointer is returned.
124 */
125 template <typename type>
126 const type *
127 try_read(const std::string &name) const;
128
129 /**
130 * Access to stored data object by index.
131 */
132 template <typename type>
133 type
134 entry(const unsigned int i);
135
136 /// Read-only access to stored data object by index.
137 template <typename type>
138 type
139 entry(const unsigned int i) const;
140
141 /// Dedicated read only access.
142 template <typename type>
143 type
144 read(const unsigned int i) const;
145
146 /// Dedicated read only access to pointer object.
147 template <typename type>
148 const type *
149 read_ptr(const unsigned int i) const;
150
151 /// Dedicated read only access to pointer object without exception.
152 template <typename type>
153 const type *
154 try_read_ptr(const unsigned int i) const;
155
156 /// Dedicated read only access without exception.
157 template <typename type>
158 const type *
159 try_read(const unsigned int i) const;
160
161 /// Name of object at index.
162 const std::string &
163 name(const unsigned int i) const;
164
165 /**
166 * @brief Find index of a named object
167 *
168 * Try to find the object and return its index in the list. Throw an
169 * exception if the object has not been found.
170 */
171 unsigned int
172 find(const std::string &name) const;
173
174 /**
175 * @brief Try to find index of a named object
176 *
177 * Try to find the object and return its index in the list. returns
178 * numbers::invalid_unsigned_int if the name was not found.
179 */
180 unsigned int
181 try_find(const std::string &name) const;
182
183 /// Find out if object is of a certain type
184 template <typename type>
185 bool
186 is_type(const unsigned int i) const;
187
188 /// List the contents to a stream
189 template <typename StreamType>
190 void
191 list(StreamType &os) const;
192
193 /// An entry with this name does not exist in the AnyData object.
194 DeclException1(ExcNameNotFound,
195 std::string,
196 << "No entry with the name " << arg1 << " exists.");
197
198 /// The requested type and the stored type are different
199 DeclException2(ExcTypeMismatch,
200 std::string,
201 std::string,
202 << "The requested type " << arg1 << " and the stored type "
203 << arg2 << " must coincide.");
204
205 /**
206 * Exception indicating that a function expected a vector to have a certain
207 * name, but we store a different name in that position.
208 */
209 DeclException2(ExcNameMismatch,
210 int,
211 std::string,
212 << "Name at position " << arg1 << " is not equal to " << arg2
213 << '.');
214
215 private:
216 /// The stored data
217 std::vector<std::any> data;
218 /// The names of the stored data
219 std::vector<std::string> names;
220 };
221
222
223 unsigned int inline AnyData::size() const
224 {
225 AssertDimension(data.size(), names.size());
226 return data.size();
227 }
228
229
230 template <typename type>
231 inline type
232 AnyData::entry(const unsigned int i)
233 {
234 AssertIndexRange(i, size());
235 const type *p = std::any_cast<type>(&data[i]);
236 Assert(p != nullptr,
237 ExcTypeMismatch(typeid(type).name(), data[i].type().name()));
238 return *p;
239 }
240
241
242 template <typename type>
243 inline type
244 AnyData::entry(const unsigned int i) const
245 {
246 AssertIndexRange(i, size());
247 const type *p = std::any_cast<type>(&data[i]);
248 if (p == nullptr)
249 p = std::any_cast<const type>(&data[i]);
250 Assert(p != nullptr,
251 ExcTypeMismatch(typeid(type).name(), data[i].type().name()));
252 return *p;
253 }
254
255
256 template <typename type>
257 inline type
258 AnyData::read(const unsigned int i) const
259 {
260 AssertIndexRange(i, size());
261 const type *p = std::any_cast<type>(&data[i]);
262 if (p == nullptr)
263 p = std::any_cast<const type>(&data[i]);
264 Assert(p != nullptr,
265 ExcTypeMismatch(typeid(type).name(), data[i].type().name()));
266 return *p;
267 }
268
269
270 template <typename type>
271 inline const type *
272 AnyData::read_ptr(const unsigned int i) const
273 {
274 AssertIndexRange(i, size());
275 const type *const *p = std::any_cast<type *>(&data[i]);
276 if (p == nullptr)
277 p = std::any_cast<const type *>(&data[i]);
278 Assert(p != nullptr,
279 ExcTypeMismatch(typeid(type *).name(), data[i].type().name()));
280 return *p;
281 }
282
283
284 template <typename type>
285 inline const type *
286 AnyData::try_read_ptr(const unsigned int i) const
287 {
288 AssertIndexRange(i, size());
289 const type *const *p = std::any_cast<type *>(&data[i]);
290 if (p == nullptr)
291 p = std::any_cast<const type *>(&data[i]);
292 if (p == nullptr)
293 return nullptr;
294 return *p;
295 }
296
297
298 template <typename type>
299 inline const type *
300 AnyData::try_read(const unsigned int i) const
301 {
302 AssertIndexRange(i, size());
303 const type *p = std::any_cast<type>(&data[i]);
304 if (p == 0)
305 p = std::any_cast<const type>(&data[i]);
306 return p;
307 }
308
309
310 inline const std::string &
311 AnyData::name(const unsigned int i) const
312 {
313 AssertIndexRange(i, size());
314 return names[i];
315 }
316
317
318 inline unsigned int
319 AnyData::try_find(const std::string &n) const
320 {
321 std::vector<std::string>::const_iterator it =
322 std::find(names.begin(), names.end(), n);
323
324 if (it == names.end())
325 return numbers::invalid_unsigned_int;
326
327 return it - names.begin();
328 }
329
330
331 inline unsigned int
332 AnyData::find(const std::string &n) const
333 {
334 const unsigned int i = try_find(n);
335 Assert(i != numbers::invalid_unsigned_int, ExcNameNotFound(n));
336
337 return i;
338 }
339
340
341 template <typename type>
342 inline bool
343 AnyData::is_type(const unsigned int i) const
344 {
345 return data[i].type() == typeid(type);
346 }
347
348
349 template <typename type>
350 inline type
351 AnyData::entry(const std::string &n)
352 {
353 const unsigned int i = find(n);
354 const type *p = std::any_cast<type>(&data[i]);
355 Assert(p != 0, ExcTypeMismatch(typeid(type).name(), data[i].type().name()));
356 return *p;
357 }
358
359
360 template <typename type>
361 inline type
362 AnyData::entry(const std::string &n) const
363 {
364 const unsigned int i = find(n);
365 const type *p = std::any_cast<type>(&data[i]);
366 Assert(p != nullptr,
367 ExcTypeMismatch(typeid(type).name(), data[i].type().name()));
368 return *p;
369 }
370
371
372 template <typename type>
373 inline type
374 AnyData::read(const std::string &n) const
375 {
376 const unsigned int i = find(n);
377 const type *p = std::any_cast<type>(&data[i]);
378 Assert(p != 0, ExcTypeMismatch(typeid(type).name(), data[i].type().name()));
379 return *p;
380 }
381
382
383 template <typename type>
384 inline const type *
385 AnyData::read_ptr(const std::string &n) const
386 {
387 const unsigned int i = find(n);
388 const type *const *p = std::any_cast<type *>(&data[i]);
389 if (p == nullptr)
390 p = std::any_cast<const type *>(&data[i]);
391 Assert(p != nullptr,
392 ExcTypeMismatch(typeid(type).name(), data[i].type().name()));
393 return *p;
394 }
395
396
397 template <typename type>
398 inline const type *
399 AnyData::try_read_ptr(const std::string &n) const
400 {
401 const unsigned int i = try_find(n);
402 if (i == numbers::invalid_unsigned_int)
403 return 0;
404
405 const type *const *p = std::any_cast<type *>(&data[i]);
406 if (p == 0)
407 p = std::any_cast<const type *>(&data[i]);
408 return *p;
409 }
410
411
412 template <typename type>
413 inline const type *
414 AnyData::try_read(const std::string &n) const
415 {
416 // Try to find name
417 std::vector<std::string>::const_iterator it =
418 std::find(names.begin(), names.end(), n);
419 // Return null pointer if not found
420 if (it == names.end())
421 return nullptr;
422
423 // Compute index and return casted pointer
424 unsigned int i = it - names.begin();
425 const type *p = std::any_cast<type>(&data[i]);
426 return p;
427 }
428
429
430 template <typename type>
431 inline void
432 AnyData::add(type ent, const std::string &n)
433 {
434 std::any e = ent;
435 data.push_back(e);
436 names.push_back(n);
437 }
438
439
440 inline void
441 AnyData::merge(const AnyData &other)
442 {
443 for (unsigned int i = 0; i < other.size(); ++i)
444 {
445 names.push_back(other.names[i]);
446 data.push_back(other.data[i]);
447 }
448 }
449
450
451 template <typename StreamType>
452 inline void
453 AnyData::list(StreamType &os) const
454 {
455 for (unsigned int i = 0; i < names.size(); ++i)
456 {
457 os << i << '\t' << names[i] << '\t' << data[i].type().name() << std::endl;
458 }
459 }
460
461
462 //----------------------------------------------------------------------//
463
464
465
466 DEAL_II_NAMESPACE_CLOSE
467
468 #endif