itkVariableLengthVector.h

Go to the documentation of this file.

/*=========================================================================
 *
 *  Copyright NumFOCUS
 *
 *  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
 *
 *         https://www.apache.org/licenses/LICENSE-2.0.txt
 *
 *  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.
 *
 *=========================================================================*/
#ifndef itkVariableLengthVector_h
#define itkVariableLengthVector_h
 
#include <cassert>
#include <algorithm>
#include <iterator>
#include <type_traits>
#include "itkNumericTraits.h"
#include "itkMetaProgrammingLibrary.h"
#include "itkIsNumber.h"
#include "itkPromoteType.h"
#include "itkBinaryOperationConcept.h"
 
namespace itk
{
 
template <typename TExpr1, typename TExpr2, typename TBinaryOp>
struct VariableLengthVectorExpression;

template <typename TValue>
class ITK_TEMPLATE_EXPORT VariableLengthVector
{
public:

  struct AllocateRootPolicy
  {};

  struct AlwaysReallocate : AllocateRootPolicy
  {
    bool
    operator()(unsigned int itkNotUsed(newSize), unsigned int itkNotUsed(oldSize)) const
    {
      return true;
    }
  };

  struct NeverReallocate : AllocateRootPolicy
  {
    bool
    operator()([[maybe_unused]] unsigned int newSize, [[maybe_unused]] unsigned int oldSize) const
    {
      itkAssertInDebugAndIgnoreInReleaseMacro(newSize == oldSize &&
                                              "SetSize is expected to never change the VariableLengthVector size...");
      return true;
    }
  };

  struct ShrinkToFit : AllocateRootPolicy
  {
    bool
    operator()(unsigned int newSize, unsigned int oldSize) const
    {
      return newSize != oldSize;
    }
  };

  struct DontShrinkToFit : AllocateRootPolicy
  {
    bool
    operator()(unsigned int newSize, unsigned int oldSize) const
    {
      return newSize > oldSize;
    }
  };

  struct KeepValuesRootPolicy
  {};

  struct KeepOldValues : KeepValuesRootPolicy
  {
    template <typename TValue2>
    void
    operator()(unsigned int newSize, unsigned int oldSize, TValue2 * oldBuffer, TValue2 * newBuffer) const
    {
      const size_t nb = std::min(newSize, oldSize);
      if (nb > 0)
      {
        itkAssertInDebugAndIgnoreInReleaseMacro(newBuffer);
        itkAssertInDebugAndIgnoreInReleaseMacro(oldBuffer);
        std::copy_n(oldBuffer, nb, newBuffer);
      }
    }
  };

  struct DumpOldValues : KeepValuesRootPolicy
  {
    template <typename TValue2>
    void
    operator()(unsigned int itkNotUsed(newSize),
               unsigned int itkNotUsed(oldSize),
               TValue2 *    itkNotUsed(oldBuffer),
               TValue2 *    itkNotUsed(newBuffer)) const
    {}
  };
 

  using ValueType = TValue;
  using ComponentType = TValue;
  using RealValueType = typename NumericTraits<ValueType>::RealType;
  using Self = VariableLengthVector;

  using ElementIdentifier = unsigned int;
 
  // Nested types from C++ Standard section "Container requirements" [container.reqmts], and from `std::vector`:
  using value_type = TValue;
  using reference = TValue &;
  using const_reference = const TValue &;
  using iterator = TValue *;
  using const_iterator = const TValue *;
  using difference_type = ptrdiff_t;
  using size_type = size_t;
  using reverse_iterator = std::reverse_iterator<iterator>;
  using const_reverse_iterator = std::reverse_iterator<const_iterator>;

  VariableLengthVector() = default;

  explicit VariableLengthVector(unsigned int length);

  explicit VariableLengthVector(unsigned int length, const TValue & value);

  VariableLengthVector(ValueType * datain, unsigned int sz, bool LetArrayManageMemory = false);

  VariableLengthVector(const ValueType * datain, unsigned int sz, bool LetArrayManageMemory = false);

