 |
Domi
Multi-dimensional, distributed data structures
|
|
Domi
Multi-dimensional, distributed data structures
|
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 | |
| Slice & | operator= (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... | |
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:
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
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,
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.
|
inline |
Default constructor.
Returns start == 0, step == Default, step == 1.
|
inline |
One argument constructor.
| stopVal | [in] The stop index of the slice. |
Returns Slice with start == 0, step == stopVal, step == 1.
Two or three argument constructor.
| 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.
Return a Slice with concrete start and stop values.
| 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:
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.
|
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.
|
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.
|
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.
|
friend |
Streaming output operator.
Friend operator for streaming output
|
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.
1.8.5
