tf::IndexRanges< T, N > Class Template Reference

class to create an N-dimensional index range of integral indices More...

#include <taskflow/utility/iterator.hpp>

Public Types
using	index_type = T
	alias for the index type

Public Member Functions
	IndexRanges ()=default
	constructs an index range without initialization
	IndexRanges (T beg, T end, T step_size)
	constructs a 1D index range (only available when N == 1)
template<typename... Ranges> requires (sizeof...(Ranges) == N) && (std::same_as<std::decay_t<Ranges>, IndexRanges<T, 1>> && ...)
	IndexRanges (Ranges &&... ranges)
	constructs an N-D index range from N 1D ranges
	IndexRanges (const std::array< std::tuple< T, T, T >, N > &dims)
	constructs an index range from an array of (begin, end, step) tuples
const std::tuple< T, T, T > &	dim (size_t d) const
	returns the (begin, end, step) tuple for dimension d (read-only)
std::tuple< T, T, T > &	dim (size_t d)
	returns the (begin, end, step) tuple for dimension d (mutable)
T	begin () const
	queries the starting index of the range (only available when N == 1)
T	end () const
	queries the ending index of the range (only available when N == 1)
T	step_size () const
	queries the step size of the range (only available when N == 1)
IndexRanges &	reset (T beg, T end, T step_size)
	updates the range with a new starting index, ending index, and step size (only available when N == 1)
IndexRanges &	begin (T new_begin)
	updates the starting index of the range (only available when N == 1)
IndexRanges &	end (T new_end)
	updates the ending index of the range (only available when N == 1)
IndexRanges &	step_size (T new_step_size)
	updates the step size of the range (only available when N == 1)
IndexRanges	unravel (size_t part_beg, size_t part_end) const
	maps a contiguous index partition back to the corresponding subrange (only available when N == 1)
size_t	size (size_t d) const
	returns the number of iterations along dimension d
size_t	size () const
	returns the number of active flat iterations
size_t	ceil (size_t chunk_size) const
	returns the smallest hyperplane-aligned chunk size that is >= chunk_size, capped at size() when chunk_size exceeds the total active range size (only available when N > 1)
size_t	floor (size_t chunk_size) const
	returns the largest hyperplane-aligned chunk size that is <= chunk_size (only available when N > 1)
IndexRanges	upper_slice (size_t flat_beg, size_t chunk_size) const
	returns the smallest perfectly-aligned hyperbox reachable from flat_beg, rounding up to the next hyperplane boundary when chunk_size is not aligned (only available when N > 1)
IndexRanges	lower_slice (size_t flat_beg, size_t chunk_size) const
	returns the largest perfectly-aligned hyperbox reachable from flat_beg whose size does not exceed chunk_size, rounding down to the previous hyperplane boundary when chunk_size is not aligned (only available when N > 1)
IndexRanges	empty_box () const
	returns a box whose size() is 0 (only available when N > 1)

Static Public Attributes
static constexpr size_t	rank = N
	the number of dimensions

Detailed Description

template<std::integral T, size_t N = 1>
class tf::IndexRanges< T, N >

class to create an N-dimensional index range of integral indices

Template Parameters

T	the integral type of the indices
N	the number of dimensions (defaults to 1)

This class represents the Cartesian product of N independent 1D index ranges, each defined by a starting index, ending index, and step size. Each dimension is stored as a std::tuple<T, T, T> of (begin, end, step), accessible and mutable through dim(d).

For N == 1, the class behaves like a plain 1D range: tf::IndexRange<T> (an alias for tf::IndexRanges<T, 1>) exposes convenience accessors begin(), end(), step_size(), reset(), and unravel() directly, without going through dim(0).

tf::IndexRange<int> range(0, 10, 2);
for(auto i=range.begin(); i<range.end(); i+=range.step_size()) {
  printf("%d ", i);
}

You can reset the range to a different value using tf::IndexRanges::reset. This is particularly useful when the range value is only known at runtime.

tf::IndexRange<int> range;
range.reset(0, 10, 2);
for(auto i=range.begin(); i<range.end(); i+=range.step_size()) {
  printf("%d ", i);
}

Attention

It is the user's responsibility to ensure the given range is valid. For instance, a range from 0 to 10 with a step size of -2 is invalid.

