src/gromacs/topology/symtab.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
   5  * Copyright (c) 2001-2004, The GROMACS development team.
   6  * Copyright (c) 2010,2014,2017,2018,2019,2020, by the GROMACS development team, led by
   7  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   8  * and including many others, as listed in the AUTHORS file in the
   9  * top-level source directory and at http://www.gromacs.org.
  10  *
  11  * GROMACS is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Lesser General Public License
  13  * as published by the Free Software Foundation; either version 2.1
  14  * of the License, or (at your option) any later version.
  15  *
  16  * GROMACS is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public
  22  * License along with GROMACS; if not, see
  23  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  24  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  25  *
  26  * If you want to redistribute modifications to GROMACS, please
  27  * consider that scientific software is very special. Version
  28  * control is crucial - bugs must be traceable. We will be happy to
  29  * consider code for inclusion in the official distribution, but
  30  * derived work must not be called official GROMACS. Details are found
  31  * in the README & COPYING files - if they are missing, get the
  32  * official version at http://www.gromacs.org.
  33  *
  34  * To help us fund GROMACS development, we humbly ask that you cite
  35  * the research papers on the package. Check out http://www.gromacs.org.
  36  */
  37 /*! \file
  38  * \brief
  39  * Declares modern and legacy symbol table used to store strings of characters.
  40  *
  41  * \author David van der Spoel <david.vanderspoel@icm.uu.se>
  42  * \author Paul Bauer <paul.bauer.q@gmail.com>
  43  *
  44  * \ingroup module_topology
  45  * \inlibraryapi
  46  */
  47 #ifndef GMX_TOPOLOGY_SYMTAB_H
  48 #define GMX_TOPOLOGY_SYMTAB_H
  49
  50 #include <stdio.h>
  51
  52 #include <functional>
  53 #include <string>
  54 #include <unordered_map>
  55 #include <vector>
  56
  57 #include "gromacs/utility/gmxassert.h"
  58
  59 struct t_commrec;
  60 struct t_fileio;
  61
  62 namespace gmx
  63 {
  64 class ISerializer;
  65 namespace test
  66 {
  67 class StringTableTest;
  68 } // namespace test
  69 } // namespace gmx
  70
  71 //! Convenience typedef for pair stored in map.
  72 using StringTablePair = std::pair<std::string, int>;
  73 //! Convenience typedef for string reference wrapper.
  74 using StringReference = std::reference_wrapper<const std::string>;
  75
  76 class StringTableBuilder;
  77 class StringTableEntry;
  78 /*! \brief
  79  * A class to store strings for lookup.
  80  *
  81  * We store the strings in a dedicated object to avoid
  82  * wrong usage of the flat string vector, and forcing people
  83  * to use an object that can only be constructed from the transitional
  84  * StringTableBuilder or filled during file IO.
  85  *
  86  * Note that strings are stripped of trailing and leading whitespace.
  87  */
  88 class StringTable
  89 {
  90 public:
  91     //! Constructor used to generate table object from file reading.
  92     StringTable(gmx::ISerializer* serializer);
  93     //! Can move construct.
  94     StringTable(StringTable&&) = default;
  95     //! Can move assign.
  96     StringTable& operator=(StringTable&&) = default;
  97     //! No copy constructor.
  98     StringTable(const StringTable&) = delete;
  99     //! No copy assign.
 100     StringTable& operator=(const StringTable&) = delete;
 101     /*! \brief
 102      *  Access string at \p index.
 103      *
 104      *  \returns Entry type that constains both the string and the index,
 105      *           with the index needed during (de-)serialization.
 106      *  \throws  On index being out of range.
 107      */
 108     StringTableEntry at(gmx::index index) const;
 109     //! Bracket operator.
 110     StringTableEntry operator[](gmx::index index) const;
 111     //! Handle file IO.
 112     void serializeStringTable(gmx::ISerializer* serializer);
 113
 114     //! Print human readable format of storage.
 115     void printStringTableStorageToFile(FILE* fp, int indent, const char* title) const;
 116
 117     /*! \brief
 118      * Copy data in new datastructure to legacy version.
 119      *
 120      * The legacy datastructures need to be already initialized.
 121      *
 122      * \param[in] symtab Legacy symbol table to add entries to.
 123      */
 124     void copyToLegacySymtab(struct t_symtab* symtab) const;
 125
 126     friend class StringTableBuilder;
 127
 128 private:
 129     /*! \brief
 130      * Private constructor so that only builder can create the final table.
 131      *
 132      * \param[in] table A vector of strings to be stored in the table.
 133      */
 134     StringTable(const std::vector<std::string>& table) : table_(table) {}
 135
 136     //! The table is stored as a vector of strings.
 137     std::vector<std::string> table_;
 138 };
 139
 140 /*! \brief
 141  * Helper class to access members in StringTable.
 142  *
 143  * This class is a wrapper around a string reference to access
 144  * the actual entry in the table, as well as an index used for
 145  * serializing the datastructure.
 146  *
 147  * This also provides efficient comparison calls between different entries.
 148  */
 149 class StringTableEntry
 150 {
 151 public:
 152     //! Copy construct.
 153     StringTableEntry(const StringTableEntry&) = default;
 154     //! Move construct.
 155     StringTableEntry(StringTableEntry&&) noexcept = default;
 156     //! Copy assign.
 157     StringTableEntry& operator=(const StringTableEntry&) = default;
 158     //! Move assign.
 159     StringTableEntry& operator=(StringTableEntry&&) = default;
 160
 161     //! Compare entries by indices. Same string should always have same index.
 162     bool operator==(const StringTableEntry& o) const { return tableIndex_ == o.tableIndex_; }
 163     //! Unequal comparisson.
 164     bool operator!=(const StringTableEntry& o) const { return !(*this == o); }
 165     //! Access to underlying view.
 166     const std::string& operator*() const { return entry_; }
 167     //! Access to underlying view.
 168     const std::string* operator->() const { return &entry_.get(); }
 169     //! Serialize index.
 170     void serialize(gmx::ISerializer* serializer) const;
 171
 172     // We only allow construction from the places that are known to create
 173     // valid objects for us.
 174     friend StringTableEntry readStringTableEntry(gmx::ISerializer* serializer, const StringTable& table);
 175     friend class StringTableBuilder;
 176     friend class StringTable;
 177
 178 private:
 179     //! Only allow construct with all information present.
 180     StringTableEntry(StringReference entry, int tableIndex) : entry_(entry), tableIndex_(tableIndex)
 181     {
 182     }
 183     //! The actual string reference that is stored.
 184     StringReference entry_;
 185     //! The index into the table.
 186     int tableIndex_ = -1;
 187 };
 188
 189 /*! \brief
 190  * De-serialize StringTableEntry using the index into the \p table.
 191  *
 192  * \param[in] serializer  The object containing the serialized index.
 193  * \param[in] table       The storage object holding all strings.
 194  * \returns The entry into the Table as StringTableEntry.
 195  */
 196 StringTableEntry readStringTableEntry(gmx::ISerializer* serializer, const StringTable& table);
 197
 198 /*! \libinternal \brief
 199  * Builds a memory efficient storage for strings of characters.
 200  *
 201  * Allows storing strings of characters with unique entries.
 202  */
 203 class StringTableBuilder
 204 {
 205 public:
 206     /*! \brief
 207      * Place new unique string in storage object.
 208      *
 209      * Enters new string into the underlying storage or recovers existing entry.
 210      * \param[in] theString New string to enter.
 211      * \returns New entry object with reference to string and index into storage.
 212      *          The reference is only valid while the builder is in use, and becomes
 213      *          invalidated when generating the StringTable.
 214      */
 215     StringTableEntry addString(const std::string& theString);
 216     //! Find matching entry in storage by name as string.
 217     int findEntryByName(const std::string& name) const;
 218     /*! \brief
 219      * Build the StringTable from the internal map of strings.
 220      *
 221      * The unique indices returned from addString() can be used
 222      * to index into the returned StringTable. Clears the
 223      * temporary storage so that the StringTableBuilder can be re-used to
 224      * build a distinct StringTable.
 225      */
 226     StringTable build();
 227
 228 private:
 229     //! Storage object for entries.
 230     std::unordered_map<std::string, int> map_;
 231 };
 232
 233 // Below this is the legacy code for the old symbol table, only used in
 234 // deprecated datastructures.
 235 /*! \libinternal \brief
 236  * Legacy symbol table entry as linked list.
 237  */
 238 struct t_symbuf
 239 {
 240     //! Number of entries in this item
 241     int bufsize;
 242     //! Storage for strings in this item.
 243     char** buf;
 244     //! Next item in linked list.
 245     struct t_symbuf* next;
 246 };
 247
 248 /* \libinternal \brief
 249  * Legacy symbol table.
 250  */
 251 struct t_symtab
 252 {
 253     //! Total number of entries stored.
 254     int nr;
 255     //! First item in linked list of storage elements.
 256     t_symbuf* symbuf;
 257 };
 258
 259 /*
 260  * This module handles symbol table manipulation. All text strings
 261  * needed by an application are allocated only once. All references
 262  * to these text strings use handles returned from the put_symtab()
 263  * routine. These handles can easily be converted to address independent
 264  * values by invoking lookup_symtab(). So when writing structures to
 265  * a file which contains text strings, this value can be written in stead
 266  * of the text string or its address. This value can easily be converted
 267  * back to a text string handle by get_symtab_handle().
 268  */
 269
 270 //! Initialises the symbol table symtab.
 271 void open_symtab(t_symtab* symtab);
 272
 273 /*! \brief
 274  * Undoes the effect of open_symtab()
 275  *
 276  * After invoking this function, no value can be added to the
 277  * symbol table, only values can be retrieved using get_symtab_handle().
 278  *
 279  * Note that this does no work.
 280  * \param[inout] symtab Symbol table to close.
 281  */
 282 void close_symtab(t_symtab* symtab);
 283
 284 /*! \brief Returns a deep copy of \c symtab. */
 285 t_symtab* duplicateSymtab(const t_symtab* symtab);
 286
 287 //! Frees the space allocated by the symbol table itself.
 288 void free_symtab(t_symtab* symtab);
 289
 290 //! Frees the space allocated by the symbol table, including all entries in it.
 291 void done_symtab(t_symtab* symtab);
 292
 293 /*! \brief
 294  * Enters a string into the symbol table.
 295  *
 296  * If the string \p name was not present before, a reference to a copy is returned,
 297  * else a reference to the earlier entered value is returned. Strings are trimmed of spaces.
 298  *
 299  * \param[inout] symtab Symbol table to add string to.
 300  * \param[in] name String to add.
 301  * \returns Pointer to entry of string in symtab.
 302  */
 303 char** put_symtab(t_symtab* symtab, const char* name);
 304
 305 /*! \brief
 306  * Returns unique handle for \p name.
 307  *
 308  * Looks up the string pointer \p name in the symbol table and returns the
 309  * index in it to the matching entry. Gives fatal error if \p name is
 310  * not found. \p name has to be entered first using put_symtab().
 311  *
 312  * \param[in] symtab Symbol table to search.
 313  * \param[in] name String pointer into \p symtab.
 314  * \returns Unique index to position in symbol table.
 315  */
 316 int lookup_symtab(t_symtab* symtab, char** name);
 317
 318 /*! \brief
 319  * Returns text string corresponding to \p index.
 320  *
 321  * \p index needs to be value obtained from call to lookup_symtab().
 322  * get_symtab_handle() and lookup_symtab() are inverse functions.
 323  *
 324  * \param[in] symtab Symbol table to search.
 325  * \param[in] index  Entry to find in table.
 326  * \returns String pointer into \p symtab corresponding to the entry.
 327  */
 328 char** get_symtab_handle(t_symtab* symtab, int index);
 329
 330 /*! \brief
 331  * Prints human readable form of \p symtab.
 332  *
 333  * \param[in] fp File to print to.
 334  * \param[in] indent Number of spaces to use for indentation.
 335  * \param[in] title Name for header text.
 336  * \param[in] symtab Symbol table to print out.
 337  */
 338 void pr_symtab(FILE* fp, int indent, const char* title, t_symtab* symtab);
 339
 340 #endif