src/gromacs/compat/pointers.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 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
  36 /*! \libinternal \file
  37  * \brief Provides ported functions/classes from gsl/pointers
  38  *
  39  * Adapted from the Guidelines Support Library v2.0.0. at
  40  * https://github.com/Microsoft/GSL
  41  *
  42  * \author Mark Abraham <mark.j.abraham@gmail.com>
  43  * \ingroup module_compat
  44  * \inlibraryapi
  45  */
  46 #ifndef GMX_COMPAT_POINTERS_H
  47 #define GMX_COMPAT_POINTERS_H
  48
  49 #include <type_traits>
  50 #include <utility>
  51
  52 #include "gromacs/utility/gmxassert.h"
  53
  54 namespace gmx
  55 {
  56 namespace compat
  57 {
  58
  59 //! Contract-assurance macros that work like a simple version of the GSL ones
  60 //! \{
  61 #define Expects(cond) GMX_ASSERT((cond), "Precondition violation")
  62 #define Ensures(cond) GMX_ASSERT((cond), "Postcondition violation")
  63 //! \}
  64
  65 /*! \libinternal
  66  * \brief Restricts a pointer or smart pointer to only hold non-null values.
  67  *
  68  * Has zero size overhead over T.
  69  *
  70  * If T is a pointer (i.e. T == U*) then
  71  * - allow construction from U*
  72  * - disallow construction from nullptr_t
  73  * - disallow default construction
  74  * - ensure construction from null U* fails (only in debug builds)
  75  * - allow implicit conversion to U*
  76  *
  77  * \todo Eliminate this when we require a version of C++ that supports
  78  * std::not_null.
  79  */
  80 template<class T>
  81 class not_null
  82 {
  83 public:
  84     static_assert(std::is_assignable<T&, std::nullptr_t>::value, "T cannot be assigned nullptr.");
  85
  86     //! Move constructor. Asserts in debug mode if \c is nullptr.
  87     template<typename U, typename = std::enable_if_t<std::is_convertible<U, T>::value>>
  88     constexpr explicit not_null(U&& u) : ptr_(std::forward<U>(u))
  89     {
  90         Expects(ptr_ != nullptr);
  91     }
  92
  93     //! Simple constructor. Asserts in debug mode if \c u is nullptr.
  94     template<typename = std::enable_if_t<!std::is_same<std::nullptr_t, T>::value>>
  95     constexpr explicit not_null(T u) : ptr_(u)
  96     {
  97         Expects(ptr_ != nullptr);
  98     }
  99
 100     //! Copy constructor.
 101     template<typename U, typename = std::enable_if_t<std::is_convertible<U, T>::value>>
 102     constexpr not_null(const not_null<U>& other) : not_null(other.get())
 103     {
 104     }
 105
 106     //! Default constructors and assignment.
 107     //! \{
 108     not_null(not_null&& other) noexcept = default;
 109     not_null(const not_null& other)     = default;
 110     not_null& operator=(const not_null& other) = default;
 111     //! \}
 112
 113     //! Getters
 114     //! \{
 115     constexpr T get() const
 116     {
 117         Ensures(ptr_ != nullptr);
 118         return ptr_;
 119     }
 120
 121     constexpr   operator T() const { return get(); }
 122     constexpr T operator->() const { return get(); }
 123     //! \}
 124
 125     //! Deleted to prevent compilation when someone attempts to assign a null pointer constant.
 126     //! \{
 127     not_null(std::nullptr_t) = delete;
 128     not_null& operator=(std::nullptr_t) = delete;
 129     //! \}
 130
 131     //! Deleted unwanted operators because pointers only point to single objects.
 132     //! \{
 133     not_null& operator++()                     = delete;
 134     not_null& operator--()                     = delete;
 135     not_null  operator++(int)                  = delete;
 136     not_null  operator--(int)                  = delete;
 137     not_null& operator+=(std::ptrdiff_t)       = delete;
 138     not_null& operator-=(std::ptrdiff_t)       = delete;
 139     void      operator[](std::ptrdiff_t) const = delete;
 140     //! \}
 141
 142 private:
 143     T ptr_;
 144 };
 145
 146 //! Convenience function for making not_null pointers from plain pointers.
 147 template<class T>
 148 not_null<T> make_not_null(T&& t)
 149 {
 150     return not_null<std::remove_cv_t<std::remove_reference_t<T>>>{ std::forward<T>(t) };
 151 }
 152
 153 //! Convenience function for making not_null pointers from smart pointers.
 154 template<class T>
 155 not_null<typename T::pointer> make_not_null(T& t)
 156 {
 157     return not_null<typename std::remove_reference_t<T>::pointer>{ t.get() };
 158 }
 159
 160 //! Operators to compare not_null pointers.
 161 //! \{
 162 template<class T, class U>
 163 auto operator==(const not_null<T>& lhs, const not_null<U>& rhs) -> decltype(lhs.get() == rhs.get())
 164 {
 165     return lhs.get() == rhs.get();
 166 }
 167
 168 template<class T, class U>
 169 auto operator!=(const not_null<T>& lhs, const not_null<U>& rhs) -> decltype(lhs.get() != rhs.get())
 170 {
 171     return lhs.get() != rhs.get();
 172 }
 173
 174 template<class T, class U>
 175 auto operator<(const not_null<T>& lhs, const not_null<U>& rhs) -> decltype(lhs.get() < rhs.get())
 176 {
 177     return lhs.get() < rhs.get();
 178 }
 179
 180 template<class T, class U>
 181 auto operator<=(const not_null<T>& lhs, const not_null<U>& rhs) -> decltype(lhs.get() <= rhs.get())
 182 {
 183     return lhs.get() <= rhs.get();
 184 }
 185
 186 template<class T, class U>
 187 auto operator>(const not_null<T>& lhs, const not_null<U>& rhs) -> decltype(lhs.get() > rhs.get())
 188 {
 189     return lhs.get() > rhs.get();
 190 }
 191
 192 template<class T, class U>
 193 auto operator>=(const not_null<T>& lhs, const not_null<U>& rhs) -> decltype(lhs.get() >= rhs.get())
 194 {
 195     return lhs.get() >= rhs.get();
 196 }
 197 //! \}
 198
 199 //! Deleted unwanted arithmetic operators.
 200 //! \{
 201 template<class T, class U>
 202 std::ptrdiff_t operator-(const not_null<T>&, const not_null<U>&) = delete;
 203 template<class T>
 204 not_null<T> operator-(const not_null<T>&, std::ptrdiff_t) = delete;
 205 template<class T>
 206 not_null<T> operator+(const not_null<T>&, std::ptrdiff_t) = delete;
 207 template<class T>
 208 not_null<T> operator+(std::ptrdiff_t, const not_null<T>&) = delete;
 209 //! \}
 210
 211 } // namespace compat
 212 } // namespace gmx
 213
 214 #endif