For N > 1, iteration order is row-major: the last dimension varies fastest, matching the natural nesting of C-style for-loops.

// 3D range: i in [0,4), j in [0,6), k in [0,8), all step 1
tf::IndexRanges<int, 3> r(
  tf::IndexRange<int>(0, 4, 1),
  tf::IndexRange<int>(0, 6, 1),
  tf::IndexRange<int>(0, 8, 1)
);
printf("%zu\n", r.size());  // 4*6*8 = 192

Note

If any dimension has zero size (e.g. an empty range such as [0,0)), the active iteration space stops at that dimension. size() returns the product of all outer dimensions before the first zero, and upper_slice / lower_slice copy the zero-size dimension and all inner dimensions as full extent into each returned sub-box. This matches the behaviour of sequential nested loops:

// Zero in the middle dimension: outer i-loop still runs, j/k body never executes.
tf::IndexRanges<int, 3> r(
  tf::IndexRange<int>(0, 100, 1),   // i: 100 iters (active)
  tf::IndexRange<int>(0,   0, 1),   // j:   0 iters (stops accumulation here)
  tf::IndexRange<int>(0, 100, 1)    // k: 100 iters (inactive — never reached)
);
r.size();  // 100  (only the i-dimension contributes)

Constructor & Destructor Documentation

IndexRanges() [1/4]

template<std::integral T, size_t N = 1>

tf::IndexRanges< T, N >::IndexRanges ( )

default

constructs an index range without initialization

The per-dimension ranges are left in an indeterminate state. Use this when the bounds will be set later via reset() (N==1) or dim(d) (any N).

IndexRanges() [2/4]

template<std::integral T, size_t N = 1>

tf::IndexRanges< T, N >::IndexRanges ( T beg, T end, T step_size )

inlineexplicit

constructs a 1D index range (only available when N == 1)

Parameters

beg	starting index of the range
end	ending index of the range (exclusive)
step_size	step size between consecutive indices in the range

tf::IndexRange<int> range(0, 10, 2);   // elements: 0, 2, 4, 6, 8

IndexRanges() [3/4]

template<std::integral T, size_t N = 1>

template<typename... Ranges>
requires (sizeof...(Ranges) == N) && (std::same_as<std::decay_t<Ranges>, IndexRanges<T, 1>> && ...)

tf::IndexRanges< T, N >::IndexRanges ( Ranges &&... ranges )

inlineexplicit

constructs an N-D index range from N 1D ranges

Parameters

ranges

exactly N 1D ranges (each a tf::IndexRanges<T, 1>, i.e. a tf::IndexRange<T>), one per dimension in order from outermost (dim 0) to innermost (dim N-1)

Each 1D range defines the begin, end, and step_size for its dimension. Dimensions are independent — any combination of positive, negative, or zero step sizes is supported, as long as each 1D range is individually valid.

// 3D: mixed step sizes
tf::IndexRanges<int, 3> r3(
  tf::IndexRange<int>(0,  4, 1),   // dim 0: 4 elements
  tf::IndexRange<int>(0, 10, 2),   // dim 1: 5 elements (0,2,4,6,8)
  tf::IndexRange<int>(0,  6, 1)    // dim 2: 6 elements
);
r3.size();   // 120

IndexRanges() [4/4]

template<std::integral T, size_t N = 1>

tf::IndexRanges< T, N >::IndexRanges ( const std::array< std::tuple< T, T, T >, N > & dims )

inlineexplicit

constructs an index range from an array of (begin, end, step) tuples

Parameters

dims	std::array of exactly N (begin, end, step) tuples

Useful when the per-dimension bounds are constructed programmatically.

std::array<std::tuple<int,int,int>, 2> dims = {
  std::tuple{0, 4, 1},
  std::tuple{0, 5, 1}
};
tf::IndexRanges<int, 2> r(dims);
r.size();  // 20

Member Function Documentation

begin() [1/2]

template<std::integral T, size_t N = 1>

T tf::IndexRanges< T, N >::begin ( ) const

inline

queries the starting index of the range (only available when N == 1)

Returns

the starting index of the range

tf::IndexRange<int> range(0, 10, 2);
auto b = range.begin();  // b == 0

begin() [2/2]

template<std::integral T, size_t N>
requires (N == 1)

IndexRanges< T, N > & tf::IndexRanges< T, N >::begin

(

T

new_begin

)

