Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference

ID 767253
Date 11/07/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

n_bounds_t

Variadic template class to describe the valid iteration space over an N-dimensional container. #include <sdlt/n_bounds.h>

Syntax

template<typename... TypeListT>
class n_bounds_t

Description

n_bound_t represents the valid iteration space over a n_container or its accessor as as a sequence of bounds_t for each dimension. The bounds_t of each dimension can be represented by different types. This flexibility allows the same interface to be used to declare n_bounds_t whose dimensions are fully known at compile time with fixed<int NumberT>, or to be only known at runtime with int, or only known at runtime but with a guarantee will be a multiple of an alignment with aligned<int Alignment>. For details see the Number Representation section).

When an n_container is created, its n_bounds_t always start at fixed<0> for the inclusive lower bounds of each dimension, and exclusive upper bounds match the extent of the dimension. Accessors can be translated to different index spaces as well as restrict their iteration space to subsections, which will change the n_bounds_t those accessors provide.

The following table provides information on the template arguments for n_bounds_t.

Template Argument

Description

typename... TypeListT

Comma separated list of types, where the number of types provided controls how many dimensions there are. Each type in the list identifies how the bounds of the corresponding dimension is to be represented. The order of the dimensions is the same order as C++ subscripts declaring a multi-dimensional array – from leftmost to rightmost.

Requirements: types in the list be bounds_t<LowerT, UpperT>

The following table provides information on the member types of n_bounds_t

Member Types

Description

typedef implementation-defined lower_type

Type of n_index_t<…> returned by method lower()

typedef implementation-defined upper_type

Type of n_index_t<…> returned by method upper()

   

The following table provides information on the members of n_bounds_t.

Member

Description

static constexpr int rank;

Number of dimensions

static constexpr int row_dimension = rank-1;

Index of last dimension considered to be the row

n_bounds_t()

Requirements: Every bounds_t in TypeListT is default constructible.

Effects: Construct n_bounds_t, uses default values of each bounds_t in TypeListT for the dimesnion sizes. In general only correctly initialized when every bounds_t has an LowerT and UpperT that is a fixed<NumberT>.

n_bounds_t(const n_bounds_t &a_other)

Effects: Construct n_bounds_t, copying bounds of each dimension from a_other.

template<int DimensionT> 
auto get() const

Requirements: DimenstionT >=0 and DimensiontT < rank.

Effects: Determine the bounds of DimensionT.

Returns: In the type declared by the DimensionT position of 0-based TypeListT, the bounds_t of the specified DimensionT

lower_type lower()

Effects: build n_index<…> representing the inclusive lower bounds for all dimensions

Returns: n_index[get<0>().lower()]

[get<1>().lower()]

[get<…>().lower()]

[get<row_dimension>().lower()]

upper_type upper()

Effects: build n_index<…> representing the exclusive upper bounds for all dimensions

Returns: n_index[get<0>().upper()]

[get<1>(). upper ()]

[get<…>(). upper ()]

[get<row_dimension>().upper()]

template<typename... OtherTypeListT> 
bool contains(n_bounds_t<OtherTypeListT...>
                             &a_other) const	

Requirements: rank of a_other is the same as this instance’s.

Effects: Determine whether each dimension of the passed n_bounds_t is fully contained within bounds of each dimenson of this object.

Returns: get<0>().contains(a_other.get<0>() ) &&

get<1>().contains(a_other.get<1>() ) &&

get<…>().contains(a_other.get<…>() ) &&

get<row_dimension>().contains(a_other.get<row_dimension>() )

template<class... OtherTypeListT>
bool operator == (const n_bounds_t<OtherTypeListT...> a_other) const

Requirements: rank of a_other is the same as this instance’s.

Effects: Compare bounds each of dimension for equality. Only compares numeric values, not the types of each dimension.

Returns: true if all dimensions are numerically equal, false otherwise.

template<class... OtherTypeListT>
bool operator != (const n_bounds_t<OtherTypeListT...> a_other) const

Requirements: rank of a_other is the same as this instance’s.

Effects: Compare bounds of each dimension for inequality. Only compares numeric values, not the types of each dimension.

Returns: true if any dimensions are numerically different, false otherwise.

template<class ...OtherTypeListT> 
auto operator+ (const n_index_t<OtherTypeListT...> a_offset) const

Requirements: rank of a_other is the same as this instance’s.

Effects: construct a n_bound_t whose types and bounds value for each dimension are determined by taking the bounds for each dimension and adding the an offset for that dimension from a_offset.

Returns: n_bounds[get<0>() + a_offset.get<0>()]

[get<1>() + a_offset.get<1>()]

[get<…>() + a_offset.get<…>()]

[get<row_dimension>() + a_offset.get< row_dimension >()]

template<int DimensionT> 
auto rightmost_dimensions() const

Requirements: DimenstionT >=0 and DimensiontT <= rank.

Effects: Construct a n_bounds_t with a lower rank by copying the righmost DimensionT values from this instance.

Returns: n_bounds[get<rank – DimensionT>()]

[get<rank + 1 – DimensionT>()]

[get<…>()]

[get<row_dimension>()]

template<class... OtherTypeListT>
auto overlay_rightmost(const n_bounds_t<OtherTypeListT...> & a_other) const

Requirements: rank of a_other is <= rank

Effects: Construct copy of n_bounds_t where the rightmost dimensions’ values are copied from a_other, effectively overlaying a_other ontop of rightmost dimensions of this instance.

Returns:

n_bounds[get<0>()]

[get<1 >()]

[get<…>()]

[get<rank-a_other::rank>()]

[a_other.get<0>()]

[a_other.get<…>()]

[a_other.get<a_other::row_dimension>()]

The following table provides information on the friend functions of n_bounds_t.

Friend Function

Description

std::ostream& operator << (std::ostream& output_stream, const n_bounds_t & a_bounds_list)

Effects: append string representation of a_bounds_list values to a_output_stream

Returns: reference to a_output_stream for chained calls.