Debian Codegraph @

include/deal.II/hp/collection.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2021 - 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_hp_collection_h
16 #define dealii_hp_collection_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/memory_consumption.h>
23
24 #include <iterator>
25 #include <memory>
26 #include <vector>
27
28 DEAL_II_NAMESPACE_OPEN
29
30 namespace hp
31 {
32 /**
33 * Exception thrown when comparing hp::Collection iterators into different
34 * objects.
35 *
36 * @ingroup Exceptions
37 */
38 DeclExceptionMsg(ExcDifferentCollection,
39 "You are trying to compare iterators into different "
40 "hp::Collection objects.");
41
42 /**
43 * An iterator for hp::Collection.
44 */
45 template <typename T>
46 class CollectionIterator
47 {
48 public:
49 /**
50 * Constructor.
51 *
52 * @param data The actual data of hp::Collection.
53 * @param index The current index.
54 */
55 CollectionIterator(const std::vector<std::shared_ptr<const T>> &data,
56 const std::size_t index)
57 : data(&data)
58 , index(index)
59 {}
60
61 /**
62 * Copy constructor.
63 */
64 CollectionIterator(const CollectionIterator<T> &other) = default;
65
66 /**
67 * Copy assignment.
68 */
69 CollectionIterator<T> &
70 operator=(const CollectionIterator<T> &other) = default;
71
72 /**
73 * Compare for equality.
74 */
75 bool
76 operator==(const CollectionIterator<T> &other) const
77 {
78 Assert(this->data == other.data, ExcDifferentCollection());
79 return this->index == other.index;
80 }
81
82 /**
83 * Compare for inequality.
84 */
85 bool
86 operator!=(const CollectionIterator<T> &other) const
87 {
88 Assert(this->data == other.data, ExcDifferentCollection());
89 return this->index != other.index;
90 }
91
92 /**
93 * Compare indices.
94 */
95 bool
96 operator<(const CollectionIterator<T> &other) const
97 {
98 Assert(this->data == other.data, ExcDifferentCollection());
99 return this->index < other.index;
100 }
101
102 /**
103 * Compare indices.
104 */
105 bool
106 operator<=(const CollectionIterator<T> &other) const
107 {
108 Assert(this->data == other.data, ExcDifferentCollection());
109 return this->index <= other.index;
110 }
111
112 /**
113 * Compare indices.
114 */
115 bool
116 operator>(const CollectionIterator<T> &other) const
117 {
118 Assert(this->data == other.data, ExcDifferentCollection());
119 return this->index > other.index;
120 }
121
122 /**
123 * Compare indices.
124 */
125 bool
126 operator>=(const CollectionIterator<T> &other) const
127 {
128 Assert(this->data == other.data, ExcDifferentCollection());
129 return this->index >= other.index;
130 }
131
132 /**
133 * Dereferencing operator: returns the value of the current index.
134 */
135 const T &
136 operator*() const
137 {
138 AssertIndexRange(index, data->size());
139 return *(*data)[index];
140 }
141
142 /**
143 * Prefix <tt>++</tt> operator: <tt>++iterator</tt>. This operator advances
144 * the iterator to the next index and returns a reference to
145 * <tt>*this</tt>.
146 */
147 CollectionIterator<T> &
148 operator++()
149 {
150 AssertIndexRange(index + 1, data->size() + 1);
151 ++index;
152 return *this;
153 }
154
155 /**
156 * This operator advances the iterator by @p offset and returns a
157 * reference to <tt>*this</tt>.
158 */
159 CollectionIterator<T> &
160 operator+=(const std::size_t offset)
161 {
162 AssertIndexRange(index + offset, data->size() + 1);
163 index += offset;
164 return *this;
165 }
166
167 /**
168 * Prefix <tt>--</tt> operator: <tt>--iterator</tt>. This operator advances
169 * the iterator to the previous index and returns a reference to
170 * <tt>*this</tt>.
171 */
172 CollectionIterator<T> &
173 operator--()
174 {
175 Assert(
176 index > 0,
177 ExcMessage(
178 "You can't decrement an iterator that is already at the beginning of the range."));
179 --index;
180 return *this;
181 }
182
183 /**
184 * Create new iterator, which is shifted by @p offset.
185 */
186 CollectionIterator<T>
187 operator+(const std::size_t &offset) const
188 {
189 AssertIndexRange(index + offset, T::size() + 1);
190 return CollectionIterator<T>(*data, index + offset);
191 }
192
193 /**
194 * Compute distance between this iterator and iterator @p other.
195 */
196 std::ptrdiff_t
197 operator-(const CollectionIterator<T> &other) const
198 {
199 return static_cast<std::ptrdiff_t>(index) -
200 static_cast<std::ptrdiff_t>(other.index);
201 }
202
203 private:
204 /**
205 * Pointer to the actual data of hp::Collection.
206 */
207 const std::vector<std::shared_ptr<const T>> *data;
208
209 /**
210 * Current index.
211 */
212 std::size_t index;
213 };
214
215 /**
216 * This class implements a collection of objects.
217 *
218 * It implements the concepts stated in the
219 * @ref hpcollection
220 * topic described in the doxygen documentation.
221 *
222 * @ingroup hp hpcollection
223 */
224 template <typename T>
225 class Collection : public EnableObserverPointer
226 {
227 public:
228 /**
229 * Default constructor. Leads to an empty collection that can later be
230 * filled using push_back().
231 */
232 Collection() = default;
233
234 /**
235 * Add a new object.
236 */
237 void
238 push_back(const std::shared_ptr<const T> &new_entry);
239
240 /**
241 * Return the object which was specified by the user for the
242 * active FE index which is provided as a parameter to this method.
243 *
244 * @pre @p index must be between zero and the number of elements of the
245 * collection.
246 */
247 const T &
248 operator[](const unsigned int index) const;
249
250 /**
251 * Return the number of objects stored in this container.
252 */
253 unsigned int
254 size() const;
255
256 /**
257 * The return value of this function is equivalent to
258 * <code>size() == 0</code>
259 */
260 bool
261 empty() const;
262
263 /**
264 * Determine an estimate for the memory consumption (in bytes) of this
265 * object.
266 */
267 std::size_t
268 memory_consumption() const;
269
270 /**
271 * @return An iterator pointing to the beginning of the underlying data (`const`
272 * version).
273 */
274 CollectionIterator<T>
275 begin() const;
276
277 /**
278 * @return An iterator pointing to the end of the underlying data (`const`
279 * version).
280 */
281 CollectionIterator<T>
282 end() const;
283
284 private:
285 /**
286 * The real container, which stores pointers to the different objects.
287 */
288 std::vector<std::shared_ptr<const T>> entries;
289 };
290
291
292 /* --------------- inline functions ------------------- */
293
294
295
296 template <typename T>
297 std::size_t
298 Collection<T>::memory_consumption() const
299 {
300 return (sizeof(*this) + MemoryConsumption::memory_consumption(entries));
301 }
302
303
304
305 template <typename T>
306 void
307 Collection<T>::push_back(const std::shared_ptr<const T> &new_entry)
308 {
309 entries.push_back(new_entry);
310 }
311
312
313
314 template <typename T>
315 inline unsigned int
316 Collection<T>::size() const
317 {
318 return entries.size();
319 }
320
321
322
323 template <typename T>
324 inline bool
325 Collection<T>::empty() const
326 {
327 return this->size() == 0;
328 }
329
330
331
332 template <typename T>
333 inline const T &
334 Collection<T>::operator[](const unsigned int index) const
335 {
336 AssertIndexRange(index, entries.size());
337 return *entries[index];
338 }
339
340
341
342 template <typename T>
343 CollectionIterator<T>
344 Collection<T>::begin() const
345 {
346 return CollectionIterator<T>(entries, 0);
347 }
348
349
350
351 template <typename T>
352 CollectionIterator<T>
353 Collection<T>::end() const
354 {
355 return CollectionIterator<T>(entries, entries.size());
356 }
357
358 } // namespace hp
359
360
361 DEAL_II_NAMESPACE_CLOSE
362
363 namespace std
364 {
365 /**
366 * Iterator traits for hp::CollectionIterator.
367 */
368 template <class T>
369 struct iterator_traits<dealii::hp::CollectionIterator<T>>
370 : public iterator_traits<
371 typename std::vector<std::shared_ptr<const T>>::iterator>
372 {};
373 } // namespace std
374
375 #endif