updates the starting index of the range (only available when N == 1)

Parameters

new_begin

the new starting index of the range

Returns

a reference to *this

tf::IndexRange<int> range(0, 10, 2);   // elements: 0, 2, 4, 6, 8
range.begin(4);                        // elements become: 4, 6, 8

ceil()

template<std::integral T, size_t N>
requires (N > 1)

size_t tf::IndexRanges< T, N >::ceil

(

size_t

chunk_size

)

const

returns the smallest hyperplane-aligned chunk size that is >= chunk_size, capped at size() when chunk_size exceeds the total active range size (only available when N > 1)

Parameters

chunk_size

hint for the desired number of flat elements

Returns

the smallest natural per-step volume of the active dimensions that is >= chunk_size, or size() if chunk_size > size(), or 0 if the outermost dimension is zero-size

Analogous to std::ceil but operating on the discrete set of hyperplane boundary sizes of the active dimensions (those before the first zero-size dimension). Only active suffix products are considered — inactive inner dimensions do not contribute boundaries.

// 6D range: 3 x 4 x 8 x 0 x 2 x 3
// Active dims: d=0(3), d=1(4), d=2(8) -> size()=96
// Active boundaries: 1, 8, 32, 96  (inactive dims d=3,4,5 contribute nothing)
tf::IndexRanges<int, 6> r(
  tf::IndexRange<int>(0, 3, 1),
  tf::IndexRange<int>(0, 4, 1),
  tf::IndexRange<int>(0, 8, 1),
  tf::IndexRange<int>(0, 0, 1),
  tf::IndexRange<int>(0, 2, 1),
  tf::IndexRange<int>(0, 3, 1)
);
r.ceil(1);   //  1 — already a boundary
r.ceil(5);   //  8 — rounds up to next active boundary
r.ceil(33);  // 96 — rounds up to full active size
r.ceil(200); // 96 — capped at size()

dim() [1/2]

template<std::integral T, size_t N = 1>

std::tuple< T, T, T > & tf::IndexRanges< T, N >::dim ( size_t d )

inline

returns the (begin, end, step) tuple for dimension d (mutable)

Parameters

d	zero-based dimension index in [0, N)

Returns

a mutable reference to the std::tuple<T, T, T> for dimension d

Use this to update the bounds of an individual dimension at runtime, for example inside an upstream init task when using stateful ranges:

tf::IndexRanges<int, 2> range;
 
auto init = taskflow.emplace([&]() {
  range.dim(0) = {0, rows, 1};  // set row range at runtime
  range.dim(1) = {0, cols, 1};  // set col range at runtime
});
 
auto loop = taskflow.for_each_by_index(std::ref(range), callable);
init.precede(loop);

Native structured bindings can bind directly to the tuple's elements:

// mutate a single field through a structured binding
auto& [beg, end, step] = range.dim(0);
beg = 0; end = rows; step = 1;

dim() [2/2]

template<std::integral T, size_t N = 1>

const std::tuple< T, T, T > & tf::IndexRanges< T, N >::dim ( size_t d ) const

inline

returns the (begin, end, step) tuple for dimension d (read-only)

Parameters

d	zero-based dimension index in [0, N)

Returns

a const reference to the std::tuple<T, T, T> for dimension d, in (begin, end, step) order

tf::IndexRanges<int, 3> r(
  tf::IndexRange<int>(0,  4, 1),
  tf::IndexRange<int>(0, 10, 2),
  tf::IndexRange<int>(0,  6, 1)
);
 
auto [beg, end, step] = r.dim(1);  // beg=0, end=10, step=2

empty_box()

template<std::integral T, size_t N>
requires (N > 1)

IndexRanges< T, N > tf::IndexRanges< T, N >::empty_box

(

)

const

returns a box whose size() is 0 (only available when N > 1)

Returns

a degenerate box with the same dimensions as *this, except dimension 0 is collapsed to a single point (begin == end)

Collapsing dimension 0 alone is sufficient: size() stops accumulating at the first zero-size dimension, so the returned box reports 0 regardless of the other dimensions, which are copied through verbatim.

Used by upper_slice and lower_slice for the chunk_size == 0 case, since the returned box's size() doubles as the "consumed" count.

end() [1/2]

template<std::integral T, size_t N = 1>

T tf::IndexRanges< T, N >::end ( ) const

