ReferencePtr.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_REFERENCE_PTR_H_
#define SimTK_SimTKCOMMON_REFERENCE_PTR_H_

/* -------------------------------------------------------------------------- *
 *                       Simbody(tm): SimTKcommon                             *
 * -------------------------------------------------------------------------- *
 * This is part of the SimTK biosimulation toolkit originating from           *
 * Simbios, the NIH National Center for Physics-Based Simulation of           *
 * Biological Structures at Stanford, funded under the NIH Roadmap for        *
 * Medical Research, grant U54 GM072970. See https://simtk.org/home/simbody.  *
 *                                                                            *
 * Portions copyright (c) 2012-15 Stanford University and the Authors.        *
 * Authors: Michael Sherman                                                   *
 * Contributors:                                                              *
 *                                                                            *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may    *
 * not use this file except in compliance with the License. You may obtain a  *
 * copy of the License at http://www.apache.org/licenses/LICENSE-2.0.         *
 *                                                                            *
 * Unless required by applicable law or agreed to in writing, software        *
 * distributed under the License is distributed on an "AS IS" BASIS,          *
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   *
 * See the License for the specific language governing permissions and        *
 * limitations under the License.                                             *
 * -------------------------------------------------------------------------- */

#include "SimTKcommon/internal/common.h"
#include <cassert>
#include <utility>

namespace SimTK {

template <class T> class ReferencePtr {
public:
    typedef T  element_type; 
    typedef T* pointer;      
    typedef T& reference;    

    ReferencePtr() noexcept : p(nullptr) {}

    ReferencePtr(std::nullptr_t) noexcept : ReferencePtr() {}

    explicit ReferencePtr(T* tp) noexcept : p(tp) {}

    explicit ReferencePtr(T& t) noexcept : ReferencePtr(&t) {}

    ReferencePtr(const ReferencePtr&) noexcept : p(nullptr) {}

    ReferencePtr(ReferencePtr&& src) noexcept : p(src.release()) {}

    DEPRECATED_14("use ReferencePtr(nullptr) instead")
    ReferencePtr(int mustBeZero) noexcept : ReferencePtr()
    {   assert(mustBeZero==0); }
    ReferencePtr& operator=(const ReferencePtr& src) noexcept
    {   if (&src != this) reset(); return *this; }

    ReferencePtr& operator=(ReferencePtr&& src) noexcept {
        if (&src != this) 
            p = src.release();
        return *this; 
    }

    ReferencePtr& operator=(T& t) noexcept    
    {  reset(&t); return *this; }

    ReferencePtr& operator=(T* tp) noexcept               
    {   reset(tp); return *this; }
    
    ~ReferencePtr() noexcept {reset();} // just being tidy
    T* get() const noexcept {return p;}

    T& getRef() const { 
        SimTK_ERRCHK(p!=nullptr, "ReferencePtr::getRef()", 
                    "An attempt was made to dereference a null pointer."); 
        return *p; 
    }

    T* operator->() const {return &getRef();}

    T& operator*() const {return getRef();}

    void reset(T* tp=nullptr) noexcept {p=tp;}

    void swap(ReferencePtr& other) noexcept {
        std::swap(p, other.p);
    }

    bool empty() const noexcept {return !p;}

    explicit operator bool() const noexcept {return !empty();}

    T* release() noexcept {
        T* x=p; 
        p=nullptr; 
        return x;
    }

    DEPRECATED_14("use reset() instead")
    void clear() noexcept {reset();}

    DEPRECATED_14("use get() rather than implicit conversion to T*")
    operator T*() const noexcept {return p;}

private:
    T*    p;        // can be nullptr
};    



//==============================================================================
//                       SimTK namespace-scope functions
//==============================================================================
// These namespace-scope functions will be resolved by the compiler using
// "Koenig lookup" which examines the arguments' namespaces first.
// See Herb Sutter's discussion here: http://www.gotw.ca/publications/mill08.htm.

template <class T> inline void
swap(ReferencePtr<T>& p1, ReferencePtr<T>& p2) noexcept {
    p1.swap(p2);
}

template <class charT, class traits, class T>
inline std::basic_ostream<charT,traits>& 
operator<<(std::basic_ostream<charT,traits>& os, 
           const ReferencePtr<T>&  p) 
{   os << p.get(); return os; }

template <class T, class U>
inline bool operator==(const ReferencePtr<T>& lhs,
                       const ReferencePtr<U>& rhs)
{   return lhs.get() == rhs.get(); }

template <class T>
inline bool operator==(const ReferencePtr<T>& lhs, std::nullptr_t)
{   return lhs.empty(); }

template <class T>
inline bool operator==(std::nullptr_t, const ReferencePtr<T>& rhs)
{   return rhs.empty(); }

template <class T, class U>
inline bool operator<(const ReferencePtr<T>& lhs,
                      const ReferencePtr<U>& rhs)
{   return lhs.get() < rhs.get(); }

template <class T>
inline bool operator<(const ReferencePtr<T>& lhs, std::nullptr_t)
{   return false; }

template <class T>
inline bool operator<(std::nullptr_t, const ReferencePtr<T>& rhs)
{   return !rhs.empty(); }


// These functions are derived from operator== and operator<.

template <class T, class U>
inline bool operator!=(const ReferencePtr<T>& lhs,
                       const ReferencePtr<U>& rhs)
{   return !(lhs==rhs); }

template <class T>
inline bool operator!=(const ReferencePtr<T>& lhs, std::nullptr_t)
{   return !(lhs==nullptr); }

template <class T>
inline bool operator!=(std::nullptr_t, const ReferencePtr<T>& rhs)
{   return !(nullptr==rhs); }

template <class T, class U>
inline bool operator>(const ReferencePtr<T>& lhs,
                      const ReferencePtr<U>& rhs)
{   return rhs < lhs; }
template <class T>
inline bool operator>(const ReferencePtr<T>& lhs, std::nullptr_t)
{   return nullptr < lhs; }

template <class T>
inline bool operator>(std::nullptr_t, const ReferencePtr<T>& rhs)
{   return rhs < nullptr; }


template <class T, class U>
inline bool operator>=(const ReferencePtr<T>& lhs,
                       const ReferencePtr<U>& rhs)
{   return !(lhs < rhs); }
template <class T>
inline bool operator>=(const ReferencePtr<T>& lhs, std::nullptr_t)
{   return !(lhs < nullptr); }

template <class T>
inline bool operator>=(std::nullptr_t, const ReferencePtr<T>& rhs)
{   return !(nullptr < rhs); }


template <class T, class U>
inline bool operator<=(const ReferencePtr<T>& lhs,
                       const ReferencePtr<U>& rhs)
{   return !(rhs < lhs); }
template <class T>
inline bool operator<=(const ReferencePtr<T>& lhs, std::nullptr_t)
{   return !(nullptr < lhs); }
template <class T>
inline bool operator<=(std::nullptr_t, const ReferencePtr<T>& rhs)
{   return !(rhs < nullptr); }


template <class T>
DEPRECATED_14("use refptr != nullptr instead")
inline bool operator!=(const ReferencePtr<T>& lhs, int mustBeZero)
{   assert(mustBeZero==0); return !(lhs==nullptr); }

} // namespace SimTK

#endif // SimTK_SimTKCOMMON_REFERENCE_PTR_H_