ENH: Add std::vector-like interface to VariableLengthVector

Added the following member functions:

     empty()
     size()
     at(size_type)
     front()
     back()
     data()
     begin()
     end()
     cbegin()
     cend()
     rbegin()
     rend()
     crbegin()
     crend()

As well as STL-style nested type aliases.

Aims to ease using `VariableLengthVector` in generic code.

Author: N-Dekker

Modules/Core/Common/include/itkVariableLengthVector.h

@@ -20,6 +20,7 @@
 
 #include <cassert>
 #include <algorithm>
+#include <iterator>
 #include <type_traits>
 #include "itkNumericTraits.h"
 #include "itkMetaProgrammingLibrary.h"
@@ -314,6 +315,17 @@ class ITK_TEMPLATE_EXPORT VariableLengthVector
   /** Typedef used to indicate the number of elements in the vector */
   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>;
+
   /** Default constructor. It is created with an empty array
    *  it has to be allocated later by assignment, \c SetSize() or \c Reserve().
    * \post \c m_Data is null
@@ -983,11 +995,156 @@ class ITK_TEMPLATE_EXPORT VariableLengthVector
     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)
+  {
+    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) + ")!");
+    }
+  }
 };
 
 /// \cond HIDE_META_PROGRAMMING

Modules/Core/Common/test/CMakeLists.txt

@@ -1902,6 +1902,7 @@ set(
   itkSizeGTest.cxx
   itkSmartPointerGTest.cxx
   itkSymmetricSecondRankTensorGTest.cxx
+  itkVariableLengthVectorGTest.cxx
   itkVectorContainerGTest.cxx
   itkVectorGTest.cxx
   itkWeakPointerGTest.cxx

Modules/Core/Common/test/itkRangeGTestUtilities.h

@@ -41,6 +41,15 @@ class RangeGTestUtilities
   }
 
 
+  template <typename TRange>
+  static void
+  ExpectReverseBeginIsReverseEndWhenRangeIsDefaultConstructed()
+  {
+    TRange defaultConstructedRange;
+    EXPECT_EQ(std::rbegin(defaultConstructedRange), std::rend(defaultConstructedRange));
+  }
+
+
   template <typename TRange>
   static void
   ExpectZeroSizeWhenRangeIsDefaultConstructed()
@@ -156,6 +165,55 @@ class RangeGTestUtilities
   }
 
 
+  // Checks the nested types that are required according to the C++ Standard section "Container requirements"
+  // [container.reqmts].
+  template <typename TContainer, typename TValue = typename TContainer::ValueType>
+  static constexpr bool
+  CheckContainerRequirementsOnNestedTypes()
+  {
+    AssertSameType<typename TContainer::value_type, TValue>();
+    AssertSameType<typename TContainer::reference, TValue &>();
+    AssertSameType<typename TContainer::const_reference, const TValue &>();
+
+    // The C++ Standard requires that "the type `iterator` is convertible to `const_iterator`".
+    static_assert(std::is_convertible_v<typename TContainer::iterator, typename TContainer::const_iterator>);
+
+    using difference_type = typename TContainer::difference_type;
+    using size_type = typename TContainer::size_type;
+
+    static_assert(std::is_signed_v<difference_type>);
+    static_assert(std::is_integral_v<difference_type>);
+
+    // `size_type` must be "an unsigned integer type that can represent any non-negative value of `difference_type`."
+    static_assert(std::is_unsigned_v<size_type>);
+    static_assert(sizeof(size_type) >= sizeof(difference_type));
+    return true;
+  }
+
+
+  // Expects that `distance(begin, end)` is equal to `size`, for the specified container.
+  template <typename TContainer>
+  static void
+  ExpectDistanceFromBeginToEndEqualsSize(const TContainer & container)
+  {
+    const auto distance = std::distance(std::begin(container), std::end(container));
+    ASSERT_GE(distance, 0);
+    EXPECT_EQ(static_cast<size_t>(distance), std::size(container));
+  }
+
+
+  // Expects that `distance(&front, &back) + 1` is equal to `size`, for the specified (non-empty) container.
+  template <typename TContainer>
+  static void
+  ExpectDistanceFromFrontToBackPlusOneEqualsSize(const TContainer & container)
+  {
+    ASSERT_FALSE(std::empty(container));
+    const auto distance = std::distance(&container.front(), &container.back());
+    ASSERT_GE(distance, 0);
+    EXPECT_EQ(static_cast<size_t>(distance + 1), std::size(container));
+  }
+
+
   // Tells if `distance(&front, &back) + 1` is equal to `size`, for the specified container.
   template <typename TContainer>
   static constexpr bool
@@ -177,6 +235,13 @@ class RangeGTestUtilities
   }
 
 private:
+  template <typename T1, typename T2>
+  static constexpr void
+  AssertSameType()
+  {
+    static_assert(std::is_same_v<T1, T2>);
+  }
+
   template <typename TRange>
   static void
   ExpectRangesHaveEqualBeginAndEnd(const TRange & range1, const TRange & range2)