Debian Codegraph @

include/deal.II/base/table_handler.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1999 - 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_table_handler_h
16 #define dealii_table_handler_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22
23 #include <boost/serialization/map.hpp>
24 #include <boost/serialization/split_member.hpp>
25 #include <boost/serialization/string.hpp>
26 #include <boost/serialization/vector.hpp>
27
28 #include <cstdint>
29 #include <map>
30 #include <ostream>
31 #include <string>
32 #include <variant>
33 #include <vector>
34
35
36 DEAL_II_NAMESPACE_OPEN
37
38 // Forward declaration
39 #ifndef DOXYGEN
40 class TableHandler;
41 #endif
42
43 namespace internal
44 {
45 /**
46 * A <tt>TableEntry</tt> stores the value of a table entry. It can either be
47 * of type int, unsigned int, std::uint64_t, double or std::string. In
48 * essence, this structure is the same as `std::variant<int,unsigned
49 * int,std::uint64_t,double,std::string>` but we wrap this object in a
50 * structure for which we can write a function that can serialize it. This is
51 * also why the function is not in fact of type std::any.
52 */
53 struct TableEntry
54 {
55 public:
56 /**
57 * Default constructor.
58 */
59 TableEntry() = default;
60
61 /**
62 * Constructor. Initialize this table element with the value
63 * <code>t</code>.
64 */
65 template <typename T>
66 explicit TableEntry(const T &t);
67
68 /**
69 * Return the value stored by this object. The template type T must be one
70 * of <code>int,unsigned int,std::uint64_t,double,std::string</code> and it
71 * must match the data type of the object originally stored in this
72 * TableEntry object.
73 */
74 template <typename T>
75 T
76 get() const;
77
78 /**
79 * Return the numeric value of this object if data has been stored in it
80 * either as an integer, an unsigned integer,std::uint64_t, or a double.
81 *
82 * @return double
83 */
84 double
85 get_numeric_value() const;
86
87 /**
88 * Cache the contained value with the given formatting and return it. The
89 * given parameters from the column definition are used for the
90 * formatting. The value is cached as a string internally in cached_value.
91 * The cache needs to be invalidated with this routine if the formatting
92 * of the column changes.
93 */
94 void
95 cache_string(bool scientific, unsigned int precision) const;
96
97 /**
98 * Return the value cached using cache_string(). This is just a wrapper
99 * around cached_value.
100 */
101 const std::string &
102 get_cached_string() const;
103
104
105 /**
106 * Return a TableEntry object that has the same data type of the stored
107 * value but with a value that is default constructed for this data type.
108 * This is used to pad columns below previously set ones.
109 */
110 TableEntry
111 get_default_constructed_copy() const;
112
113 /**
114 * Write the data of this object to a stream for the purpose of
115 * serialization using the [BOOST serialization
116 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
117 */
118 template <class Archive>
119 void
120 save(Archive &ar, const unsigned int version) const;
121
122 /**
123 * Read the data of this object from a stream for the purpose of
124 * serialization using the [BOOST serialization
125 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
126 */
127 template <class Archive>
128 void
129 load(Archive &ar, const unsigned int version);
130
131 #ifdef DOXYGEN
132 /**
133 * Write and read the data of this object from a stream for the purpose
134 * of serialization using the [BOOST serialization
135 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
136 */
137 template <class Archive>
138 void
139 serialize(Archive &archive, const unsigned int version);
140 #else
141 // This macro defines the serialize() method that is compatible with
142 // the templated save() and load() method that have been implemented.
143 BOOST_SERIALIZATION_SPLIT_MEMBER()
144 #endif
145
146 private:
147 /**
148 * Abbreviation for the data type stored by this object.
149 */
150 using value_type =
151 std::variant<int, unsigned int, std::uint64_t, double, std::string>;
152
153 /**
154 * Stored value.
155 */
156 value_type value;
157
158 /**
159 * Cache the current value as a string.
160 */
161 mutable std::string cached_value;
162
163 friend class dealii::TableHandler;
164 };
165 } // namespace internal
166
167
168 /**
169 * The TableHandler stores TableEntries of arbitrary value type and writes the
170 * table as text or in tex format to an output stream. The value type actually
171 * may vary from column to column and from row to row.
172 *
173 * <h3>Usage</h3>
174 *
175 * The most important function is the templatized function
176 * <code>add_value(const std::string &key, const T value)</code> that adds a
177 * column with the name <tt>key</tt> to the table if this column does not yet
178 * exist and adds the given value of type <tt>T</tt> (which must be one of
179 * <tt>int</tt>, <tt>unsigned int</tt>, <tt>double</tt>, <tt>std::string</tt>)
180 * to this column. After the table is complete there are different
181 * possibilities of output, e.g., into a latex file with write_tex() or as
182 * text with write_text().
183 *
184 * Two (or more) columns may be merged into a "supercolumn" by twice (or
185 * multiple) calling add_column_to_supercolumn(), see there. Additionally
186 * there is a function to set for each column the precision of the output of
187 * numbers, and there are several functions to prescribe the format and the
188 * captions the columns are written with in tex mode.
189 *
190 * A detailed explanation of this class is also given in the step-13 tutorial
191 * program.
192 *
193 *
194 * <h3>Example</h3>
195 *
196 * This is a simple example demonstrating the usage of this class. The first
197 * column includes the numbers $i=1 \dots n$, the second $1^2 \dots n^2$, the
198 * third $\sqrt{1}\dots\sqrt{n}$, where the second and third columns are merged
199 * into one supercolumn with the superkey <tt>squares and roots</tt>.
200 * Additionally the first column is aligned to the right (the default was
201 * <tt>centered</tt>) and the precision of the square roots are set to be 6
202 * (instead of 4 as default).
203 *
204 * @code
205 * TableHandler table;
206 * for (unsigned int i = 1; i <= n; ++i)
207 * {
208 * table.add_value("numbers", i);
209 * table.add_value("squares", i * i);
210 * table.add_value("square roots", std::sqrt(i));
211 * }
212 * // merge the second and third column
213 * table.add_column_to_supercolumn("squares", "squares and roots");
214 * table.add_column_to_supercolumn("square roots", "squares and roots");
215 *
216 * // additional settings
217 * table.set_tex_format("numbers", "r");
218 * table.set_precision("square roots", 6);
219 *
220 * // output
221 * std::ofstream out_file("number_table.tex");
222 * table.write_tex(out_file);
223 * out_file.close();
224 * @endcode
225 *
226 *
227 * <h3>Dealing with sparse data: auto-fill mode</h3>
228 *
229 * When generating output, TableHandler expects that all columns have the
230 * exact same number of elements in it so that the result is in fact a table.
231 * This assumes that in each of the iterations (time steps, nonlinear
232 * iterations, etc) you fill every single column. On the other hand, this may
233 * not always be what you want to do. For example, it could be that the
234 * function that computes the nonlinear residual is only called every few time
235 * steps; or, a function computing statistics of the mesh is only called
236 * whenever the mesh is in fact refined. In these cases, the add_value()
237 * function will be called less often for some columns and the column would
238 * therefore have fewer elements; furthermore, these elements would not be
239 * aligned with the rows that contain the other data elements that were
240 * produced during this iteration. An entirely different scenario is that the
241 * table is filled and at a later time we use the data in there to compute the
242 * elements of other rows; the ConvergenceTable class does something like
243 * this.
244 *
245 * To support both scenarios, the TableHandler class has a property called <i
246 * >auto-fill mode</i>. By default, auto-fill mode is off, but it can be
247 * enabled by calling set_auto_fill_mode(). If auto-fill mode is enabled we
248 * use the following algorithm:
249 *
250 * - When calling <code>add_value(key, value)</code>, we count the number of
251 * elements in the column corresponding to <code>key</code>. Let's call this
252 * number $m$.
253 *
254 * - We also determine the maximal number of elements in the other columns;
255 * call it $n$.
256 *
257 * - If $m < n-1$ then we add $n-m-1$ copies of the object <code>T()</code> to
258 * this column. Here, <code>T</code> is the data type of the given
259 * <code>value</code>. For example, if <code>T</code> is a numeric type, then
260 * <code>T()</code> is the number zero; if <code>T</code> is
261 * <code>std::string</code>, then <code>T()</code> is the empty string
262 * <code>""</code>.
263 *
264 * - Add the given value to this column.
265 *
266 * Padding the column with default elements makes sure that after the addition
267 * the column has as many entries as the longest other column. In other words,
268 * if we have skipped previous invocations of add_value() for a given key,
269 * then the padding will enter default values into this column.
270 *
271 * The algorithm as described will fail if you try to skip adding values for a
272 * key if adding an element for this key is the first thing you want to do for
273 * a given iteration or time step, since we would then pad to the length of
274 * the longest column of the <i>previous</i> iteration or time step. You may
275 * have to re-order adding to this column to a different spot in your program,
276 * after adding to a column that will always be added to; or, you may want to
277 * start every iteration by adding the number of the iteration to the table,
278 * for example in column 1.
279 *
280 * In the case above, we have always padded columns <b>above</b> the element
281 * that is being added to a column. However, there is also a case where we
282 * have to pad <b>below</b>. Namely, if a previous row has been completely
283 * filled using TableHandler::add_value(), subsequent rows have been filled
284 * partially, and we then ask for output via write_text() or write_tex(). In
285 * that case, the last few rows that have been filled only partially need to
286 * be padded below the last element that has been added to them. As before, we
287 * do that by using default constructed objects of the same type as the last
288 * element of that column.
289 *
290 * @ingroup textoutput
291 */
292 class TableHandler
293 {
294 public:
295 /**
296 * Set of options how a table should be formatted when output with the
297 * write_text() function. The following possibilities exist:
298 *
299 * - <code>table_with_headers</code>: The table is formatted in such a way
300 * that the contents are aligned under the key of each column, i.e. the key
301 * sits atop each column. This is suitable for tables with few columns where
302 * the entire table can be displayed on the screen. Output looks like this:
303 * @code
304 * key1 key2 key3
305 * 0 0 ""
306 * 1 0 ""
307 * 2 13 a
308 * 1 0 ""
309 * @endcode
310 * - <code>table_with_separate_column_description</code>: This is a better
311 * format when there are many columns and the table as a whole can not be
312 * displayed on the screen. Here, the column keys are first listed
313 * one-by-one on lines of their own, and are numbered for better readability.
314 * In addition, each of these description lines are prefixed by '#' to mark
315 * these lines as comments for programs that want to read the following
316 * table as data and should ignore these descriptive lines. GNUPLOT is one
317 * such program that will automatically ignore lines so prefixed. Output
318 * with this option looks like this:
319 * @code
320 * # 1: key1
321 * # 2: key2
322 * # 3: key3
323 * 0 0 ""
324 * 1 0 ""
325 * 2 13 a
326 * 1 0 ""
327 * @endcode
328 * - <code>simple_table_with_separate_column_description</code>: This format
329 * is very similar to <code>table_with_separate_column_description</code>,
330 * but it skips aligning the columns with additional white space. This
331 * increases the performance of write_text() for large tables. Example
332 * output:
333 * @code
334 * # 1: key1
335 * # 2: key2
336 * # 3: key3
337 * 0 0 ""
338 * 1 0 ""
339 * 2 13 a
340 * 1 0 ""
341 * @endcode
342 * - <code>org_mode_table</code>: Outputs to org-mode (http://orgmode.org/)
343 * table format. It is easy to convert org-mode tables to HTML/LaTeX/csv.
344 * Example output:
345 * @code
346 * | key1 | key2 | key3 |
347 * | 0 | 0 | "" |
348 * | 1 | 0 | "" |
349 * | 2 | 13 | a |
350 * | 1 | 0 | "" |
351 * @endcode
352 */
353 enum TextOutputFormat
354 {
355 /**
356 * Print the table with headers.
357 */
358 table_with_headers,
359 /**
360 * Print the table with separate lines for each column label.
361 */
362 table_with_separate_column_description,
363 /**
364 * Like table_with_separate_column_description, but without aligning the
365 * column containing the column labels.
366 */
367 simple_table_with_separate_column_description,
368 /**
369 * Print the table in org mode format.
370 */
371 org_mode_table
372 };
373
374 /**
375 * Constructor.
376 */
377 TableHandler();
378
379
380 /**
381 * Declare the existence of a column in the table by giving it a name.
382 * As discussed in the documentation of the class, this is not usually
383 * necessary -- just adding a value for a given column key via the
384 * add_value() function also declares the column. This function is
385 * therefore only necessary in cases where you want a column to
386 * also show up even if you never add an entry to any row in this column;
387 * or, more likely, if you want to prescribe the order in which columns
388 * are later printed by declaring columns in a particular order before
389 * entries are ever put into them.
390 *
391 * (The latter objective can also be achieved by adding entries to
392 * the table in whatever order they are produced by a program,
393 * and later calling set_column_order(). However, this approach
394 * requires knowing -- in one central place of your software --
395 * all of the columns keys that other parts of the software have
396 * written into, and how they should be sorted. This is easily
397 * possible for small programs, but may not be feasible for
398 * large code bases in which parts of the code base are only
399 * executed based on run-time parameters.)
400 */
401 void
402 declare_column(const std::string &key);
403
404 /**
405 * Adds a column (if not yet existent) with the key <tt>key</tt> and adds
406 * the value of type <tt>T</tt> to the column. Values of type <tt>T</tt>
407 * must be convertible to one of <code>int, unsigned int, double,
408 * std::uint64_t, std::string</code> or a compiler error will result.
409 */
410 template <typename T>
411 void
412 add_value(const std::string &key, const T value);
413
414 /**
415 * If a row is only partially filled, then set all elements of that
416 * row for which no elements exist in a particular column to the
417 * empty string. This is akin to the 'auto_fill_mode' described in
418 * the introduction, but more general because it allows you to start
419 * writing into a column for a new row without having to know that
420 * that column had been written to in the previous row.
421 *
422 * If all columns have been written into in the current row, then
423 * this function doesn't do anything at all. In other words,
424 * conceptually the function "completes" the current row, though its
425 * use case is to "start" a new row.
426 */
427 void
428 start_new_row();
429
430 /**
431 * Switch auto-fill mode on or off. See the general documentation of this
432 * class for a description of what auto-fill mode does.
433 */
434 void
435 set_auto_fill_mode(const bool state);
436
437 /**
438 * Creates a supercolumn (if not yet existent) and includes column to it.
439 * The keys of the column and the supercolumn are <tt>key</tt> and
440 * <tt>superkey</tt>, respectively. To merge two columns <tt>c1</tt> and
441 * <tt>c2</tt> to a supercolumn <tt>sc</tt> hence call
442 * <tt>add_column_to_supercolumn(c1,sc)</tt> and
443 * <tt>add_column_to_supercolumn(c2,sc)</tt>.
444 *
445 * Concerning the order of the columns, the supercolumn replaces the first
446 * column that is added to the supercolumn. Within the supercolumn the order
447 * of output follows the order the columns are added to the supercolumn.
448 */
449 void
450 add_column_to_supercolumn(const std::string &key,
451 const std::string &superkey);
452
453 /**
454 * Change the order of columns and supercolumns in the table.
455 *
456 * <tt>new_order</tt> includes the keys and superkeys of the columns and
457 * supercolumns in the order the user would like them to be output. If a
458 * superkey is included the keys of the subcolumns need not be explicitly
459 * mentioned in this vector. The order of subcolumns within a supercolumn
460 * is not changeable and remains in the order in which the columns are added
461 * to the supercolumn.
462 *
463 * This function may also be used to break big tables with too many columns
464 * into smaller ones. For example, you can call this function with the first
465 * five columns and then call one of the <tt>write_*</tt> functions, then
466 * call this function with the next five columns and again <tt>write_*</tt>,
467 * and so on.
468 */
469 void
470 set_column_order(const std::vector<std::string> &new_order);
471
472 /**
473 * Set the <tt>precision</tt> e.g. double or float variables are written
474 * with. <tt>precision</tt> is the same as in calling
475 * <tt>out<<setprecision(precision)</tt>.
476 */
477 void
478 set_precision(const std::string &key, const unsigned int precision);
479
480 /**
481 * Set the <tt>scientific_flag</tt>. True means scientific, false means
482 * fixed point notation.
483 */
484 void
485 set_scientific(const std::string &key, const bool scientific);
486
487 /**
488 * Set the caption of the column <tt>key</tt> for tex output. You may want
489 * to chose this different from <tt>key</tt>, if it contains formulas or
490 * similar constructs.
491 */
492 void
493 set_tex_caption(const std::string &key, const std::string &tex_caption);
494
495 /**
496 * Set the tex caption of the entire <tt>table</tt> for tex output.
497 */
498 void
499 set_tex_table_caption(const std::string &table_caption);
500
501 /**
502 * Set the label of this <tt>table</tt> for tex output.
503 */
504 void
505 set_tex_table_label(const std::string &table_label);
506
507 /**
508 * Set the caption the supercolumn <tt>superkey</tt> for tex output.
509 * You may want to chose this different from <tt>superkey</tt>, if it
510 * contains formulas or similar constructs.
511 */
512 void
513 set_tex_supercaption(const std::string &superkey,
514 const std::string &tex_supercaption);
515
516 /**
517 * Set the tex output format of a column, e.g. <tt>c</tt>, <tt>r</tt>,
518 * <tt>l</tt>, or <tt>p{3cm}</tt>. The default is <tt>c</tt>. Also if this
519 * function is not called for a column, the default is preset to be
520 * <tt>c</tt>.
521 */
522 void
523 set_tex_format(const std::string &key, const std::string &format = "c");
524
525 /**
526 * Write table as formatted text to the given stream. The text is formatted
527 * in such as way that it represents data as formatted columns of text. To
528 * avoid problems when reading these tables automatically, for example for
529 * postprocessing, if an entry in a cell of this table is empty (i.e. it has
530 * been created by calling the add_value() function with an empty string),
531 * then the entry of the table is printed as <code>""</code>.
532 *
533 * The second argument indicates how column keys are to be displayed. See
534 * the description of TextOutputFormat for more information.
535 */
536 void
537 write_text(std::ostream &out,
538 const TextOutputFormat format = table_with_headers) const;
539
540 /**
541 * Write table as a tex file. If @p with_header is set to false, then no
542 * <code>\\documentclass{...}</code>, <code>\\begin{document}</code> and
543 * <code>\\end{document}</code> are used. In this way the file can be
544 * included into an existing tex file using a command like
545 * <code>\\input{table_file}</code>.
546 */
547 void
548 write_tex(std::ostream &file, const bool with_header = true) const;
549
550 /**
551 * Clear the rows of the table, i.e. calls clear() on all the underlying
552 * storage data structures.
553 */
554 void
555 clear();
556
557 /**
558 * Remove all values added at the current row. This is useful when, for
559 * example, a time-step is rejected and all data recorded about it needs to
560 * be discarded.
561 */
562 void
563 clear_current_row();
564
565 /**
566 * Read or write the data of this object to or from a stream for the purpose
567 * of serialization using the [BOOST serialization
568 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
569 */
570 template <class Archive>
571 void
572 serialize(Archive &ar, const unsigned int version);
573
574 /**
575 * @addtogroup Exceptions
576 * @{
577 */
578
579 /**
580 * Exception
581 */
582 DeclException1(ExcColumnNotExistent,
583 std::string,
584 << "Column <" << arg1 << "> does not exist.");
585
586 /**
587 * Exception
588 */
589 DeclException1(ExcSuperColumnNotExistent,
590 std::string,
591 << "Supercolumn <" << arg1 << "> does not exist.");
592
593 /**
594 * Exception
595 */
596 DeclException1(ExcColumnOrSuperColumnNotExistent,
597 std::string,
598 << "Column or supercolumn <" << arg1 << "> does not exist.");
599
600 /**
601 * Exception
602 */
603 DeclException4(ExcWrongNumberOfDataEntries,
604 std::string,
605 int,
606 std::string,
607 int,
608 << "Column <" << arg1 << "> has " << arg2
609 << " rows, but Column <" << arg3 << "> has " << arg4
610 << " rows.");
611
612 /**
613 * Exception
614 */
615 DeclException1(ExcUndefinedTexFormat,
616 std::string,
617 << '<' << arg1 << "> is not a tex column format. Use "
618 << "'l', 'c', or 'r' to indicate left, centered, or "
619 << "right aligned text.");
620 /** @} */
621 protected:
622 /**
623 * Structure encapsulating all the data that is needed to describe one
624 * column of a table.
625 */
626 struct Column
627 {
628 /**
629 * Constructor needed by <tt>std::map</tt>.
630 */
631 Column();
632
633 /**
634 * Constructor.
635 */
636 explicit Column(const std::string &tex_caption);
637
638 /**
639 * Pad this column with default constructed elements to the number of rows
640 * given by the argument.
641 */
642 void
643 pad_column_below(const unsigned int length);
644
645 /**
646 * Write the data of this object to a stream for the purpose of
647 * serialization using the [BOOST serialization
648 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
649 */
650 template <class Archive>
651 void
652 save(Archive &ar, const unsigned int version) const;
653
654 /**
655 * Read the data of this object from a stream for the purpose of
656 * serialization using the [BOOST serialization
657 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
658 */
659 template <class Archive>
660 void
661 load(Archive &ar, const unsigned int version);
662
663 #ifdef DOXYGEN
664 /**
665 * Write and read the data of this object from a stream for the purpose
666 * of serialization using the [BOOST serialization
667 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
668 */
669 template <class Archive>
670 void
671 serialize(Archive &archive, const unsigned int version);
672 #else
673 // This macro defines the serialize() method that is compatible with
674 // the templated save() and load() method that have been implemented.
675 BOOST_SERIALIZATION_SPLIT_MEMBER()
676 #endif
677
678
679 /**
680 * Invalidates the string cache of all the entries and recomputes the
681 * maximum length max_length.
682 */
683 void
684 invalidate_cache();
685
686 /**
687 * List of entries within this column. Values are always immediately
688 * converted to strings to provide a uniform method of lookup.
689 */
690 std::vector<internal::TableEntry> entries;
691
692 /**
693 * The caption of the column in tex output. By default, this is the key
694 * string that is given to the <tt>TableHandler</tt> by
695 * <tt>TableHandler::add_value(...)</tt>. This may be changed by calling
696 * <tt>TableHandler::set_tex_caption(...)</tt>.
697 */
698 std::string tex_caption;
699
700 /**
701 * The column format in tex output. By default, this is <tt>"c"</tt>,
702 * meaning `centered'. This may be changed by calling
703 * <tt>TableHandler::set_tex_format(...)</tt> with <tt>"c", "r", "l"</tt>
704 * for centered, right or left.
705 */
706
707 std::string tex_format;
708
709 /**
710 * Double or float entries are written with this precision (set by the
711 * user). The default is 4.
712 */
713 unsigned int precision;
714
715 /**
716 * <tt>scientific</tt>=false means fixed point notation.
717 */
718 bool scientific;
719
720 /**
721 * Flag that may be used by derived classes for arbitrary purposes.
722 *
723 * In particular, the ConvergenceTable class uses the flag to denote
724 * columns for which convergence information has already been computed, or
725 * should not be computed at all.
726 */
727 unsigned int flag;
728
729 /**
730 * This entry caches the maximum length in characters for all entries in
731 * this table.
732 */
733 unsigned int max_length;
734 };
735
736 /**
737 * Help function that gives a vector of the keys of all columns that are
738 * mentioned in <tt>column_order</tt>, where each supercolumn key is
739 * replaced by its subcolumn keys.
740 *
741 * This function implicitly checks the consistency of the data. The result
742 * is returned in <tt>sel_columns</tt>.
743 */
744 void
745 get_selected_columns(std::vector<std::string> &sel_columns) const;
746
747 /**
748 * Builtin function, that gives the number of rows in the table and that
749 * checks if the number of rows is equal in every column. This function is
750 * e.g. called before writing output.
751 */
752 unsigned int
753 n_rows() const;
754
755 /**
756 * A variable storing the column and supercolumn keys in the order desired by
757 * the user. By default this is the order of adding the columns. This order
758 * may be changed by set_column_order().
759 */
760 std::vector<std::string> column_order;
761
762 /**
763 * A map from the column keys to the columns (not supercolumns).
764 *
765 * The field is declared mutable so that the write_text() and write_tex()
766 * functions can be const, even though they may pad columns below if
767 * 'auto_fill_mode' is on.
768 */
769 mutable std::map<std::string, Column> columns;
770
771 /**
772 * A map from each supercolumn key to the keys of its subcolumns in the right
773 * order. It is allowed that a supercolumn has got the same key as a
774 * column.
775 *
776 * Note that we do not use a <tt>multimap</tt> here since the order of
777 * column keys for each supercolumn key is relevant.
778 */
779 std::map<std::string, std::vector<std::string>> supercolumns;
780
781 /**
782 * A map from the supercolumn keys to the captions of the supercolumns that
783 * are used in tex output.
784 *
785 * By default these are just the supercolumn keys but they may be changed by
786 * <tt>set_tex_supercaptions(...)</tt>.
787 */
788 std::map<std::string, std::string> tex_supercaptions;
789
790 /**
791 * The caption of the table itself.
792 */
793 std::string tex_table_caption;
794 /**
795 * The label of the table.
796 */
797 std::string tex_table_label;
798
799 /**
800 * Flag indicating whether auto-fill mode should be used.
801 */
802 bool auto_fill_mode;
803 };
804
805
806 namespace internal
807 {
808 template <typename T>
809 TableEntry::TableEntry(const T &t)
810 : value(t)
811 {}
812
813
814 template <typename T>
815 T
816 TableEntry::get() const
817 {
818 // we don't quite know the data type in 'value', but
819 // it must be one of the ones in the type list of the
820 // std::variant. so if T is not in the list, or if
821 // the data stored in the TableEntry is not of type
822 // T, then we will get an exception that we can
823 // catch and produce an error message
824 try
825 {
826 return std::get<T>(value);
827 }
828 catch (...)
829 {
830 Assert(false,
831 ExcMessage(
832 "This TableEntry object does not store a datum of type T"));
833 throw;
834 }
835 }
836
837
838
839 template <class Archive>
840 void
841 TableEntry::save(Archive &ar, const unsigned int) const
842 {
843 // write first an identifier for the kind
844 // of data stored and then the actual
845 // data, in its correct data type
846 if (std::holds_alternative<int>(value))
847 {
848 const int p = std::get<int>(value);
849 char c = 'i';
850 ar &c &p;
851 }
852 else if (std::holds_alternative<unsigned int>(value))
853 {
854 const unsigned int p = std::get<unsigned int>(value);
855 char c = 'u';
856 ar &c &p;
857 }
858 else if (std::holds_alternative<double>(value))
859 {
860 const double p = std::get<double>(value);
861 char c = 'd';
862 ar &c &p;
863 }
864 else if (std::holds_alternative<std::string>(value))
865 {
866 const std::string p = std::get<std::string>(value);
867 char c = 's';
868 ar &c &p;
869 }
870 else if (std::holds_alternative<std::uint64_t>(value))
871 {
872 const std::uint64_t p = std::get<std::uint64_t>(value);
873 char c = 'l';
874 ar &c &p;
875 }
876 else
877 DEAL_II_ASSERT_UNREACHABLE();
878 }
879
880
881
882 template <class Archive>
883 void
884 TableEntry::load(Archive &ar, const unsigned int)
885 {
886 // following what we do in the save()
887 // function, first read in the data type
888 // as a one-character id, and then read
889 // the data
890 char c;
891 ar &c;
892
893 switch (c)
894 {
895 case 'i':
896 {
897 int val;
898 ar &val;
899 value = val;
900 break;
901 }
902
903 case 'u':
904 {
905 unsigned int val;
906 ar &val;
907 value = val;
908 break;
909 }
910
911 case 'd':
912 {
913 double val;
914 ar &val;
915 value = val;
916 break;
917 }
918
919 case 's':
920 {
921 std::string val;
922 ar &val;
923 value = val;
924 break;
925 }
926
927 case 'l':
928 {
929 std::uint64_t val;
930 ar &val;
931 value = val;
932 break;
933 }
934
935 default:
936 DEAL_II_ASSERT_UNREACHABLE();
937 }
938 }
939 } // namespace internal
940
941
942
943 template <typename T>
944 void
945 TableHandler::add_value(const std::string &key, const T value)
946 {
947 // see if the column already exists
948 if (columns.find(key) == columns.end())
949 declare_column(key);
950
951 if (auto_fill_mode == true)
952 {
953 // follow the algorithm given in the introduction to this class
954 // of padding columns as necessary
955 unsigned int max_col_length = 0;
956 for (const auto &column : columns)
957 max_col_length =
958 std::max(max_col_length,
959 static_cast<unsigned int>(column.second.entries.size()));
960
961 while (columns[key].entries.size() + 1 < max_col_length)
962 {
963 columns[key].entries.push_back(internal::TableEntry(T()));
964 const internal::TableEntry &entry = columns[key].entries.back();
965 entry.cache_string(columns[key].scientific, columns[key].precision);
966 columns[key].max_length =
967 std::max(columns[key].max_length,
968 static_cast<unsigned int>(
969 entry.get_cached_string().size()));
970 }
971 }
972
973 // now push the value given to this function
974 columns[key].entries.push_back(internal::TableEntry(value));
975 const internal::TableEntry &entry = columns[key].entries.back();
976 entry.cache_string(columns[key].scientific, columns[key].precision);
977 columns[key].max_length =
978 std::max(columns[key].max_length,
979 static_cast<unsigned int>(entry.get_cached_string().size()));
980 }
981
982
983
984 template <class Archive>
985 void
986 TableHandler::Column::save(Archive &ar, const unsigned int /*version*/) const
987 {
988 ar &entries &tex_caption &tex_format &precision &scientific &flag &max_length;
989 }
990
991
992
993 template <class Archive>
994 void
995 TableHandler::Column::load(Archive &ar, const unsigned int /*version*/)
996 {
997 ar &entries &tex_caption &tex_format &precision &scientific &flag &max_length;
998 invalidate_cache();
999 }
1000
1001
1002 template <class Archive>
1003 void
1004 TableHandler::serialize(Archive &ar, const unsigned int)
1005 {
1006 ar &column_order &columns &supercolumns &tex_supercaptions &tex_table_caption
1007 &tex_table_label &auto_fill_mode;
1008 }
1009
1010
1011 DEAL_II_NAMESPACE_CLOSE
1012
1013 #endif