inline

queries the ending index of the range (only available when N == 1)

Returns

the ending index (exclusive) of the range

tf::IndexRange<int> range(0, 10, 2);
auto e = range.end();  // e == 10

end() [2/2]

template<std::integral T, size_t N>
requires (N == 1)

IndexRanges< T, N > & tf::IndexRanges< T, N >::end

(

T

new_end

)

updates the ending index of the range (only available when N == 1)

Parameters

new_end

the new ending index (exclusive) of the range

Returns

a reference to *this

tf::IndexRange<int> range(0, 10, 2);   // elements: 0, 2, 4, 6, 8
range.end(6);                          // elements become: 0, 2, 4

floor()

template<std::integral T, size_t N>
requires (N > 1)

size_t tf::IndexRanges< T, N >::floor

(

size_t

chunk_size

)

const

returns the largest hyperplane-aligned chunk size that is <= chunk_size (only available when N > 1)

Parameters

chunk_size

hint for the desired number of flat elements

Returns

the largest natural per-step volume of the active dimensions that is <= chunk_size, or 0 if the outermost dimension is zero-size

Analogous to std::floor; see ceil for the boundary semantics.

// 6D range: 3 x 4 x 8 x 0 x 2 x 3
// Active dims: d=0(3), d=1(4), d=2(8) -> size()=96
// Active boundaries: 1, 8, 32, 96  (inactive dims d=3,4,5 contribute nothing)
tf::IndexRanges<int, 6> r(
  tf::IndexRange<int>(0, 3, 1),
  tf::IndexRange<int>(0, 4, 1),
  tf::IndexRange<int>(0, 8, 1),
  tf::IndexRange<int>(0, 0, 1),
  tf::IndexRange<int>(0, 2, 1),
  tf::IndexRange<int>(0, 3, 1)
);
r.floor(5);   //  1 — rounds down to previous active boundary
r.floor(33);  // 32 — rounds down
r.floor(200); // 96 — capped at size()

lower_slice()

template<std::integral T, size_t N>
requires (N > 1)

IndexRanges< T, N > tf::IndexRanges< T, N >::lower_slice	(	size_t	flat_beg,
		size_t	chunk_size ) const

returns the largest perfectly-aligned hyperbox reachable from flat_beg whose size does not exceed chunk_size, rounding down to the previous hyperplane boundary when chunk_size is not aligned (only available when N > 1)

Parameters

flat_beg	starting flat index (row-major) into the active ND space
chunk_size	hint for the desired number of elements

Returns

the sub-box; its size() gives the number of elements consumed

Analogous to std::floor: if chunk_size already aligns to a hyperplane boundary the returned box is exact (identical to upper_slice); otherwise it rounds down to the largest box that does not exceed chunk_size, so size() <= chunk_size.

Used by static partitioners: each worker's pre-assigned flat quota is never exceeded, so workers do not double-process elements at quota boundaries.

reset()

template<std::integral T, size_t N>
requires (N == 1)

IndexRanges< T, N > & tf::IndexRanges< T, N >::reset	(	T	beg,
		T	end,
		T	step_size )

updates the range with a new starting index, ending index, and step size (only available when N == 1)

Parameters

beg	new starting index of the range
end	new ending index of the range (exclusive)
step_size	new step size between consecutive indices in the range

Returns

a reference to *this

Use this to rebind a stateful range to new bounds at runtime, for example inside an upstream init task:

tf::IndexRange<int> range;
 
auto init = taskflow.emplace([&]() {
  range.reset(0, 10, 2);  // elements: 0, 2, 4, 6, 8
});
 
auto loop = taskflow.for_each_by_index(std::ref(range), callable);
init.precede(loop);

size() [1/2]

template<std::integral T, size_t N>

size_t tf::IndexRanges< T, N >::size

(

)

const

returns the number of active flat iterations

For N == 1 this is simply the element count of the range. For N > 1 it returns the product of dimension sizes from the outermost dimension inward, stopping before the first zero-size dimension. This matches the behaviour of sequential nested loops: a zero-size dimension prevents its own iterations and those of all deeper dimensions, but outer dimensions are unaffected.

// All non-zero: 4 * 6 * 8 = 192
tf::IndexRanges<int, 3> r1(
  tf::IndexRange<int>(0, 4, 1),
  tf::IndexRange<int>(0, 6, 1),
  tf::IndexRange<int>(0, 8, 1)
);
r1.size();  // 192
 
