table_handler.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
// Copyright (C) 1999 - 2025 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Detailed license information governing the source code and contributions
// can be found in LICENSE.md and CONTRIBUTING.md at the top level directory.
//
// -----------------------------------------------------------------------------
 
#ifndef dealii_table_handler_h
#define dealii_table_handler_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/exceptions.h>
 
#include <boost/serialization/map.hpp>
#include <boost/serialization/split_member.hpp>
#include <boost/serialization/string.hpp>
#include <boost/serialization/vector.hpp>
 
#include <cstdint>
#include <map>
#include <ostream>
#include <string>
#include <variant>
#include <vector>
 
 
DEAL_II_NAMESPACE_OPEN
 
// Forward declaration
#ifndef DOXYGEN
class TableHandler;
#endif
 
namespace internal
{
  struct TableEntry
  {
  public:
    TableEntry() = default;
 
    template <typename T>
    explicit TableEntry(const T &t);
 
    template <typename T>
    T
    get() const;
 
    double
    get_numeric_value() const;
 
    void
    cache_string(bool scientific, unsigned int precision) const;
 
    const std::string &
    get_cached_string() const;
 
 
    TableEntry
    get_default_constructed_copy() const;
 
    template <class Archive>
    void
    save(Archive &ar, const unsigned int version) const;
 
    template <class Archive>
    void
    load(Archive &ar, const unsigned int version);
 
#ifdef DOXYGEN
    template <class Archive>
    void
    serialize(Archive &archive, const unsigned int version);
#else
    // This macro defines the serialize() method that is compatible with
    // the templated save() and load() method that have been implemented.
    BOOST_SERIALIZATION_SPLIT_MEMBER()
#endif
 
  private:
    using value_type =
      std::variant<int, unsigned int, std::uint64_t, double, std::string>;
 
    value_type value;
 
    mutable std::string cached_value;
 
    friend class ::TableHandler;
  };
} // namespace internal
 
 
class TableHandler
{
public:
  enum TextOutputFormat
  {
    table_with_headers,
    table_with_separate_column_description,
    simple_table_with_separate_column_description,
    org_mode_table
  };
 
  TableHandler();
 
 
  void
  declare_column(const std::string &key);
 
  template <typename T>
  void
  add_value(const std::string &key, const T value);
 
  void
  start_new_row();
 
  void
  set_auto_fill_mode(const bool state);
 
  void
  add_column_to_supercolumn(const std::string &key,
                            const std::string &superkey);
 
  void
  set_column_order(const std::vector<std::string> &new_order);
 
  void
  set_precision(const std::string &key, const unsigned int precision);
 
  void
  set_scientific(const std::string &key, const bool scientific);
 
  void
  set_tex_caption(const std::string &key, const std::string &tex_caption);
 
  void
  set_tex_table_caption(const std::string &table_caption);
 
  void
  set_tex_table_label(const std::string &table_label);
 
  void
  set_tex_supercaption(const std::string &superkey,
                       const std::string &tex_supercaption);
 
  void
  set_tex_format(const std::string &key, const std::string &format = "c");
 
  void
  write_text(std::ostream          &out,
             const TextOutputFormat format = table_with_headers) const;
 
  void
  write_tex(std::ostream &file, const bool with_header = true) const;
 
  void
  clear();
 
  void
  clear_current_row();
 
  template <class Archive>
  void
  serialize(Archive &ar, const unsigned int version);
 
  DeclException1(ExcColumnNotExistent,
                 std::string,
                 << "Column <" << arg1 << "> does not exist.");
 
  DeclException1(ExcSuperColumnNotExistent,
                 std::string,
                 << "Supercolumn <" << arg1 << "> does not exist.");
 
  DeclException1(ExcColumnOrSuperColumnNotExistent,
                 std::string,
                 << "Column or supercolumn <" << arg1 << "> does not exist.");
 
  DeclException4(ExcWrongNumberOfDataEntries,
                 std::string,
                 int,
                 std::string,
                 int,
                 << "Column <" << arg1 << "> has " << arg2
                 << " rows, but Column <" << arg3 << "> has " << arg4
                 << " rows.");
 
  DeclException1(ExcUndefinedTexFormat,
                 std::string,
                 << '<' << arg1 << "> is not a tex column format. Use "
                 << "'l', 'c', or 'r' to indicate left, centered, or "
                 << "right aligned text.");
protected:
  struct Column
  {
    Column();
 
    explicit Column(const std::string &tex_caption);
 
    void
    pad_column_below(const unsigned int length);
 
    template <class Archive>
    void
    save(Archive &ar, const unsigned int version) const;
 
    template <class Archive>
    void
    load(Archive &ar, const unsigned int version);
 
#ifdef DOXYGEN
    template <class Archive>
    void
    serialize(Archive &archive, const unsigned int version);
#else
    // This macro defines the serialize() method that is compatible with
    // the templated save() and load() method that have been implemented.
    BOOST_SERIALIZATION_SPLIT_MEMBER()
#endif
 
 
    void
    invalidate_cache();
 
    std::vector<internal::TableEntry> entries;
 
    std::string tex_caption;
 
    std::string tex_format;
 
    unsigned int precision;
 
    bool scientific;
 
