tf::IndexRange< T > Class Template Reference

class to create an index range of integral indices with a step size More...

#include <taskflow/utility/iterator.hpp>

Public Types
using	index_type = T
	alias for the index type used in the range

Public Member Functions
	IndexRange ()=default
	constructs an index range object without any initialization
	IndexRange (T beg, T end, T step_size)
	constructs an IndexRange object
T	begin () const
	queries the starting index of the range
T	end () const
	queries the ending index of the range
T	step_size () const
	queries the step size of the range
IndexRange< T > &	reset (T begin, T end, T step_size)
	updates the range with the new starting index, ending index, and step size
IndexRange< T > &	begin (T new_begin)
	updates the starting index of the range
IndexRange< T > &	end (T new_end)
	updates the ending index of the range
IndexRange< T > &	step_size (T new_step_size)
	updates the step size of the range
size_t	size () const
	queries the number of elements in the range
IndexRange	unravel (size_t part_beg, size_t part_end) const
	maps a contiguous index partition back to the corresponding subrange

Detailed Description

template<typename T>
class tf::IndexRange< T >

class to create an index range of integral indices with a step size

Template Parameters

T	the integral type of the indices

This class provides functionality for managing a range of indices, where the range is defined by a starting index, an ending index, and a step size. Indices must be an integral type. For example, the range `[0, 10) with a step size 2 represents the five elements, 0, 2, 4, 6, and 8.

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

Constructor & Destructor Documentation

IndexRange()

template<typename T>

tf::IndexRange< T >::IndexRange ( T beg, T end, T step_size )

inlineexplicit

constructs an IndexRange object

Parameters

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

Member Function Documentation

size()

template<typename T>

size_t tf::IndexRange< T >::size ( ) const

inline

queries the number of elements in the range

The number of elements is equivalent to the number of iterations in the range. For instance, the range [0, 10) with step size of 2 will iterate five elements, 0, 2, 4, 6, and 8.

tf::IndexRange<int> range(0, 10, 2);
printf("%zu\n", range.size());        // 5 (0, 2, 4, 6, 8)

unravel()

template<typename T>

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

inline

maps a contiguous index partition back to the corresponding subrange

Parameters

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

Returns

a new IndexRange 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).

For example, the range [0, 10) with step size 2 contains five elements at positions 0->0, 1->2, 2->4, 3->6, 4->8. Unraveling the partition [1, 4) yields the subrange [2, 8) with the same step size 2, whose elements are 2, 4, and 6.

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

This is particularly useful when partitioning work across parallel workers: each worker receives a position-space partition [part_beg, part_end) and calls unravel to recover the actual index subrange it should process.

Attention

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

---

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

• taskflow/utility/iterator.hpp