// Zero in middle (d=1): outer dim only -> 4
tf::IndexRanges<int, 3> r2(
  tf::IndexRange<int>(0, 4, 1),
  tf::IndexRange<int>(0, 0, 1),   // stops accumulation here
  tf::IndexRange<int>(0, 8, 1)
);
r2.size();  // 4

size() [2/2]

template<std::integral T, size_t N = 1>

size_t tf::IndexRanges< T, N >::size ( size_t d ) const

inline

returns the number of iterations along dimension d

Parameters

d	zero-based dimension index in [0, N)

Returns

the element count of dimension d

This is a per-dimension count, independent of other dimensions and of the zero-size stopping rule that size() applies.

tf::IndexRanges<int, 3> r(
  tf::IndexRange<int>(0,  4, 1),
  tf::IndexRange<int>(0, 10, 2),
  tf::IndexRange<int>(0,  6, 1)
);
 
r.size(1);  // 5, since the range [0,10) with step 2 has 5 elements

step_size() [1/2]

template<std::integral T, size_t N = 1>

T tf::IndexRanges< T, N >::step_size ( ) const

inline

queries the step size of the range (only available when N == 1)

Returns

the step size between consecutive indices in the range

tf::IndexRange<int> range(0, 10, 2);
auto s = range.step_size();  // s == 2

step_size() [2/2]

template<std::integral T, size_t N>
requires (N == 1)

IndexRanges< T, N > & tf::IndexRanges< T, N >::step_size

(

T

new_step_size

)

updates the step size of the range (only available when N == 1)

Parameters

new_step_size

the new step size between consecutive indices

Returns

a reference to *this

tf::IndexRange<int> range(0, 10, 1);   // elements: 0, 1, 2, ..., 9
range.step_size(3);                    // elements become: 0, 3, 6, 9

unravel()

template<std::integral T, size_t N>
requires (N == 1)

IndexRanges< T, N > tf::IndexRanges< T, N >::unravel	(	size_t	part_beg,
		size_t	part_end ) const

maps a contiguous index partition back to the corresponding subrange (only available when N == 1)

Parameters

part_beg	beginning index of the partition (inclusive)
part_end	ending index of the partition (exclusive)

Returns

a new range covering the elements at positions [part_beg, part_end) in the original range

Each element of the range can be addressed by a zero-based position index from 0 to size()-1. This function unravels a contiguous slice of those position indices back into the original iteration space, returning the sub-range whose elements correspond exactly to positions [part_beg, part_end).

tf::IndexRange<int> range(0, 10, 2);   // elements: 0, 2, 4, 6, 8
auto sub = range.unravel(1, 4);        // elements at positions [1,4): 2, 4, 6
// sub.begin() == 2, sub.end() == 8, sub.step_size() == 2

Attention

Users must ensure [part_beg, part_end) is a valid partition of [0, size()), i.e., part_end <= size().

upper_slice()

template<std::integral T, size_t N>
requires (N > 1)

IndexRanges< T, N > tf::IndexRanges< T, N >::upper_slice	(	size_t	flat_beg,
		size_t	chunk_size ) const

returns the smallest perfectly-aligned hyperbox reachable from flat_beg, rounding up to the next hyperplane boundary when chunk_size is not aligned (only available when N > 1)

Parameters

flat_beg	starting flat index (row-major) into the active ND space
chunk_size	hint for the desired number of elements

Returns

the sub-box; its size() gives the number of elements consumed

Analogous to std::ceil: if chunk_size already aligns to a hyperplane boundary the returned box is exact; otherwise it rounds up to the next clean orthogonal boundary, so size() >= chunk_size.

Only the active dimensions — those before the first zero-size dimension — are partitioned. Dimensions from the first zero onward are copied into the returned box as full extent and do not affect the flat index space.

The trailing-zeros rule applies within the active dimensions: a dimension can only expand if all active dimensions inner to it start at coordinate 0. When this fires the function returns the best geometry-constrained box reachable from flat_beg.

Used by dynamic partitioners: the atomic cursor advances by the returned box's size() and any overshoot is self-correcting.

---

The documentation for this class was generated from the following file:

• taskflow/utility/iterator.hpp