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,2021, 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/basedefinitions.h"
  58 #include "gromacs/utility/gmxassert.h"
  59
  60 struct t_commrec;
  61 struct t_fileio;
  62
  63 namespace gmx
  64 {
  65 class ISerializer;
  66 namespace test
  67 {
  68 class StringTableTest;
  69 } // namespace test
  70 } // namespace gmx
  71
  72 //! Convenience typedef for pair stored in map.
  73 using StringTablePair = std::pair<std::string, int>;
  74 //! Convenience typedef for string reference wrapper.
  75 using StringReference = std::reference_wrapper<const std::string>;
  76
  77 class StringTableBuilder;
  78 class StringTableEntry;
  79 /*! \brief
  80  * A class to store strings for lookup.
  81  *
  82  * We store the strings in a dedicated object to avoid
  83  * wrong usage of the flat string vector, and forcing people
  84  * to use an object that can only be constructed from the transitional
  85  * StringTableBuilder or filled during file IO.
  86  *
  87  * Note that strings are stripped of trailing and leading whitespace.
  88  */
  89 class StringTable
  90 {
  91 public:
  92     //! Constructor used to generate table object from file reading.
  93     StringTable(gmx::ISerializer* serializer);
  94     //! Can move construct.
  95     StringTable(StringTable&&) = default;
  96     //! Can move assign.
  97     StringTable& operator=(StringTable&&) = default;
  98     //! No copy constructor.
  99     StringTable(const StringTable&) = delete;
 100     //! No copy assign.
 101     StringTable& operator=(const StringTable&) = delete;
 102     /*! \brief
 103      *  Access string at \p index.
 104      *
 105      *  \returns Entry type that constains both the string and the index,
 106      *           with the index needed during (de-)serialization.
 107      *  \throws  On index being out of range.
 108      */
 109     StringTableEntry at(gmx::index index) const;
 110     //! Bracket operator.
 111     StringTableEntry operator[](gmx::index index) const;
 112     //! Handle file IO.
 113     void serializeStringTable(gmx::ISerializer* serializer);
 114
 115     //! Print human readable format of storage.
 116     void printStringTableStorageToFile(FILE* fp, int indent, const char* title) const;
 117
 118     /*! \brief
 119      * Copy data in new datastructure to legacy version.
 120      *
 121      * The legacy datastructures need to be already initialized.
 122      *
 123      * \param[in] symtab Legacy symbol table to add entries to.
 124      */
 125     void copyToLegacySymtab(struct t_symtab* symtab) const;
 126
 127     friend class StringTableBuilder;
 128
 129 private:
 130     /*! \brief
 131      * Private constructor so that only builder can create the final table.
 132      *
 133      * \param[in] table A vector of strings to be stored in the table.
 134      */
 135     StringTable(const std::vector<std::string>& table) : table_(table) {}
 136
 137     //! The table is stored as a vector of strings.
 138     std::vector<std::string> table_;
 139 };
 140
 141 /*! \brief
 142  * Helper class to access members in StringTable.
 143  *
 144  * This class is a wrapper around a string reference to access
 145  * the actual entry in the table, as well as an index used for
 146  * serializing the datastructure.
 147  *
 148  * This also provides efficient comparison calls between different entries.
 149  */
 150 class StringTableEntry
 151 {
 152 public:
 153     //! Copy construct.
 154     StringTableEntry(const StringTableEntry&) = default;
 155     //! Move construct.
 156     StringTableEntry(StringTableEntry&&) noexcept = default;
 157     //! Copy assign.
 158     StringTableEntry& operator=(const StringTableEntry&) = default;
 159     //! Move assign.
 160     StringTableEntry& operator=(StringTableEntry&&) = default;
 161
 162     //! Compare entries by indices. Same string should always have same index.
 163     bool operator==(const StringTableEntry& o) const { return tableIndex_ == o.tableIndex_; }
 164     //! Unequal comparisson.
 165     bool operator!=(const StringTableEntry& o) const { return !(*this == o); }
 166     //! Access to underlying view.
 167     const std::string& operator*() const { return entry_; }
 168     //! Access to underlying view.
 169     const std::string* operator->() const { return &entry_.get(); }
 170     //! Serialize index.
 171     void serialize(gmx::ISerializer* serializer) const;
 172
 173     // We only allow construction from the places that are known to create
 174     // valid objects for us.
 175     friend StringTableEntry readStringTableEntry(gmx::ISerializer* serializer, const StringTable& table);
 176     friend class StringTableBuilder;
 177     friend class StringTable;
 178
 179 private:
 180     //! Only allow construct with all information present.
 181     StringTableEntry(StringReference entry, int tableIndex) : entry_(entry), tableIndex_(tableIndex)
 182     {
 183     }
 184     //! The actual string reference that is stored.
 185     StringReference entry_;
 186     //! The index into the table.
 187     int tableIndex_ = -1;
 188 };
 189
 190 /*! \brief
 191  * De-serialize StringTableEntry using the index into the \p table.
 192  *
 193  * \param[in] serializer  The object containing the serialized index.
 194  * \param[in] table       The storage object holding all strings.
 195  * \returns The entry into the Table as StringTableEntry.
 196  */
 197 StringTableEntry readStringTableEntry(gmx::ISerializer* serializer, const StringTable& table);
 198
 199 /*! \libinternal \brief
 200  * Builds a memory efficient storage for strings of characters.
 201  *
 202  * Allows storing strings of characters with unique entries.
 203  */
 204 class StringTableBuilder
 205 {
 206 public:
 207     /*! \brief
 208      * Place new unique string in storage object.
 209      *
 210      * Enters new string into the underlying storage or recovers existing entry.
 211      * \param[in] theString New string to enter.
 212      * \returns New entry object with reference to string and index into storage.
 213      *          The reference is only valid while the builder is in use, and becomes
 214      *          invalidated when generating the StringTable.
 215      */
 216     StringTableEntry addString(const std::string& theString);
 217     //! Find matching entry in storage by name as string.
 218     int findEntryByName(const std::string& name) const;
 219     /*! \brief
 220      * Build the StringTable from the internal map of strings.
 221      *
 222      * The unique indices returned from addString() can be used
 223      * to index into the returned StringTable. Clears the
 224      * temporary storage so that the StringTableBuilder can be re-used to
 225      * build a distinct StringTable.
 226      */
 227     StringTable build();
 228
 229 private:
 230     //! Storage object for entries.
 231     std::unordered_map<std::string, int> map_;
 232 };
 233
 234 // Below this is the legacy code for the old symbol table, only used in
 235 // deprecated datastructures.
 236 /*! \libinternal \brief
 237  * Legacy symbol table entry as linked list.
 238  */
 239 struct t_symbuf
 240 {
 241     //! Number of entries in this item
 242     int bufsize;
 243     //! Storage for strings in this item.
 244     char** buf;
 245     //! Next item in linked list.
 246     struct t_symbuf* next;
 247 };
 248
 249 /* \libinternal \brief
 250  * Legacy symbol table.
 251  */
 252 struct t_symtab
 253 {
 254     //! Total number of entries stored.
 255     int nr;
 256     //! First item in linked list of storage elements.
 257     t_symbuf* symbuf;
 258 };
 259
 260 /*
 261  * This module handles symbol table manipulation. All text strings
 262  * needed by an application are allocated only once. All references
 263  * to these text strings use handles returned from the put_symtab()
 264  * routine. These handles can easily be converted to address independent
 265  * values by invoking lookup_symtab(). So when writing structures to
 266  * a file which contains text strings, this value can be written in stead
 267  * of the text string or its address. This value can easily be converted
 268  * back to a text string handle by get_symtab_handle().
 269  */
 270
 271 //! Initialises the symbol table symtab.
 272 void open_symtab(t_symtab* symtab);
 273
 274 /*! \brief
 275  * Undoes the effect of open_symtab()
 276  *
 277  * After invoking this function, no value can be added to the
 278  * symbol table, only values can be retrieved using get_symtab_handle().
 279  *
 280  * Note that this does no work.
 281  * \param[inout] symtab Symbol table to close.
 282  */
 283 void close_symtab(t_symtab* symtab);
 284
 285 /*! \brief Returns a deep copy of \c symtab. */
 286 t_symtab* duplicateSymtab(const t_symtab* symtab);
 287
 288 //! Frees the space allocated by the symbol table itself.
 289 void free_symtab(t_symtab* symtab);
 290
 291 //! Frees the space allocated by the symbol table, including all entries in it.
 292 void done_symtab(t_symtab* symtab);
 293
 294 /*! \brief
 295  * Enters a string into the symbol table.
 296  *
 297  * If the string \p name was not present before, a reference to a copy is returned,
 298  * else a reference to the earlier entered value is returned. Strings are trimmed of spaces.
 299  *
 300  * \param[inout] symtab Symbol table to add string to.
 301  * \param[in] name String to add.
 302  * \returns Pointer to entry of string in symtab.
 303  */
 304 char** put_symtab(t_symtab* symtab, const char* name);
 305
 306 /*! \brief
 307  * Returns unique handle for \p name.
 308  *
 309  * Looks up the string pointer \p name in the symbol table and returns the
 310  * index in it to the matching entry. Gives fatal error if \p name is
 311  * not found. \p name has to be entered first using put_symtab().
 312  *
 313  * \param[in] symtab Symbol table to search.
 314  * \param[in] name String pointer into \p symtab.
 315  * \returns Unique index to position in symbol table.
 316  */
 317 int lookup_symtab(t_symtab* symtab, char** name);
 318
 319 /*! \brief
 320  * Returns text string corresponding to \p index.
 321  *
 322  * \p index needs to be value obtained from call to lookup_symtab().
 323  * get_symtab_handle() and lookup_symtab() are inverse functions.
 324  *
 325  * \param[in] symtab Symbol table to search.
 326  * \param[in] index  Entry to find in table.
 327  * \returns String pointer into \p symtab corresponding to the entry.
 328  */
 329 char** get_symtab_handle(t_symtab* symtab, int index);
 330
 331 /*! \brief
 332  * Prints human readable form of \p symtab.
 333  *
 334  * \param[in] fp File to print to.
 335  * \param[in] indent Number of spaces to use for indentation.
 336  * \param[in] title Name for header text.
 337  * \param[in] symtab Symbol table to print out.
 338  */
 339 void pr_symtab(FILE* fp, int indent, const char* title, t_symtab* symtab);
 340
 341 #endif