tf::IndexRange< 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
	IndexRange ()=default
	constructs an N-dimensional index range without initialization
template<typename... Ranges> requires (sizeof...(Ranges) == N) && (std::same_as<std::remove_cvref_t<Ranges>, IndexRange<T, 1>> && ...)
	IndexRange (Ranges &&... ranges)
	constructs an N-D index range from N 1D IndexRange<T, 1> objects
	IndexRange (const std::array< IndexRange< T, 1 >, N > &dims)
	constructs an N-D index range from an array of 1D ranges
const IndexRange< T, 1 > &	dim (size_t d) const
	returns the 1D range for dimension d (read-only)
IndexRange< T, 1 > &	dim (size_t d)
	returns the 1D range for dimension d (mutable)
const std::array< IndexRange< T, 1 >, N > &	dims () const
	returns the underlying array of all per-dimension 1D ranges
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
std::pair< IndexRange< T, N >, size_t >	slice_ceil (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
std::pair< IndexRange< T, N >, size_t >	slice_floor (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
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
size_t	floor (size_t chunk_size) const
	returns the largest hyperplane-aligned chunk size that is <= chunk_size

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

Detailed Description

template<std::integral T, size_t N>
class tf::IndexRange< 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 (must be > 1; use IndexRange<T, 1> for 1D)

This class represents the Cartesian product of N independent 1D index ranges, each defined by a starting index, ending index, and step size. 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::IndexRange<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 slice_ceil / slice_floor 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::IndexRange<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)
 
// High-dimensional example: 15D with zero at d=7
// size() = product of dims [0..6] only
tf::IndexRange<int, 15> r2(
  tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,3,1), tf::IndexRange<int>(0,4,1),
  tf::IndexRange<int>(0,5,1), tf::IndexRange<int>(0,6,1), tf::IndexRange<int>(0,7,1),
  tf::IndexRange<int>(0,8,1), tf::IndexRange<int>(0,0,1),  // d=7: zero
  tf::IndexRange<int>(0,9,1), tf::IndexRange<int>(0,10,1), tf::IndexRange<int>(0,11,1),
  tf::IndexRange<int>(0,12,1),tf::IndexRange<int>(0,13,1), tf::IndexRange<int>(0,14,1),
  tf::IndexRange<int>(0,15,1)
);
r2.size();  // 2*3*4*5*6*7*8 = 40320

Constructor & Destructor Documentation

IndexRange() [1/3]

template<std::integral T, size_t N>

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

default

constructs an N-dimensional index range without initialization

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

IndexRange() [2/3]

template<std::integral T, size_t N>

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

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

inlineexplicit

constructs an N-D index range from N 1D IndexRange<T, 1> objects

Parameters

ranges

exactly N 1D ranges, 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.

// 2D: 4 rows, 5 columns (unit steps)
tf::IndexRange<int, 2> r2(
  tf::IndexRange<int>(0,  4, 1),   // dim 0 (rows):    0,1,2,3
  tf::IndexRange<int>(0,  5, 1)    // dim 1 (columns): 0,1,2,3,4
);
r2.size();   // 20
 
// 3D: mixed step sizes
tf::IndexRange<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
 
// 3D: innermost dim has zero size — outer two dims still active
tf::IndexRange<int, 3> r4(
  tf::IndexRange<int>(0, 4, 1),
  tf::IndexRange<int>(0, 5, 1),
  tf::IndexRange<int>(0, 0, 1)    // zero-size: only dims 0,1 contribute
);
r4.size();   // 20  (4 * 5, not 0)

IndexRange() [3/3]

template<std::integral T, size_t N>

tf::IndexRange< T, N >::IndexRange ( const std::array< IndexRange< T, 1 >, N > & dims )

explicit

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

Parameters

dims	std::array of exactly N 1D ranges

Equivalent to the variadic constructor but takes a pre-built array, which is useful when the ranges are constructed programmatically.

std::array<tf::IndexRange<int, 1>, 3> dims = {
  tf::IndexRange<int>(0, 4, 1),
  tf::IndexRange<int>(0, 5, 1),
  tf::IndexRange<int>(0, 6, 1)
};
tf::IndexRange<int, 3> r(dims);
r.size();  // 120

Member Function Documentation

ceil()

template<std::integral T, size_t N>

size_t tf::IndexRange< 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

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.

When chunk_size is already a natural boundary size the return equals chunk_size exactly — just like std::ceil of an integer.

// 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::IndexRange<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(8);   //  8 — already a boundary
r.ceil(9);   // 32 — rounds up
r.ceil(32);  // 32 — already a boundary
r.ceil(33);  // 96 — rounds up to full active size
r.ceil(96);  // 96 — already a boundary (== size())
r.ceil(200); // 96 — capped at size()

dim() [1/2]

template<std::integral T, size_t N>

