From 50e68cf423f15c455f11864d9b1d9a7039244dff Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Tue, 11 Apr 2017 15:51:58 -0600
Subject: [PATCH] Add TableHandler::declare_column().

---
 include/deal.II/base/table_handler.h | 30 +++++++++++++++++++++++-----
 source/base/table_handler.cc         | 13 ++++++++++++
 2 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/include/deal.II/base/table_handler.h b/include/deal.II/base/table_handler.h
index 807fda071b..c1ae220f4e 100644
--- a/include/deal.II/base/table_handler.h
+++ b/include/deal.II/base/table_handler.h
@@ -346,6 +346,30 @@ public:
    */
   TableHandler ();
 
+
+  /**
+   * Declare the existence of a column in the table by giving it a name.
+   * As discussed in the documentation of the class, this is not usually
+   * necessary -- just adding a value for a given column key via the
+   * add_value() function also declares the column. This function is
+   * therefore only necessary in cases where you want a column to
+   * also show up even if you never add an entry to any row in this column;
+   * or, more likely, if you want to prescribe the order in which columns
+   * are later printed by declaring columns in a particular order before
+   * entries are ever put into them.
+   *
+   * (The latter objective can also be achieved by adding entries to
+   * the table in whatever order they are produced by a program,
+   * and later calling set_column_order(). However, this approach
+   * requires knowing -- in one central place of your software --
+   * all of the columns keys that other parts of the software have
+   * written into, and how they should be sorted. This is easily
+   * possible for small programs, but may not be feasible for
+   * large code bases in which parts of the code base are only
+   * executed based on run-time parameters.)
+   */
+  void declare_column (const std::string &key);
+
   /**
    * Adds a column (if not yet existent) with the key <tt>key</tt> and adds
    * the value of type <tt>T</tt> to the column. Values of type <tt>T</tt>
@@ -841,11 +865,7 @@ void TableHandler::add_value (const std::string &key,
 {
   // see if the column already exists
   if (columns.find(key) == columns.end())
-    {
-      std::pair<std::string, Column> new_column(key, Column(key));
-      columns.insert(new_column);
-      column_order.push_back(key);
-    }
+    declare_column (key);
 
   if (auto_fill_mode == true)
     {
diff --git a/source/base/table_handler.cc b/source/base/table_handler.cc
index 5dc3b0708f..c2dbfc5c8f 100644
--- a/source/base/table_handler.cc
+++ b/source/base/table_handler.cc
@@ -189,6 +189,19 @@ TableHandler::TableHandler()
 
 
 
+void TableHandler::declare_column (const std::string &key)
+{
+  // see if the column already exists; insert it if not
+  Assert (columns.find(key) == columns.end(),
+          ExcMessage ("You are trying to declare a column with key <" + key +
+                      "> but such a column already exists."));
+
+  columns.insert(std::make_pair(key, Column(key)));
+  column_order.push_back(key);
+}
+
+
+
 void TableHandler::start_new_row ()
 {
   // figure out the longest current column
-- 
2.39.5