  template <typename T>
  VariableLengthVector(const VariableLengthVector<T> & v)
    : VariableLengthVector(v.Size())
  {
    if (m_NumElements != 0)
    {
      itkAssertInDebugAndIgnoreInReleaseMacro(m_Data != nullptr);
      for (ElementIdentifier i = 0; i < m_NumElements; ++i)
      {
        this->m_Data[i] = static_cast<ValueType>(v[i]);
      }
    }
    else
    {
      m_Data = nullptr;
    }
  }

  VariableLengthVector(const VariableLengthVector<TValue> & v);

  void
  Swap(Self & v) noexcept
  {
    itkAssertInDebugAndIgnoreInReleaseMacro(m_LetArrayManageMemory == v.m_LetArrayManageMemory);
    using std::swap;
    swap(v.m_Data, m_Data);
    swap(v.m_NumElements, m_NumElements);
  }

  VariableLengthVector(Self && v) noexcept;

  Self &
  operator=(Self && v) noexcept;

  template <typename TExpr1, typename TExpr2, typename TBinaryOp>
  VariableLengthVector(const VariableLengthVectorExpression<TExpr1, TExpr2, TBinaryOp> & rhs);

  template <typename TExpr1, typename TExpr2, typename TBinaryOp>
  Self &
  operator=(const VariableLengthVectorExpression<TExpr1, TExpr2, TBinaryOp> & rhs);

  void
  Fill(const TValue & v);

  template <typename T>
  Self &
  operator=(const VariableLengthVector<T> & v)
  {
    // No self assignment test is done. Indeed:
    // - the operator already resists self assignment through a strong exception
    // guarantee
    // - the test becomes a pessimization as we never write
    //    VLV<const TValue> vcref(v.GetDataPointer(), v.GetSize());
    //    ...;
    //    v = vcref;
    const ElementIdentifier N = v.Size();
    this->SetSize(N, DontShrinkToFit(), DumpOldValues());
    for (ElementIdentifier i = 0; i < N; ++i)
    {
      this->m_Data[i] = static_cast<ValueType>(v[i]);
    }
    return *this;
  }

  Self &
  operator=(const Self & v);

  Self &
  FastAssign(const Self & v);

  Self &
  operator=(const TValue & v);

  [[nodiscard]] unsigned int
  Size() const
  {
    return m_NumElements;
  }
  [[nodiscard]] unsigned int
  GetSize() const
  {
    return m_NumElements;
  }
  [[nodiscard]] unsigned int
  GetNumberOfElements() const
  {
    return m_NumElements;
  }
  TValue &
  operator[](unsigned int i)
  {
    return this->m_Data[i];
  }

  const TValue &
  operator[](unsigned int i) const
  {
    return this->m_Data[i];
  }

  [[nodiscard]] const TValue &
  GetElement(unsigned int i) const
  {
    return m_Data[i];
  }

  void
  SetElement(unsigned int i, const TValue & value)
  {
    m_Data[i] = value;
  }

  template <typename TReallocatePolicy, typename TKeepValuesPolicy>
  void
  SetSize(unsigned int sz, TReallocatePolicy reallocatePolicy, TKeepValuesPolicy keepValues);

  void
  SetSize(unsigned int sz, bool destroyExistingData = true)
  {
    // Stays compatible with previous code version
    // And works around the fact C++03 template functions can't have default
    // arguments on template types.
    if (destroyExistingData)
    {
      SetSize(sz, AlwaysReallocate(), KeepOldValues());
    }
    else
    {
      SetSize(sz, ShrinkToFit(), KeepOldValues());
    }
  }

  void
  DestroyExistingData();

  void
  SetData(TValue * datain, bool LetArrayManageMemory = false);

  void
  SetData(TValue * datain, unsigned int sz, bool LetArrayManageMemory = false);

  ~VariableLengthVector();

  void
  Reserve(ElementIdentifier size);
 
#ifndef ITK_FUTURE_LEGACY_REMOVE
  ITK_FUTURE_DEPRECATED("Please consider calling `std::make_unique<TValue[]>(size)` instead.")
  [[nodiscard]] TValue *
  AllocateElements(ElementIdentifier size) const;
#endif
 