IndexRange< T, 1 > & tf::IndexRange< T, N >::dim ( size_t d )

inline

returns the 1D range for dimension d (mutable)

Parameters

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

Returns

a mutable reference to the 1D range 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::IndexRange<int, 2> range(
  tf::IndexRange<int>(0, 0, 1),   // placeholder
  tf::IndexRange<int>(0, 0, 1)    // placeholder
);
 
auto init = taskflow.emplace([&]() {
  range.dim(0).reset(0, rows, 1);  // set row range at runtime
  range.dim(1).reset(0, cols, 1);  // set col range at runtime
});
 
auto loop = taskflow.for_each_by_index(std::ref(range), callable);
init.precede(loop);

dim() [2/2]

template<std::integral T, size_t N>

const IndexRange< T, 1 > & tf::IndexRange< T, N >::dim ( size_t d ) const

inline

returns the 1D range for dimension d (read-only)

Parameters

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

Returns

a const reference to the 1D range for dimension d, which exposes begin(), end(), and step_size()

Use this inside a for_each_by_index callable to iterate the indices assigned to each dimension of the delivered sub-box.

// 3D range: i in [0,4), j in [0,10,2) (step 2), k in [0,6)
tf::IndexRange<int, 3> r(
  tf::IndexRange<int>(0,  4, 1),
  tf::IndexRange<int>(0, 10, 2),
  tf::IndexRange<int>(0,  6, 1)
);
 
r.dim(0).begin();      // 0
r.dim(0).end();        // 4
r.dim(0).step_size();  // 1
r.dim(0).size();       // 4
 
r.dim(1).begin();      // 0
r.dim(1).end();        // 10
r.dim(1).step_size();  // 2
r.dim(1).size();       // 5  (values: 0, 2, 4, 6, 8)
 
// Typical usage inside a for_each_by_index callable:
taskflow.for_each_by_index(r, [](const tf::IndexRange<int, 3>& sub) {
  for(int i = sub.dim(0).begin(); i < sub.dim(0).end(); i += sub.dim(0).step_size()) {
    for(int j = sub.dim(1).begin(); j < sub.dim(1).end(); j += sub.dim(1).step_size()) {
      for(int k = sub.dim(2).begin(); k < sub.dim(2).end(); k += sub.dim(2).step_size()) {
        // process element at (i, j, k)
      }
    }
  }
});

dims()

template<std::integral T, size_t N>

const std::array< IndexRange< T, 1 >, N > & tf::IndexRange< T, N >::dims ( ) const

inline

returns the underlying array of all per-dimension 1D ranges

Returns

a const reference to the std::array of N 1D ranges, one per dimension in order from outermost (0) to innermost (N-1)

Useful when you need to inspect or iterate over all dimensions without knowing N at the call site, or when passing the full set of dimension ranges to another function.

tf::IndexRange<int, 3> r(
  tf::IndexRange<int>(0,  4, 1),
  tf::IndexRange<int>(0, 10, 2),
  tf::IndexRange<int>(0,  6, 1)
);
 
// Print each dimension's bounds and step
for(size_t d = 0; d < r.rank; ++d) {
  const auto& dim = r.dims()[d];
  printf("dim %zu: [%d, %d) step %d  size=%zu\n",
         d, dim.begin(), dim.end(), dim.step_size(), dim.size());
}
// dim 0: [0, 4)  step 1  size=4
// dim 1: [0, 10) step 2  size=5
// dim 2: [0, 6)  step 1  size=6

floor()

template<std::integral T, size_t N>

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

(

size_t

chunk_size

)

const

returns the largest hyperplane-aligned chunk size that is <= chunk_size

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 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.

When chunk_size is already a natural boundary size the return equals chunk_size exactly — just like std::floor of an integer, and identical to ceil in that case.

// 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::IndexRange<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(1);   //  1 — already a boundary
r.floor(5);   //  1 — rounds down to previous active boundary
r.floor(8);   //  8 — already a boundary
r.floor(9);   //  8 — rounds down
r.floor(32);  // 32 — already a boundary
r.floor(33);  // 32 — rounds down
r.floor(96);  // 96 — already a boundary (== size())
r.floor(200); // 96 — capped at size()

size() [1/2]

template<std::integral T, size_t N>

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

(

)

const

returns the number of active flat iterations

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::IndexRange<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::IndexRange<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
 
// Zero in innermost (d=2): outer two dims contribute -> 4*6 = 24
tf::IndexRange<int, 3> r3(
  tf::IndexRange<int>(0, 4, 1),
  tf::IndexRange<int>(0, 6, 1),
  tf::IndexRange<int>(0, 0, 1)    // stops accumulation here
);
r3.size();  // 24
 
