table_handler.h

Go to the documentation of this file.

// ---------------------------------------------------------------------
//
// Copyright (C) 1999 - 2020 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE.md at
// the top level directory of deal.II.
//
// ---------------------------------------------------------------------

#ifndef dealii_table_handler_h
#define dealii_table_handler_h


#include <deal.II/base/config.h>

#include <deal.II/base/exceptions.h>

DEAL_II_DISABLE_EXTRA_DIAGNOSTICS
#include <boost/serialization/map.hpp>
#include <boost/serialization/split_member.hpp>
#include <boost/serialization/string.hpp>
#include <boost/serialization/vector.hpp>
#include <boost/variant.hpp>
DEAL_II_ENABLE_EXTRA_DIAGNOSTICS

#include <fstream>
#include <map>
#include <ostream>
#include <string>
#include <vector>


DEAL_II_NAMESPACE_OPEN

// Forward declaration
#ifndef DOXYGEN
class TableHandler;
#endif

namespace internal
{
  struct TableEntry
  {
  public:
    TableEntry() = default;

    template <typename T>
    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 =
      boost::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();

    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
    // boost::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 boost::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 (const int *p = boost::get<int>(&value))
      {
        char c = 'i';
        ar &c &*p;
      }
    else if (const unsigned int *p = boost::get<unsigned int>(&value))
      {
        char c = 'u';
        ar &c &*p;
      }
    else if (const double *p = boost::get<double>(&value))
      {
        char c = 'd';
        ar &c &*p;
      }
    else if (const std::string *p = boost::get<std::string>(&value))
      {
        char c = 's';
        ar &c &*p;
      }
    else if (const std::uint64_t *p = boost::get<std::uint64_t>(&value))
      {
        char c = 'l';
        ar &c &*p;
      }
    else
      Assert(false, ExcInternalError());
  }



  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:
          Assert(false, ExcInternalError());
      }
  }
} // 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.push_back(internal::TableEntry(T()));
          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().length()));
        }
    }

  // now push the value given to this function
  columns[key].entries.push_back(internal::TableEntry(value));
  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().length()));
}



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