ResetOnCopy.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_RESET_ON_COPY_H_
#define SimTK_SimTKCOMMON_RESET_ON_COPY_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) 2015 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>
#include <memory>
#include <cstddef>
#include <type_traits>

namespace SimTK {

//==============================================================================
//                             RESET ON COPY
//==============================================================================

// Only show the unspecialized helper class in Doxygen.

template <class T, bool IsScalarType>
class ResetOnCopyHelper {};

template <class T> 
class ResetOnCopy : public ResetOnCopyHelper<T, std::is_scalar<T>::value> {
    using Super = ResetOnCopyHelper<T, std::is_scalar<T>::value>;
 // These confuse doxygen.
    // TODO: should be possible to specialize this for arrays.
    static_assert(!std::is_array<T>::value, 
        "ResetOnCopy<T> does not allow T to be an array. Use an array "
        "of ResetOnCopy<E> instead, where E is the element type.");

    static_assert(!std::is_enum<T>::value,
        "ResetOnCopy<T> does not allow T to be an enum, because resetting to "
        "zero may be inappropriate. Use ReinitOnCopy<T> instead and "
        "provide the desired reinitialization enumerator value.");

    static_assert(std::is_default_constructible<T>::value,
        "ResetOnCopy<T> requires type T to have an accessible default "
        "constructor. Use ReinitOnCopy<T> instead to construct from an "
        "initial value.");

    static_assert(std::is_destructible<T>::value,
        "ResetOnCopy<T> requires type T to have an accessible destructor.");
public:
    using Super::Super;
    using Super::operator=;
  
    ResetOnCopy() : Super() {} // same as default

    ResetOnCopy(const T& value) : Super(value) {}

    ResetOnCopy(T&& value) : Super(std::move(value)) {}

    ResetOnCopy(const ResetOnCopy&) : ResetOnCopy() {}

    ResetOnCopy(ResetOnCopy&& source) 
    :   Super(static_cast<Super&&>(source)) {} // default

    ResetOnCopy& operator=(const ResetOnCopy& ignored) 
    {   Super::operator=(static_cast<const Super&>(ignored)); return *this; }

    ResetOnCopy& operator=(ResetOnCopy&& source) 
    {   Super::operator=(static_cast<Super&&>(source)); return *this; }

    ResetOnCopy& operator=(const T& value) 
    {   Super::operator=(value); return *this; }

    ResetOnCopy& operator=(T&& value) 
    {   Super::operator=(std::move(value)); return *this; }

    const T& getT() const {return Super::getT();}

    T& updT() {return Super::updT();}
};

//==============================================================================
//                          RESET ON COPY HELPERS
//==============================================================================

 // hide helpers from doxygen
/* ResetOnCopy helper class for built-in ("scalar") types (arithmetic, 
character, and pointer types). We don't want to allow enums here because they
should always be initialized to one of their values, not necessarily zero.
These types are value initialized, so will be reset to zero. */
template <class T>
class ResetOnCopyHelper<T,true> {
public:
    // These three are just the defaults but for debugging it is helpful to
    // have them explicitly present to step into.

    // Default construction (note that m_value is "value initialized").
    ResetOnCopyHelper() {}

    // Default move construction.
    ResetOnCopyHelper(ResetOnCopyHelper&& source) 
    :   m_value(std::move(source.m_value)) {}

    // Default move assignment.
    ResetOnCopyHelper& operator=(ResetOnCopyHelper&& source) 
    {   m_value = std::move(source.m_value); return *this; }

    // Copy constructor isn't needed here since ResetOnCopy doesn't use it.
    ResetOnCopyHelper(const ResetOnCopyHelper&) = delete;

    // Constructor from lvalue or rvalue T sets an initial value but this 
    // initial value will not be restored on copy. 
    explicit ResetOnCopyHelper(const T& value) : m_value(value) {}

    // Make copy assignment produce the same result as if the target were
    // value initialized; the source is ignored.
    ResetOnCopyHelper& operator=(const ResetOnCopyHelper&) 
    {   m_value = T{}; return *this; }

    // Allow assignment from an lvalue or rvalue object of type T.
    ResetOnCopyHelper& operator=(const T& value) 
    {   m_value = value; return *this; }

    // Implicit conversion to a const reference to the contained object.
    operator const T&() const {return getT();}

    // Implicit conversion to a writable reference to the contained object.
    operator T&() {return updT();}

    const T& getT() const {return m_value;}
    T&       updT()       {return m_value;}

private:
    T   m_value{}; // value initialize; i.e., set to zero
};


/* ResetOnCopy helper class specialization for any type `T` that is not a
built-in ("scalar") type, as long as it is DefaultConstructible and 
Destructible. This will add `CopyConstructible` and `CopyAssignable` concepts to
move-only classes like `std::unique`, but those operations just reset the object
to its default-constructed state. */
template <class T>
class ResetOnCopyHelper<T,false> : public T {
public:
    using T::T;
    using T::operator=;

    // These three are just the defaults but for debugging it is helpful to
    // have them explicitly present to step into.

    // Default construction (T is default constructed).
    ResetOnCopyHelper() : T() {}

    // Default move construction.
    ResetOnCopyHelper(ResetOnCopyHelper&& source) : T(std::move(source)) {}

    // Default move assignment.
    ResetOnCopyHelper& operator=(ResetOnCopyHelper&& source) 
    {   T::operator=(std::move(source)); return *this; }

    // Copy constructor isn't needed here since ResetOnCopy doesn't use it.
    ResetOnCopyHelper(const ResetOnCopyHelper&) = delete;

    // Constructor from lvalue T sets an initial value but this initial value
    // will not be restored on copy. Won't compile if T doesn't have a copy
    // constructor.
    explicit ResetOnCopyHelper(const T& value) : T(value) {}

    // Constructor from rvalue T sets an initial value but this initial value
    // will not be restored on copy. Won't compile if T doesn't have a move
    // or copy constructor.
    explicit ResetOnCopyHelper(const T&& value) : T(std::move(value)) {}

    // Copy assignment just destroys and reconstructs this object using 
    // the default constructor for type `T`.
    ResetOnCopyHelper& operator=(const ResetOnCopyHelper&) {
        T* thisT = static_cast<T*>(this); // upcast to base
        thisT->~T();        // destruct the current base object
        new (thisT) T();    // reconstruct it with default constructor
        return *this;
    }

    const T& getT() const {return static_cast<const T&>(*this);}
    T&       updT()       {return static_cast<T&>(*this);}
};
} // namespace SimTK

#endif // SimTK_SimTKCOMMON_RESET_ON_COPY_H_