  [[nodiscard]] const TValue *
  GetDataPointer() const
  {
    return m_Data;
  }

  Self &
  operator--()
  {
    for (ElementIdentifier i = 0; i < m_NumElements; ++i)
    {
      this->m_Data[i] -= static_cast<ValueType>(1.0);
    }
    return *this;
  }

  Self &
  operator++() // prefix operator ++v;
  {
    for (ElementIdentifier i = 0; i < m_NumElements; ++i)
    {
      this->m_Data[i] += static_cast<ValueType>(1.0);
    }
    return *this;
  }

  Self
  operator--(int) // postfix operator v--;
  {
    Self tmp(*this);
 
    --tmp;
    return tmp;
  }

  Self
  operator++(int) // postfix operator v++;
  {
    Self tmp(*this);
 
    ++tmp;
    return tmp;
  }

  template <typename T>
  Self &
  operator-=(const VariableLengthVector<T> & v)
  {
    itkAssertInDebugAndIgnoreInReleaseMacro(m_NumElements == v.GetSize());
    for (ElementIdentifier i = 0; i < m_NumElements; ++i)
    {
      m_Data[i] -= static_cast<ValueType>(v[i]);
    }
    return *this;
  }

  Self &
  operator-=(TValue s)
  {
    for (ElementIdentifier i = 0; i < m_NumElements; ++i)
    {
      m_Data[i] -= s;
    }
    return *this;
  }

  template <typename T>
  Self &
  operator+=(const VariableLengthVector<T> & v)
  {
    itkAssertInDebugAndIgnoreInReleaseMacro(m_NumElements == v.GetSize());
    for (ElementIdentifier i = 0; i < m_NumElements; ++i)
    {
      m_Data[i] += static_cast<ValueType>(v[i]);
    }
    return *this;
  }

  Self &
  operator+=(TValue s)
  {
    for (ElementIdentifier i = 0; i < m_NumElements; ++i)
    {
      m_Data[i] += s;
    }
    return *this;
  }

  template <typename TExpr1, typename TExpr2, typename TBinaryOp>
  Self &
  operator+=(const VariableLengthVectorExpression<TExpr1, TExpr2, TBinaryOp> & rhs)
  {
    itkAssertInDebugAndIgnoreInReleaseMacro(rhs.Size() == Size());
    for (ElementIdentifier i = 0; i < m_NumElements; ++i)
    {
      m_Data[i] += static_cast<ValueType>(rhs[i]);
    }
    return *this;
  }

  template <typename TExpr1, typename TExpr2, typename TBinaryOp>
  Self &
  operator-=(const VariableLengthVectorExpression<TExpr1, TExpr2, TBinaryOp> & rhs)
  {
    itkAssertInDebugAndIgnoreInReleaseMacro(rhs.Size() == Size());
    for (ElementIdentifier i = 0; i < m_NumElements; ++i)
    {
      m_Data[i] -= static_cast<ValueType>(rhs[i]);
    }
    return *this;
  }

  template <typename T>
  Self &
  operator*=(T s)
  {
    const ValueType & sc = static_cast<ValueType>(s);
    for (ElementIdentifier i = 0; i < m_NumElements; ++i)
    {
      m_Data[i] *= sc;
    }
    return *this;
  }

  Self &
  operator*=(TValue s)
  {
    for (ElementIdentifier i = 0; i < m_NumElements; ++i)
    {
      m_Data[i] *= s;
    }
    return *this;
  }

  template <typename T>
  Self &
  operator/=(T s)
  {
    const RealValueType sc = s;
    for (ElementIdentifier i = 0; i < m_NumElements; ++i)
    {
      m_Data[i] = static_cast<ValueType>(static_cast<RealValueType>(m_Data[i]) / sc);
    }
    return *this;
  }

  Self &
  operator-(); // negation operator
 
  bool
  operator==(const Self & v) const;
 
  ITK_UNEQUAL_OPERATOR_MEMBER_FUNCTION(Self);

