ClonePtr.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_CLONE_PTR_H_
#define SimTK_SimTKCOMMON_CLONE_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) 2005-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 <memory>
#include <iosfwd>
#include <cassert>
#include <utility>

namespace SimTK {

template <class T> class ClonePtr {
public:
    typedef T  element_type; 
    typedef T* pointer;      
    typedef T& reference;    
    
    ClonePtr() noexcept : p(nullptr) {}

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

    explicit ClonePtr(T* x) noexcept : p(x) {}

    explicit ClonePtr(const T* x) : ClonePtr(cloneOrNull(x)) {}

    explicit ClonePtr(const T& x) : ClonePtr(&x) {}

    ClonePtr(const ClonePtr& src) : p(cloneOrNull(src.p)) {}

    template <class U>
    ClonePtr(const ClonePtr<U>& src) : p(cloneOrNull(src.p)) {} 

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

    template <class U>
    ClonePtr(ClonePtr<U>&& src) noexcept : p(src.release()) {}
    ClonePtr& operator=(const ClonePtr& src) {
        if (&src != this) { 
            assert((p != src.p) || !p); // can't be same ptr unless null
            reset(cloneOrNull(src.p));
        }
        return *this;
    }

    template <class U>
    ClonePtr& operator=(const ClonePtr<U>& src) {
        // The source can't be the same container as this one since they are
        // different types. The managed pointers should never be the same either 
        // since ClonePtrs represent unique ownership. (OK if both nullptr.)
        assert((p != static_cast<const T*>(src.p)) || !p);

        reset(cloneOrNull(src.p));
        return *this;
    }

    ClonePtr& operator=(ClonePtr&& src) noexcept { 
        if (&src != this) {   
            assert((p != src.p) || !p); // can't be same ptr unless null
            reset(src.p); src.p = nullptr; 
        }
        return *this;
    }

    template <class U>
    ClonePtr& operator=(ClonePtr<U>&& src) noexcept {
        // The source can't be the same container as this one since they are
        // different types. The managed pointers should never be the same either 
        // since ClonePtrs represent unique ownership. (OK if both nullptr.)
        assert((p != static_cast<const T*>(src.p)) || !p);
        reset(src.p); src.p = nullptr;
        return *this;
    }

    ClonePtr& operator=(const T& x)          
    {   reset(cloneOrNull(&x)); return *this; }

    ClonePtr& operator=(T* x) noexcept               
    {   reset(x); return *this; }
    ~ClonePtr() noexcept {reset();}
    const T* get() const noexcept {return p;}

    T* upd() noexcept {return p;}

    const T& getRef() const { 
        SimTK_ERRCHK(!empty(), "ClonePtr::getRef()", 
                    "An attempt was made to dereference a null pointer."); 
        return *get(); 
    } 

    T& updRef() { 
        SimTK_ERRCHK(!empty(), "ClonePtr::updRef()", 
                    "An attempt was made to dereference a null pointer.");
        return *upd(); 
    }

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

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

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

    T& operator*() {return updRef();}
    void reset() noexcept {
        delete p; 
        p = nullptr;
    }

    void reset(T* x) noexcept {
        if (x != p) {
            delete p;
            p = x;
        }
    }

    void swap(ClonePtr& other) noexcept {
        std::swap(p, other.p);
    }
   
    bool empty() const noexcept {return !p;} // count should be null also

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

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

    DEPRECATED_14("use get() instead")
    const T* getPtr() const noexcept {return get();}
    DEPRECATED_14("use upd() instead")
    T* updPtr() noexcept {return upd();}  
    DEPRECATED_14("use reset() instead")
    void clear() noexcept {reset();}

private:
template <class U> friend class ClonePtr;

    // If src is non-null, clone it; otherwise return nullptr.
    static T* cloneOrNull(const T* src) {
        return src ? src->clone() : nullptr;
    }

    T*      p;          // this may be null
};



//==============================================================================
//                       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(ClonePtr<T>& p1, ClonePtr<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 ClonePtr<T>&  p) 
{   os << p.get(); return os; }

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

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

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

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

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

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


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

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

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

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


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

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


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

} // namespace SimTK

#endif // SimTK_SimTKCOMMON_CLONE_PTR_H_