Domi
Multi-dimensional, distributed data structures
 All Classes Files Functions Variables Typedefs Friends
Public Types | Public Member Functions | Static Public Attributes | Friends | List of all members
Domi::Slice Struct Reference

A Slice contains a start, stop, and step index, describing a subset of an ordered container. More...

#include <Domi_Slice.hpp>

+ Inheritance diagram for Domi::Slice:

Public Types

typedef Domi::dim_type dim_type
 The type for start indexes, stop indexes, and step intervals.
 

Public Member Functions

virtual Slice bounds (dim_type size) const
 Return a Slice with concrete start and stop values. More...
 
std::string toString () const
 Return a string representation of the Slice. More...
 
Constructors and destructor
 Slice ()
 Default constructor. More...
 
 Slice (dim_type stopVal)
 One argument constructor. More...
 
 Slice (dim_type startVal, dim_type stopVal, dim_type stepVal=1)
 Two or three argument constructor. More...
 
 Slice (const Slice &source)
 Copy constructor.
 
virtual ~Slice ()
 Destructor.
 
Accessor methods
const dim_type start () const
 Start index. More...
 
const dim_type stop () const
 Stop index. More...
 
const dim_type step () const
 Step interval. More...
 
Slice operators
Sliceoperator= (const Slice &source)
 Assignment operator.
 
bool operator== (const Slice &slice) const
 Equals operator.
 
bool operator!= (const Slice &slice) const
 Inequality operator.
 

Static Public Attributes

static const dim_type Default
 Default value for Slice constructors. More...
 

Friends

std::ostream & operator<< (std::ostream &os, const Slice &slice)
 Streaming output operator. More...
 

Detailed Description

A Slice contains a start, stop, and step index, describing a subset of an ordered container.

A Slice is an alternative to an index and specifies a range of values with a start value, a stop value, and a step interval. Containers that support indexing with a Slice (such as the MDArray classes) typically overload the operator[] method and return a view into the same type of container being referenced.

The formal constructors for Slices are of the form Domi::Slice(...). To ease their use as index-like objects, it is recommended that the user define a typedef to provide a shorthand:

typedef Domi::Slice slc;

Thus if you wanted a view into an existing MDArray (named array) consisting of the 5th through 10th elements of that array, you could specify

view = array[slc(5,10)];

and you would obtain an MDArrayView. Note that the meaning of the stop index is up to the container class, not the Slice struct. It is recommended that the stop index be non-inclusive. Thus in the example above, the length of view would be 10 - 5 = 5 and would support integer indexes 0, 1, ... 4.

There are several Slice constructors, taking 0-3 arguments and supporting both implicit and explicit default values. For explicitly requesting a default value, you can use Slice::Default. It is also recommended that the user define a shorthand for this as well. For example,

const Domi::dim_type & dflt = Domi::Slice::Default;

For the common case of a positive step value, the default start index is zero and the default stop index is the size of the dimension being indexed. If the step value is negative, these defaults are reversed. The default step value is one. Given these rules, plus the 3-argument constructor meaning Slice(start, stop, step), the following constructors have the following meanings:

Slice() is equivalent to Slice(0,Default,1).

Slice(3) is equivalent to Slice(0,3,1).

Slice(1,4) is equivalent to Slice(1,4,1).

Slice(Default,5,2) is equivalent to Slice(0,5,2).

Slice(Default,Default,-1) is equivalent to Slice(Default,0,-1).

Note again that it is up to the container class to recognize that a value of Default refers to the size of the container, and not to the literal value of Default (which would be set, for practical purposes, to the maximum value supported by the dim_type, which might be something like 2**31 as an example).

A container class can easily convert a Slice object that (potentially) has default values to a Slice object that has concrete values by calling the bounds() method, which takes as its single argument the size of the container.

Constructor & Destructor Documentation

Domi::Slice::Slice ( )
inline

Default constructor.

Returns start == 0, step == Default, step == 1.

Domi::Slice::Slice ( dim_type  stopVal)
inline

One argument constructor.

Parameters
stopVal[in] The stop index of the slice.

Returns Slice with start == 0, step == stopVal, step == 1.

Domi::Slice::Slice ( dim_type  startVal,
dim_type  stopVal,
dim_type  stepVal = 1 
)
inline

Two or three argument constructor.

Parameters
startVal[in] The start index of the slice.
stopVal[in] The stop index of the slice.
stepVal[in] The step interval of the slice.

Returns Slice with start == startVal, step == stopVal, step == stepVal (default 1). If stepVal is positive, then startVal == Default is converted to start = 0. If stepVal is negative, then stopVal == Default is converted to stop = 0. If stepVal is zero, an exception is thrown.

Member Function Documentation

virtual Slice Domi::Slice::bounds ( dim_type  size) const
virtual

Return a Slice with concrete start and stop values.

Parameters
size[in] The size of the container

The Slice returned by the bounds() method will be safe and accurate for a subsequent for loop. For example, if s is a Slice that may contain Default values or negative indexes (representing distance from the end of the container), and size is the size of a container, the following code is valid:

Slice bounds = s.bounds(size);
for (Domi::dim_type i = bounds.start(); i != bounds.stop();
i += bounds.step())
{ ... }

Note that in order to accommodate both positive and negative steps, the for loop continue condition is (i != bounds.stop()). This requires that bounds() return precisely the first ordinal outside the bounds that will be returned by (i += bounds.step()).

Reimplemented in Domi::ConcreteSlice.

const dim_type Domi::Slice::start ( ) const
inline

Start index.

If start is a non-negative ordinal, then it is a concrete value. If start is negative, it is interpreted to represent size-start, where size is the size of the container. If start equals Default, and step is positive, then it is set to zero. If start equals Default, and step is negative, then it is interpreted to represent the size of the container.

const dim_type Domi::Slice::step ( ) const
inline

Step interval.

If step is a non-zero ordinal, then it is a concrete value. If step equals 0, the constructor will throw an exception. If step equals Default, the constructor will convert it to a value of one.

const dim_type Domi::Slice::stop ( ) const
inline

Stop index.

If stop is a non-negative ordinal, then it is a concrete value. If stop is negative, it is interpreted to represent size-stop, where size is the size of the container. If stop equals Default, and step is positive, then it is interpreted to represent the size of the container. If start equals Default, and step is negative, then it is set to zero.

std::string Domi::Slice::toString ( ) const

Return a string representation of the Slice.

Return a string, encapsulated by "[" and "]", with the start, stop, and step values separated by colons (":"). If the start or stop values are default values, represent them with the null string. If the step value is 1, do not include the step or the second colon.

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  os,
const Slice slice 
)
friend

Streaming output operator.

Friend operator for streaming output

Member Data Documentation

const dim_type Domi::Slice::Default
static

Default value for Slice constructors.

The Default value can be provided to Slice constructors to set start, stop, and/or step to default values. The default start index is zero. The default stop index is the maximum index of the container the slice ultimately references. These default values are reversed if the step is negative. The default step is one.


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

Generated on Fri Sep 1 2023 07:56:17 for Domi by doxygen 1.8.5