  [[nodiscard]] RealValueType
  GetNorm() const;

  [[nodiscard]] RealValueType
  GetSquaredNorm() const;

  [[nodiscard]] bool
  IsAProxy() const
  {
    return !m_LetArrayManageMemory;
  }
 
  [[nodiscard]] bool
  empty() const noexcept
  {
    return m_NumElements == 0;
  }
 
  [[nodiscard]] size_type
  size() const noexcept
  {
    return m_NumElements;
  }
 
  [[nodiscard]] reference
  at(size_type pos)
  {
    ExceptionThrowingBoundsCheck(pos);
    return m_Data[pos];
  }
 
  [[nodiscard]] const_reference
  at(size_type pos) const
  {
    ExceptionThrowingBoundsCheck(pos);
    return m_Data[pos];
  }
 
  [[nodiscard]] reference
  front()
  {
    return m_Data[0];
  }
 
  [[nodiscard]] const_reference
  front() const
  {
    return m_Data[0];
  }
 
  [[nodiscard]] reference
  back()
  {
    return m_Data[m_NumElements - 1];
  }
 
  [[nodiscard]] const_reference
  back() const
  {
    return m_Data[m_NumElements - 1];
  }
 
  [[nodiscard]] TValue *
  data() noexcept
  {
    return m_Data;
  }
 
  [[nodiscard]] const TValue *
  data() const noexcept
  {
    return m_Data;
  }
 
  [[nodiscard]] const_iterator
  cbegin() const noexcept
  {
    return m_Data;
  }
 
  [[nodiscard]] iterator
  begin() noexcept
  {
    return m_Data;
  }
 
  [[nodiscard]] const_iterator
  begin() const noexcept
  {
    return cbegin();
  }
 
  [[nodiscard]] const_iterator
  cend() const noexcept
  {
    return m_Data + m_NumElements;
  }
 
  [[nodiscard]] iterator
  end() noexcept
  {
    return m_Data + m_NumElements;
  }
 
  [[nodiscard]] const_iterator
  end() const noexcept
  {
    return cend();
  }
 
  [[nodiscard]] reverse_iterator
  rbegin()
  {
    return reverse_iterator{ end() };
  }
 
  [[nodiscard]] const_reverse_iterator
  crbegin() const
  {
    return const_reverse_iterator{ cend() };
  }
 
  [[nodiscard]] const_reverse_iterator
  rbegin() const
  {
    return crbegin();
  }
 
  [[nodiscard]] reverse_iterator
  rend()
  {
    return reverse_iterator{ begin() };
  }
 
  [[nodiscard]] const_reverse_iterator
  crend() const
  {
    return const_reverse_iterator{ cbegin() };
  }
 
  [[nodiscard]] const_reverse_iterator
  rend() const
  {
    return crend();
  }
 
private:
  bool m_LetArrayManageMemory{ true }; // if true, the array is responsible
                                       // for memory of data
  TValue *          m_Data{};          // Array to hold data
  ElementIdentifier m_NumElements{ 0 };
 
  void
  ExceptionThrowingBoundsCheck(size_type pos) const
  {
    if (pos >= m_NumElements)
    {
      throw std::out_of_range("Out of range: `itk::VariableLengthVector::at` argument `pos` (which is " +
                              std::to_string(pos) + ") should be less than `m_NumElements` (which is " +
                              std::to_string(m_NumElements) + ")!");
    }
  }
};

namespace mpl
{
template <typename T>
struct IsArray : FalseType
{};

template <typename T>
struct IsArray<itk::VariableLengthVector<T>> : TrueType
{};
 
template <typename TExpr1, typename TExpr2, typename TBinaryOp>
struct IsArray<VariableLengthVectorExpression<TExpr1, TExpr2, TBinaryOp>> : TrueType
{};
} // namespace mpl
 
namespace Details
{

template <typename TExpr>
struct GetType
{
  using Type = TExpr;

