Document that Iterator(image, region) constructors initialize at the begin, add GTest unit test

Modules/Core/Common/include/itkImageConstIterator.h

@@ -163,8 +163,8 @@ class ITK_TEMPLATE_EXPORT ImageConstIterator
     m_PixelAccessorFunctor.SetBegin(m_Buffer);
   }
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageConstIterator(const ImageType * ptr, const RegionType & region)
   {
     m_Image = ptr;

Modules/Core/Common/include/itkImageConstIteratorWithIndex.h

@@ -144,8 +144,8 @@ class ITK_TEMPLATE_EXPORT ImageConstIteratorWithIndex
    * handle to the image is properly reference counted. */
   ImageConstIteratorWithIndex(const Self & it);
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageConstIteratorWithIndex(const TImage * ptr, const RegionType & region);
 
   /** Default Destructor. */

Modules/Core/Common/include/itkImageConstIteratorWithOnlyIndex.h

@@ -128,8 +128,8 @@ class ITK_TEMPLATE_EXPORT ImageConstIteratorWithOnlyIndex
    * provide a copy constructor. */
   ImageConstIteratorWithOnlyIndex() = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageConstIteratorWithOnlyIndex(const TImage * ptr, const RegionType & region);
 
   /** Default Destructor. */

Modules/Core/Common/include/itkImageIterator.h

@@ -98,8 +98,8 @@ class ITK_TEMPLATE_EXPORT ImageIterator : public ImageConstIterator<TImage>
   /** Default Destructor */
   ~ImageIterator() override = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageIterator(TImage * ptr, const RegionType & region);
 
   /** Set the pixel value */

Modules/Core/Common/include/itkImageIteratorWithIndex.h

@@ -101,8 +101,8 @@ class ITK_TEMPLATE_EXPORT ImageIteratorWithIndex : public ImageConstIteratorWith
   /** Default Destructor */
   ~ImageIteratorWithIndex() override = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageIteratorWithIndex(TImage * ptr, const RegionType & region);
 
   /** Set the pixel value */

Modules/Core/Common/include/itkImageLinearConstIteratorWithIndex.h

@@ -135,8 +135,8 @@ class ITK_TEMPLATE_EXPORT ImageLinearConstIteratorWithIndex : public ImageConstI
 
   {}
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageLinearConstIteratorWithIndex(const ImageType * ptr, const RegionType & region);
 
   /** Constructor that can be used to cast from an ImageIterator to an

Modules/Core/Common/include/itkImageLinearIteratorWithIndex.h

@@ -86,8 +86,8 @@ class ITK_TEMPLATE_EXPORT ImageLinearIteratorWithIndex : public ImageLinearConst
   /** Default constructor. Needed since we provide a cast constructor. */
   ImageLinearIteratorWithIndex() = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageLinearIteratorWithIndex(ImageType * ptr, const RegionType & region);
 
   /** Constructor that can be used to cast from an ImageIterator to an

Modules/Core/Common/include/itkImageRegionConstIterator.h

@@ -146,8 +146,8 @@ class ITK_TEMPLATE_EXPORT ImageRegionConstIterator : public ImageConstIterator<T
     m_SpanEndOffset = 0;
   }
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageRegionConstIterator(const ImageType * ptr, const RegionType & region)
     : ImageConstIterator<TImage>(ptr, region)
   {

Modules/Core/Common/include/itkImageRegionConstIteratorWithIndex.h

@@ -155,8 +155,8 @@ class ITK_TEMPLATE_EXPORT ImageRegionConstIteratorWithIndex : public ImageConstI
     : ImageConstIteratorWithIndex<TImage>()
   {}
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageRegionConstIteratorWithIndex(const TImage * ptr, const RegionType & region)
     : ImageConstIteratorWithIndex<TImage>(ptr, region)
   {}

Modules/Core/Common/include/itkImageRegionConstIteratorWithOnlyIndex.h

@@ -151,8 +151,8 @@ class ITK_TEMPLATE_EXPORT ImageRegionConstIteratorWithOnlyIndex : public ImageCo
     : ImageConstIteratorWithOnlyIndex<TImage>()
   {}
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageRegionConstIteratorWithOnlyIndex(const TImage * ptr, const RegionType & region)
     : ImageConstIteratorWithOnlyIndex<TImage>(ptr, region)
   {}

Modules/Core/Common/include/itkImageRegionExclusionConstIteratorWithIndex.h

@@ -150,8 +150,8 @@ class ITK_TEMPLATE_EXPORT ImageRegionExclusionConstIteratorWithIndex : public Im
   /** Default constructor. Needed since we provide a cast constructor. */
   ImageRegionExclusionConstIteratorWithIndex() = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageRegionExclusionConstIteratorWithIndex(const ImageType * ptr, const RegionType & region);
 
   /** Constructor that can be used to cast from an ImageRegionConstIteratorWithIndex

Modules/Core/Common/include/itkImageRegionExclusionIteratorWithIndex.h

@@ -87,8 +87,8 @@ class ITK_TEMPLATE_EXPORT ImageRegionExclusionIteratorWithIndex
   /** Default constructor. Needed since we provide a cast constructor. */
   ImageRegionExclusionIteratorWithIndex() = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageRegionExclusionIteratorWithIndex(ImageType * ptr, const RegionType & region);
 
   /** Constructor that can be used to cast from an ImageIterator to an

Modules/Core/Common/include/itkImageRegionIterator.h

@@ -99,8 +99,8 @@ class ITK_TEMPLATE_EXPORT ImageRegionIterator : public ImageRegionConstIterator<
   /** Default constructor. Needed since we provide a cast constructor. */
   ImageRegionIterator() = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageRegionIterator(ImageType * ptr, const RegionType & region);
 
   /** Constructor that can be used to cast from an ImageIterator to an

Modules/Core/Common/include/itkImageRegionIteratorWithIndex.h

@@ -92,8 +92,8 @@ class ITK_TEMPLATE_EXPORT ImageRegionIteratorWithIndex : public ImageRegionConst
   /** Default constructor. Needed since we provide a cast constructor. */
   ImageRegionIteratorWithIndex() = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageRegionIteratorWithIndex(TImage * ptr, const RegionType & region);
 
   /** Constructor that can be used to cast from an ImageIterator to an

Modules/Core/Common/include/itkImageRegionReverseConstIterator.h

@@ -153,8 +153,8 @@ class ITK_TEMPLATE_EXPORT ImageRegionReverseConstIterator : public ImageReverseC
     m_SpanEndOffset = 0;
   }
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageRegionReverseConstIterator(const ImageType * ptr, const RegionType & region)
     : Superclass(ptr, region)
   {

Modules/Core/Common/include/itkImageRegionReverseIterator.h

@@ -88,8 +88,8 @@ class ITK_TEMPLATE_EXPORT ImageRegionReverseIterator : public ImageRegionReverse
   /** Default constructor. Needed since we provide a cast constructor. */
   ImageRegionReverseIterator() = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageRegionReverseIterator(ImageType * ptr, const RegionType & region);
 
   /** Constructor that can be used to cast from an ImageConstIterator to an

Modules/Core/Common/include/itkImageReverseConstIterator.h

@@ -166,8 +166,8 @@ class ITK_TEMPLATE_EXPORT ImageReverseConstIterator
     m_PixelAccessorFunctor.SetBegin(m_Buffer);
   }
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageReverseConstIterator(const ImageType * ptr, const RegionType & region)
   {
     SizeValueType offset;

Modules/Core/Common/include/itkImageReverseIterator.h

@@ -84,8 +84,8 @@ class ITK_TEMPLATE_EXPORT ImageReverseIterator : public ImageRegionReverseConstI
   /** Default constructor. Needed since we provide a cast constructor. */
   ImageReverseIterator() = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageReverseIterator(ImageType * ptr, const RegionType & region);
 
   /** Constructor that can be used to cast from an ImageIterator to an

Modules/Core/Common/include/itkImageScanlineConstIterator.h

@@ -101,8 +101,8 @@ class ITK_TEMPLATE_EXPORT ImageScanlineConstIterator : public ImageConstIterator
     m_SpanEndOffset = 0;
   }
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageScanlineConstIterator(const TImage * ptr, const RegionType & region)
     : ImageConstIterator<TImage>(ptr, region)
   {

Modules/Core/Common/include/itkImageScanlineIterator.h

@@ -61,8 +61,8 @@ class ITK_TEMPLATE_EXPORT ImageScanlineIterator : public ImageScanlineConstItera
   /** Default constructor. Needed since we provide a cast constructor. */
   ImageScanlineIterator() = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageScanlineIterator(TImage * ptr, const RegionType & region);
 
   /** Constructor that can be used to cast from an ImageIterator to an

Modules/Core/Common/include/itkImageSliceConstIteratorWithIndex.h

@@ -134,8 +134,8 @@ class ITK_TEMPLATE_EXPORT ImageSliceConstIteratorWithIndex : public ImageConstIt
     : ImageConstIteratorWithIndex<TImage>()
   {}
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageSliceConstIteratorWithIndex(const ImageType * ptr, const RegionType & region)
     : ImageConstIteratorWithIndex<TImage>(ptr, region)
     , m_PixelJump(0)

Modules/Core/Common/include/itkImageSliceIteratorWithIndex.h

@@ -88,8 +88,8 @@ class ITK_TEMPLATE_EXPORT ImageSliceIteratorWithIndex : public ImageSliceConstIt
   /** Default constructor. Needed since we provide a cast constructor. */
   ImageSliceIteratorWithIndex() = default;
 
-  /** Constructor establishes an iterator to walk a particular image and a
-   * particular region of that image. */
+  /** Constructor establishes an iterator to walk a particular image and a particular region of that image. Initializes
+   * the iterator at the begin of the region. */
   ImageSliceIteratorWithIndex(ImageType * ptr, const RegionType & region);
 
   /** Constructor that can be used to cast from an ImageIterator to an

Modules/Core/Common/test/CMakeLists.txt

@@ -1735,6 +1735,7 @@ set(ITKCommonGTests
     itkImageIORegionGTest.cxx
     itkImageRandomConstIteratorWithIndexGTest.cxx
     itkImageRegionGTest.cxx
+    itkImageRegionIteratorGTest.cxx
     itkIndexGTest.cxx
     itkIndexRangeGTest.cxx
     itkLightObjectGTest.cxx

Modules/Core/Common/test/itkImageRegionIteratorGTest.cxx

@@ -0,0 +1,136 @@
+/*=========================================================================
+ *
+ *  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.
+ *
+ *=========================================================================*/
+
+// First include the header files to be tested:
+#include "itkImageConstIterator.h"
+#include "itkImageConstIteratorWithIndex.h"
+#include "itkImageConstIteratorWithOnlyIndex.h"
+#include "itkImageIterator.h"
+#include "itkImageIteratorWithIndex.h"
+#include "itkImageLinearConstIteratorWithIndex.h"
+#include "itkImageLinearIteratorWithIndex.h"
+#include "itkImageRegionConstIterator.h"
+#include "itkImageRegionConstIteratorWithIndex.h"
+#include "itkImageRegionConstIteratorWithOnlyIndex.h"
+#include "itkImageRegionExclusionConstIteratorWithIndex.h"
+#include "itkImageRegionExclusionIteratorWithIndex.h"
+#include "itkImageRegionIterator.h"
+#include "itkImageRegionIteratorWithIndex.h"
+#include "itkImageRegionReverseConstIterator.h"
+#include "itkImageRegionReverseIterator.h"
+#include "itkImageReverseConstIterator.h"
+#include "itkImageReverseIterator.h"
+#include "itkImageScanlineConstIterator.h"
+#include "itkImageScanlineIterator.h"
+#include "itkImageSliceConstIteratorWithIndex.h"
+#include "itkImageSliceIteratorWithIndex.h"
+
+#include "itkImage.h"
+#include <gtest/gtest.h>
+#include <type_traits> // For false_type and true_type.
+
+namespace
+{
+// Has_IsAtBegin tells whether the specified iterator type has an `IsAtBegin()` member function, returning a `bool`. It
+// is inspired by "How to detect whether there is a specific member variable in class?", answered by Andy Prowl, Jan 25,
+// 2013 at https://stackoverflow.com/a/14523787 (the `has_id` example).
+template <typename TIterator, typename = bool>
+struct Has_IsAtBegin : std::false_type
+{};
+
+template <typename TIterator>
+struct Has_IsAtBegin<TIterator, decltype(std::declval<TIterator>().IsAtBegin())> : std::true_type
+{};
+
+
+template <typename TIterator>
+void
+CheckConstructedAtBegin()
+{
+  using ImageType = typename TIterator::ImageType;
+  using IndexType = typename TIterator::IndexType;
+  using SizeType = typename TIterator::SizeType;
+  using RegionType = typename TIterator::RegionType;
+
+  const auto image = ImageType::New();
+
+  // Use a small image size, so that the unit test won't take a long time.
+  static constexpr itk::SizeValueType imageSizeValue{ 4 };
+
+  image->SetRegions(SizeType::Filled(imageSizeValue));
+  image->Allocate();
+
+  // Check various regions, specified by the following `indexValue` and `sizeValue` combinations:
+  for (const itk::IndexValueType indexValue : { 0, 1 })
+  {
+    for (const auto sizeValue : { itk::SizeValueType{ 1 }, imageSizeValue - 1 })
+    {
+      const RegionType imageRegion(IndexType::Filled(indexValue), SizeType::Filled(sizeValue));
+
+      const TIterator iterator(image, imageRegion);
+      TIterator       iteratorThatGoesToBegin = iterator;
+      iteratorThatGoesToBegin.GoToBegin();
+      EXPECT_EQ(iterator, iteratorThatGoesToBegin);
+
+      if constexpr (Has_IsAtBegin<TIterator>::value)
+      {
+        // Extra check, using IsAtBegin(), if the iterator has that member function. (Some iterators
+        // do not have an IsAtBegin() member function, for example, ImageRegionConstIteratorWithIndex.)
+        EXPECT_TRUE(TIterator(image, imageRegion).IsAtBegin());
+      }
+    }
+  }
+}
+
+
+template <template <typename> typename... TIteratorTemplate>
+void
+CheckIteratorsConstructedAtBegin()
+{
+  (CheckConstructedAtBegin<TIteratorTemplate<itk::Image<int>>>(), ...);
+  (CheckConstructedAtBegin<TIteratorTemplate<itk::Image<double, 3>>>(), ...);
+}
+} // namespace
+
+
+// Checks that an iterator that is just constructed by `IteratorType(image, region)` is at the begin.
+TEST(ImageRegionIterator, IsConstructedAtBegin)
+{
+  CheckIteratorsConstructedAtBegin<itk::ImageConstIterator,
+                                   itk::ImageConstIteratorWithIndex,
+                                   itk::ImageConstIteratorWithOnlyIndex,
+                                   itk::ImageIterator,
+                                   itk::ImageIteratorWithIndex,
+                                   itk::ImageLinearConstIteratorWithIndex,
+                                   itk::ImageLinearIteratorWithIndex,
+                                   itk::ImageRegionConstIterator,
+                                   itk::ImageRegionConstIteratorWithIndex,
+                                   itk::ImageRegionConstIteratorWithOnlyIndex,
+                                   itk::ImageRegionExclusionConstIteratorWithIndex,
+                                   itk::ImageRegionExclusionIteratorWithIndex,
+                                   itk::ImageRegionIterator,
+                                   itk::ImageRegionIteratorWithIndex,
+                                   itk::ImageRegionReverseConstIterator,
+                                   itk::ImageRegionReverseIterator,
+                                   itk::ImageReverseConstIterator,
+                                   itk::ImageReverseIterator,
+                                   itk::ImageScanlineConstIterator,
+                                   itk::ImageScanlineIterator,
+                                   itk::ImageSliceConstIteratorWithIndex,
+                                   itk::ImageSliceIteratorWithIndex>();
+}