src/gromacs/utility/any.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2016,2017,2018,2019,2020,2021, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \libinternal \file
  36  * \brief
  37  * Declares gmx::Any.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \inlibraryapi
  41  * \ingroup module_utility
  42  */
  43 #ifndef GMX_UTILITY_ANY_H
  44 #define GMX_UTILITY_ANY_H
  45
  46 #include <memory>
  47 #include <string>
  48 #include <type_traits>
  49 #include <typeindex>
  50 #include <typeinfo>
  51 #include <utility>
  52
  53 #include "gromacs/utility/gmxassert.h"
  54
  55 namespace gmx
  56 {
  57
  58 /*! \libinternal \brief
  59  * Represents a dynamically typed value of an arbitrary type - deprecated.
  60  *
  61  * New uses of this type should be avoided - prefer std::any or
  62  * std::variant.
  63  *
  64  * To create an Any, either initialize it as empty, or with the create()
  65  * method (or the equivalent constructor, if the type parameter can be deduced
  66  * and is clear to the reader from the context).
  67  *
  68  * To query the type of the contents in the any, use isEmpty(), type(), and
  69  * isType().
  70  *
  71  * To access the value, you need to know the type as a compile-time constant
  72  * (e.g., through branching based on isType()), and then use cast() or
  73  * tryCast().
  74  *
  75  * Methods in this class do not throw unless otherwise indicated.
  76  *
  77  * This provides essentially the same functionality as boost::any.
  78  *
  79  * It would be good to replace the current uses of this type with
  80  * std::any or std::variant, but see
  81  * https://gitlab.com/gromacs/gromacs/-/issues/3951 for discussion
  82  * about the things that have blocked such attempts.
  83  *
  84  * \ingroup module_utility
  85  */
  86 class Any
  87 {
  88 public:
  89     /*! \brief
  90      * Creates a any that holds the given value.
  91      *
  92      * \throws std::bad_alloc if out of memory.
  93      *
  94      * This method allows explicitly specifying the template argument,
  95      * contrary to the templated constructor.
  96      */
  97     template<typename T>
  98     static Any create(const T& value)
  99     {
 100         return Any(value);
 101     }
 102     /*! \brief
 103      * Creates a any that holds the given value.
 104      *
 105      * \throws std::bad_alloc if out of memory.
 106      *
 107      * In addition to allowing specifying the template argument, this
 108      * method avoids copying when move-construction is possible.
 109      */
 110     template<typename T>
 111     static Any create(T&& value)
 112     {
 113         return Any(std::forward<T>(value));
 114     }
 115
 116     //! Creates an empty any value.
 117     Any() {}
 118     /*! \brief
 119      * Creates a any that holds the given value.
 120      *
 121      * \throws std::bad_alloc if out of memory.
 122      */
 123     template<typename T, typename = std::enable_if_t<!std::is_same<T, Any>::value>>
 124     explicit Any(T&& value) :
 125         content_(new Content<typename std::decay<T>::type>(std::forward<T>(value)))
 126     {
 127     }
 128     /*! \brief
 129      * Creates a deep copy of a any.
 130      *
 131      * \throws std::bad_alloc if out of memory.
 132      */
 133     Any(const Any& other) : content_(other.cloneContent()) {}
 134     //! Move-constructs a any.
 135     Any(Any&& other) noexcept : content_(std::move(other.content_)) {}
 136     /*! \brief
 137      * Assigns the any.
 138      *
 139      * \throws std::bad_alloc if out of memory.
 140      */
 141     Any& operator=(const Any& other)
 142     {
 143         content_ = other.cloneContent();
 144         return *this;
 145     }
 146     //! Move-assigns the any.
 147     Any& operator=(Any&& other) noexcept
 148     {
 149         content_ = std::move(other.content_);
 150         return *this;
 151     }
 152
 153     //! Whether any value is stored.
 154     bool isEmpty() const { return content_ == nullptr; }
 155     //! Returns the dynamic type of the value that is currently stored.
 156     std::type_index type() const
 157     {
 158         const std::type_info& info = !isEmpty() ? content_->typeInfo() : typeid(void);
 159         return std::type_index(info);
 160     }
 161     //! Returns whether the type stored matches the template parameter.
 162     template<typename T>
 163     bool isType() const
 164     {
 165         return !isEmpty() && content_->typeInfo() == typeid(T);
 166     }
 167
 168     /*! \brief
 169      * Tries to get the value as the given type.
 170      *
 171      * \tparam T  Type to get.
 172      * \returns Pointer to the value, or nullptr if the type does not match
 173      *     the stored value.
 174      */
 175     template<typename T>
 176     const T* tryCast() const
 177     {
 178         return isType<T>() ? &static_cast<Content<T>*>(content_.get())->value_ : nullptr;
 179     }
 180     /*! \brief
 181      * Gets the value when the type is known.
 182      *
 183      * \tparam T  Type to get (which must match what the any stores).
 184      *
 185      * Asserts if the any is empty or does not contain the requested type.
 186      */
 187     template<typename T>
 188     const T& cast() const
 189     {
 190         const T* value = tryCast<T>();
 191         GMX_RELEASE_ASSERT(value != nullptr, "Cast to incorrect type");
 192         return *value;
 193     }
 194     /*! \brief
 195      * Tries to get the value as the given type as a non-const pointer.
 196      *
 197      * \tparam T  Type to get.
 198      * \returns Pointer to the value, or nullptr if the type does not match
 199      *     the stored value.
 200      *
 201      * This method allows modifying the value in-place, which is useful
 202      * with more complicated data structures.
 203      */
 204     template<typename T>
 205     T* tryCastRef()
 206     {
 207         return isType<T>() ? &static_cast<Content<T>*>(content_.get())->value_ : nullptr;
 208     }
 209     /*! \brief
 210      * Gets the value when the type is known as a modifiable reference.
 211      *
 212      * \tparam T  Type to get (which must match what the any stores).
 213      *
 214      * Asserts if the any is empty or does not contain the requested type.
 215      */
 216     template<typename T>
 217     T& castRef()
 218     {
 219         T* value = tryCastRef<T>();
 220         GMX_RELEASE_ASSERT(value != nullptr, "Cast to incorrect type");
 221         return *value;
 222     }
 223
 224 private:
 225     class IContent
 226     {
 227     public:
 228         virtual ~IContent() {}
 229         virtual const std::type_info&     typeInfo() const = 0;
 230         virtual std::unique_ptr<IContent> clone() const    = 0;
 231     };
 232
 233     template<typename T>
 234     class Content : public IContent
 235     {
 236     public:
 237         explicit Content(const T& value) : value_(value) {}
 238         explicit Content(T&& value) : value_(std::move(value)) {}
 239
 240         const std::type_info&     typeInfo() const override { return typeid(T); }
 241         std::unique_ptr<IContent> clone() const override
 242         {
 243             return std::make_unique<Content>(value_);
 244         }
 245
 246         T value_;
 247     };
 248
 249     //! Creates a deep copy of the content.
 250     std::unique_ptr<IContent> cloneContent() const
 251     {
 252         return content_ != nullptr ? content_->clone() : nullptr;
 253     }
 254
 255     std::unique_ptr<IContent> content_;
 256 };
 257
 258 //! \cond libapi
 259 /*! \brief
 260  * Converts a Any value to a string.
 261  *
 262  * As the name suggests, only some types of "simple" values (such as int) are
 263  * supported.  Asserts for unsupported types.
 264  *
 265  * \ingroup module_utility
 266  */
 267 std::string simpleValueToString(const Any& value);
 268 //! \endcond
 269
 270 } // namespace gmx
 271
 272 #endif