  static Type
  Load(const Type & v, unsigned int itkNotUsed(idx))
  {
    return v;
  }
};

template <typename TExpr1, typename TExpr2>
inline std::enable_if_t<mpl::And<mpl::IsArray<TExpr1>, mpl::IsArray<TExpr2>>::Value, unsigned int>
GetSize(const TExpr1 & lhs, [[maybe_unused]] const TExpr2 & rhs)
{
  itkAssertInDebugAndIgnoreInReleaseMacro(lhs.Size() == rhs.Size());
  return lhs.Size();
}


template <typename TExpr1, typename TExpr2>
inline std::enable_if_t<mpl::And<mpl::IsArray<TExpr1>, mpl::Not<mpl::IsArray<TExpr2>>>::Value, unsigned int>
GetSize(const TExpr1 & lhs, const TExpr2 & itkNotUsed(rhs))
{
  return lhs.Size();
}

template <typename TExpr1, typename TExpr2>
inline std::enable_if_t<mpl::And<mpl::IsArray<TExpr2>, mpl::Not<mpl::IsArray<TExpr1>>>::Value, unsigned int>
GetSize(const TExpr1 & itkNotUsed(lhs), const TExpr2 & rhs)
{
  return rhs.Size();
}
 
template <typename T>
struct GetType<VariableLengthVector<T>>
{
  using Type = T;
  static Type
  Load(const VariableLengthVector<T> & v, unsigned int idx)
  {
    return v[idx];
  }
};
template <typename TExpr1, typename TExpr2, typename TBinaryOp>
struct GetType<VariableLengthVectorExpression<TExpr1, TExpr2, TBinaryOp>>
{
  using Type = typename VariableLengthVectorExpression<TExpr1, TExpr2, TBinaryOp>::ResType;
  static Type
  Load(const VariableLengthVectorExpression<TExpr1, TExpr2, TBinaryOp> & v, unsigned int idx)
  {
    return v[idx];
  }
};
 
namespace op
{
template <typename TExpr1, typename TExpr2>
struct CanBeAddedOrSubtracted
  : mpl::Or<mpl::And<mpl::IsArray<TExpr1>, mpl::IsArray<TExpr2>>,
            mpl::And<mpl::IsArray<TExpr1>, mpl::IsNumber<TExpr2>>,
            mpl::And<mpl::IsNumber<TExpr1>, mpl::IsArray<TExpr2>>>
{};

template <typename TExpr1, typename TExpr2>
struct CanBeMultiplied
  : mpl::Or<mpl::And<mpl::IsArray<TExpr1>, mpl::IsNumber<TExpr2>>,
            mpl::And<mpl::IsNumber<TExpr1>, mpl::IsArray<TExpr2>>>
{};

template <typename TExpr1, typename TExpr2>
struct CanBeDivided : mpl::And<mpl::IsArray<TExpr1>, mpl::IsNumber<TExpr2>>
{};
 
} // namespace op
} // namespace Details

template <typename TExpr1, typename TExpr2, typename TBinaryOp>
struct VariableLengthVectorExpression
{
  VariableLengthVectorExpression(const TExpr1 & lhs, const TExpr2 & rhs)
    : m_lhs(lhs)
    , m_rhs(rhs)
  {
    // Not necessary actually as end-user/developer is not expected to
    // provide new BinaryOperations
    static_assert(std::is_base_of_v<Details::op::BinaryOperationConcept, TBinaryOp>,
                  "The Binary Operation shall inherit from BinaryOperationConcept");
  }

  [[nodiscard]] unsigned int
  Size() const
  {
    return Details::GetSize(m_lhs, m_rhs);
  }

  using ResType =
    typename mpl::PromoteType<typename Details::GetType<TExpr1>::Type, typename Details::GetType<TExpr2>::Type>::Type;
  using RealValueType = typename NumericTraits<ResType>::RealType;

  ResType
  operator[](unsigned int idx) const
  {
    itkAssertInDebugAndIgnoreInReleaseMacro(idx < Size());
    return TBinaryOp::Apply(Details::GetType<TExpr1>::Load(m_lhs, idx), Details::GetType<TExpr2>::Load(m_rhs, idx));
  }

  [[nodiscard]] RealValueType
  GetNorm() const;