    unsigned int flag;
 
    unsigned int max_length;
  };
 
  void
  get_selected_columns(std::vector<std::string> &sel_columns) const;
 
  unsigned int
  n_rows() const;
 
  std::vector<std::string> column_order;
 
  mutable std::map<std::string, Column> columns;
 
  std::map<std::string, std::vector<std::string>> supercolumns;
 
  std::map<std::string, std::string> tex_supercaptions;
 
  std::string tex_table_caption;
  std::string tex_table_label;
 
  bool auto_fill_mode;
};
 
 
namespace internal
{
  template <typename T>
  TableEntry::TableEntry(const T &t)
    : value(t)
  {}
 
 
  template <typename T>
  T
  TableEntry::get() const
  {
    // we don't quite know the data type in 'value', but
    // it must be one of the ones in the type list of the
    // std::variant. so if T is not in the list, or if
    // the data stored in the TableEntry is not of type
    // T, then we will get an exception that we can
    // catch and produce an error message
    try
      {
        return std::get<T>(value);
      }
    catch (...)
      {
        Assert(false,
               ExcMessage(
                 "This TableEntry object does not store a datum of type T"));
        throw;
      }
  }
 
 
 
  template <class Archive>
  void
  TableEntry::save(Archive &ar, const unsigned int) const
  {
    // write first an identifier for the kind
    // of data stored and then the actual
    // data, in its correct data type
    if (std::holds_alternative<int>(value))
      {
        const int p = std::get<int>(value);
        char      c = 'i';
        ar &c    &p;
      }
    else if (std::holds_alternative<unsigned int>(value))
      {
        const unsigned int p = std::get<unsigned int>(value);
        char               c = 'u';
        ar &c             &p;
      }
    else if (std::holds_alternative<double>(value))
      {
        const double p = std::get<double>(value);
        char         c = 'd';
        ar &c       &p;
      }
    else if (std::holds_alternative<std::string>(value))
      {
        const std::string p = std::get<std::string>(value);
        char              c = 's';
        ar &c            &p;
      }
    else if (std::holds_alternative<std::uint64_t>(value))
      {
        const std::uint64_t p = std::get<std::uint64_t>(value);
        char                c = 'l';
        ar &c              &p;
      }
    else
      DEAL_II_ASSERT_UNREACHABLE();
  }
 
 
 
  template <class Archive>
  void
  TableEntry::load(Archive &ar, const unsigned int)
  {
    // following what we do in the save()
    // function, first read in the data type
    // as a one-character id, and then read
    // the data
    char c;
    ar  &c;
 
    switch (c)
      {
        case 'i':
          {
            int val;
            ar &val;
            value = val;
            break;
          }
 
        case 'u':
          {
            unsigned int val;
            ar          &val;
            value = val;
            break;
          }
 
        case 'd':
          {
            double val;
            ar    &val;
            value = val;
            break;
          }
 
        case 's':
          {
            std::string val;
            ar         &val;
            value = val;
            break;
          }
 
        case 'l':
          {
            std::uint64_t val;
            ar           &val;
            value = val;
            break;
          }
 
        default:
          DEAL_II_ASSERT_UNREACHABLE();
      }
  }
} // namespace internal
 
 
 
template <typename T>
void
TableHandler::add_value(const std::string &key, const T value)
{
  // see if the column already exists
  if (columns.find(key) == columns.end())
    declare_column(key);
 
  if (auto_fill_mode == true)
    {
      // follow the algorithm given in the introduction to this class
      // of padding columns as necessary
      unsigned int max_col_length = 0;
      for (const auto &column : columns)
        max_col_length =
          std::max(max_col_length,
                   static_cast<unsigned int>(column.second.entries.size()));
 
      while (columns[key].entries.size() + 1 < max_col_length)
        {
          columns[key].entries.emplace_back(T());
          const internal::TableEntry &entry = columns[key].entries.back();
          entry.cache_string(columns[key].scientific, columns[key].precision);
          columns[key].max_length =
            std::max(columns[key].max_length,
                     static_cast<unsigned int>(
                       entry.get_cached_string().size()));
        }
    }
 
  // now push the value given to this function
  columns[key].entries.emplace_back(value);
  const internal::TableEntry &entry = columns[key].entries.back();
  entry.cache_string(columns[key].scientific, columns[key].precision);
  columns[key].max_length =
    std::max(columns[key].max_length,
             static_cast<unsigned int>(entry.get_cached_string().size()));
}
 
 
 
template <class Archive>
void
TableHandler::Column::save(Archive &ar, const unsigned int /*version*/) const
{
  ar &entries &tex_caption &tex_format &precision &scientific &flag &max_length;
}
 
 
 
template <class Archive>
void
TableHandler::Column::load(Archive &ar, const unsigned int /*version*/)
{
  ar &entries &tex_caption &tex_format &precision &scientific &flag &max_length;
  invalidate_cache();
}
 
 
template <class Archive>
void
TableHandler::serialize(Archive &ar, const unsigned int)
{
  ar &column_order &columns &supercolumns &tex_supercaptions &tex_table_caption
    &tex_table_label &auto_fill_mode;
}
 
 
DEAL_II_NAMESPACE_CLOSE
 
#endif