// Zero in outermost (d=0): no outer work -> 0
tf::IndexRange<int, 3> r4(
  tf::IndexRange<int>(0, 0, 1),   // stops immediately
  tf::IndexRange<int>(0, 6, 1),
  tf::IndexRange<int>(0, 8, 1)
);
r4.size();  // 0
 
// High-dimensional example: 19D with zero at d=9
// -> product of dims [0..8] = 2^9 = 512
tf::IndexRange<int, 19> r5(
  tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1),
  tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1),
  tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1),
  tf::IndexRange<int>(0,0,1),  // d=9: zero — dims 10..18 are inactive
  tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1),
  tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1),
  tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1), tf::IndexRange<int>(0,2,1)
);
r5.size();  // 512

size() [2/2]

template<std::integral T, size_t N>

size_t tf::IndexRange< 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, i.e. distance(dim(d).begin(), dim(d).end(), dim(d).step_size())

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

tf::IndexRange<int, 3> r(
  tf::IndexRange<int>(0,  4, 1),   // 4 elements
  tf::IndexRange<int>(0, 10, 2),   // 5 elements (0,2,4,6,8)
  tf::IndexRange<int>(0,  6, 1)    // 6 elements
);
 
r.size(0);  // 4
r.size(1);  // 5
r.size(2);  // 6
 
// Note: size(d) reports the raw dimension count regardless of
// zero-size siblings — unlike size() which stops at the first zero.
tf::IndexRange<int, 3> r2(
  tf::IndexRange<int>(0, 4, 1),
  tf::IndexRange<int>(0, 0, 1),   // zero-size middle dim
  tf::IndexRange<int>(0, 6, 1)
);
r2.size(0);  // 4   (unaffected by the zero in dim 1)
r2.size(1);  // 0
r2.size(2);  // 6   (unaffected by the zero in dim 1)
r2.size();   // 4   (stops at dim 1)

slice_ceil()

template<std::integral T, size_t N>

std::pair< IndexRange< T, N >, size_t > tf::IndexRange< T, N >::slice_ceil	(	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

Parameters

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

Returns

a pair of (sub-box, consumed) where consumed == sub-box.size()

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 consumed >= 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 consumed and any overshoot is self-correcting.

// 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 suffix products (boundaries): 1, 8, 32, 96
// Dims d=3(0), d=4(2), d=5(3) are inactive — copied as full extent
tf::IndexRange<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),   // zero — stops active space here
  tf::IndexRange<int>(0, 2, 1),
  tf::IndexRange<int>(0, 3, 1)
);
 
// chunk_size=8 aligns to one inner row — no overshoot
// box: d0=[0,1), d1=[0,1), d2=[0,8), d3=[0,0), d4=[0,2), d5=[0,3)
auto [box1, c1] = r.slice_ceil(0, 8);   // consumed=8
 
// chunk_size=20 does not align; rounds up to next boundary (32)
// box: d0=[0,1), d1=[0,4), d2=[0,8), d3=[0,0), d4=[0,2), d5=[0,3)
auto [box2, c2] = r.slice_ceil(0, 20);  // consumed=32
 
// geometry-constrained: flat=10 -> active coords (0,1,2), d2 not at 0
// trailing-zeros fires; grow_dim=2, takes remaining 6 steps in that row
auto [box3, c3] = r.slice_ceil(10, 20); // consumed=6 (<chunk_size)

slice_floor()

template<std::integral T, size_t N>

std::pair< IndexRange< T, N >, size_t > tf::IndexRange< T, N >::slice_floor	(	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

Parameters

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

Returns

a pair of (sub-box, consumed) where consumed == sub-box.size()

Analogous to std::floor: if chunk_size already aligns to a hyperplane boundary the returned box is exact (identical to slice_ceil); otherwise it rounds down to the largest box that does not exceed chunk_size, so consumed <= 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.

The trailing-zeros rule applies within the active dimensions identically to slice_ceil.

Used by static partitioners: each worker's pre-assigned flat quota is never exceeded, so workers do not double-process elements at quota 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 suffix products (boundaries): 1, 8, 32, 96
// Dims d=3(0), d=4(2), d=5(3) are inactive — copied as full extent
tf::IndexRange<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),   // zero — stops active space here
  tf::IndexRange<int>(0, 2, 1),
  tf::IndexRange<int>(0, 3, 1)
);
 
// chunk_size=8 aligns exactly — same as slice_ceil
auto [box1, c1] = r.slice_floor(0, 8);   // consumed=8
 
// chunk_size=20 does not align; rounds down to largest boundary <= 20 (which is 8)
auto [box2, c2] = r.slice_floor(0, 20);  // consumed=8
 
// chunk_size=32 aligns exactly
auto [box3, c3] = r.slice_floor(0, 32);  // consumed=32
 
// chunk_size=50 does not align; rounds down to 32
auto [box4, c4] = r.slice_floor(0, 50);  // consumed=32

---

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

• taskflow/utility/iterator.hpp