  [[nodiscard]] RealValueType
  GetSquaredNorm() const;
 
private:
  const TExpr1 & m_lhs;
  const TExpr2 & m_rhs;
};

template <typename TExpr1, typename TExpr2>
inline std::enable_if_t<Details::op::CanBeAddedOrSubtracted<TExpr1, TExpr2>::Value,
                        VariableLengthVectorExpression<TExpr1, TExpr2, Details::op::Plus>>
operator+(const TExpr1 & lhs, const TExpr2 & rhs)
{
  return VariableLengthVectorExpression<TExpr1, TExpr2, Details::op::Plus>(lhs, rhs);
}

template <typename TExpr1, typename TExpr2>
inline std::enable_if_t<Details::op::CanBeAddedOrSubtracted<TExpr1, TExpr2>::Value,
                        VariableLengthVectorExpression<TExpr1, TExpr2, Details::op::Sub>>
operator-(const TExpr1 & lhs, const TExpr2 & rhs)
{
  return VariableLengthVectorExpression<TExpr1, TExpr2, Details::op::Sub>(lhs, rhs);
}

template <typename TExpr1, typename TExpr2>
inline std::enable_if_t<Details::op::CanBeMultiplied<TExpr1, TExpr2>::Value,
                        VariableLengthVectorExpression<TExpr1, TExpr2, Details::op::Mult>>
operator*(const TExpr1 & lhs, const TExpr2 & rhs)
{
  return VariableLengthVectorExpression<TExpr1, TExpr2, Details::op::Mult>(lhs, rhs);
}

template <typename TExpr1, typename TExpr2>
inline std::enable_if_t<Details::op::CanBeDivided<TExpr1, TExpr2>::Value,
                        VariableLengthVectorExpression<TExpr1, TExpr2, Details::op::Div>>
operator/(const TExpr1 & lhs, const TExpr2 & rhs)
{
  return VariableLengthVectorExpression<TExpr1, TExpr2, Details::op::Div>(lhs, rhs);
}

template <typename TExpr1, typename TExpr2, typename TBinaryOp>
std::ostream &
operator<<(std::ostream & os, const VariableLengthVectorExpression<TExpr1, TExpr2, TBinaryOp> & v)
{
  os << '[';
  if (v.Size() != 0)
  {
    os << v[0];
    for (unsigned int i = 1, N = v.Size(); i != N; ++i)
    {
      os << ", " << v[i];
    }
  }
  return os << ']';
}

template <typename TExpr>
inline std::enable_if_t<mpl::IsArray<TExpr>::Value, typename TExpr::RealValueType>
GetNorm(const TExpr & v)
{
  return static_cast<typename TExpr::RealValueType>(std::sqrt(static_cast<double>(GetSquaredNorm(v))));
}

template <typename TExpr>
inline std::enable_if_t<mpl::IsArray<TExpr>::Value, typename TExpr::RealValueType>
GetSquaredNorm(const TExpr & v)
{
  using RealValueType = typename TExpr::RealValueType;
  RealValueType sum = 0.0;
  for (unsigned int i = 0, N = v.Size(); i < N; ++i)
  {
    const RealValueType value = v[i];
    sum += value * value;
  }
  return sum;
}


template <typename TValue>
std::ostream &
operator<<(std::ostream & os, const VariableLengthVector<TValue> & arr)
{
  const unsigned int length = arr.Size();
  const int          last = static_cast<unsigned int>(length) - 1;
 
  os << '[';
  for (int i = 0; i < last; ++i)
  {
    os << arr[i] << ", ";
  }
  if (length >= 1)
  {
    os << arr[last];
  }
  os << ']';
  return os;
}


template <typename T>
inline void
swap(VariableLengthVector<T> & l_, VariableLengthVector<T> & r_) noexcept
{
  l_.Swap(r_);
}
 
} // namespace itk
 
#include "itkNumericTraitsVariableLengthVectorPixel.h"
 
#ifndef ITK_MANUAL_INSTANTIATION
#  include "itkVariableLengthVector.hxx"
#endif
 
#endif