libcamera: utils: Add enumerate view for range-based for loops

Range-based for loops are handy and widely preferred in C++, but are
limited in their ability to replace for loops that require access to a
loop counter.  The enumerate() function solves this problem by wrapping
the iterable in an adapter that, when used as a range-expression, will
provide iterators whose value_type is a pair of index and value
reference.

The iterable must support std::begin() and std::end(). This includes all
containers provided by the standard C++ library, as well as C-style
arrays.

A typical usage pattern would use structured binding to store the index
and value in two separate variables:

std::vector<int> values = ...;

for (auto [index, value] : utils::enumerate(values)) {
     ...
}

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>

test/utils.cpp

@@ -12,6 +12,7 @@
 #include <vector>
 
 #include <libcamera/geometry.h>
+#include <libcamera/span.h>
 
 #include "libcamera/internal/utils.h"
 
@@ -73,6 +74,60 @@ protected:
 		return TestPass;
 	}
 
+	int testEnumerate()
+	{
+		std::vector<int> integers{ 1, 2, 3, 4, 5 };
+		int i = 0;
+
+		for (auto [index, value] : utils::enumerate(integers)) {
+			if (index != i || value != i + 1) {
+				cerr << "utils::enumerate(<vector>) test failed: i=" << i
+				     << ", index=" << index << ", value=" << value
+				     << std::endl;
+				return TestFail;
+			}
+
+			/* Verify that we can modify the value. */
+			--value;
+			++i;
+		}
+
+		if (integers != std::vector<int>{ 0, 1, 2, 3, 4 }) {
+			cerr << "Failed to modify container in enumerated range loop" << endl;
+			return TestFail;
+		}
+
+		Span<const int> span{ integers };
+		i = 0;
+
+		for (auto [index, value] : utils::enumerate(span)) {
+			if (index != i || value != i) {
+				cerr << "utils::enumerate(<span>) test failed: i=" << i
+				     << ", index=" << index << ", value=" << value
+				     << std::endl;
+				return TestFail;
+			}
+
+			++i;
+		}
+
+		const int array[] = { 0, 2, 4, 6, 8 };
+		i = 0;
+
+		for (auto [index, value] : utils::enumerate(array)) {
+			if (index != i || value != i * 2) {
+				cerr << "utils::enumerate(<array>) test failed: i=" << i
+				     << ", index=" << index << ", value=" << value
+				     << std::endl;
+				return TestFail;
+			}
+
+			++i;
+		}
+
+		return TestPass;
+	}
+
 	int run()
 	{
 		/* utils::hex() test. */
@@ -177,6 +232,10 @@ protected:
 			return TestFail;
 		}
 
+		/* utils::enumerate() test. */
+		if (testEnumerate() != TestPass)
+			return TestFail;
+
 		return TestPass;
 	}
 };