Selects parts of array-like objects. More...

#include <jem/base/Slice.h>

Inheritance diagram for jem::Slice:

Public Member Functions
	Slice ()
	Creates an empty Slice. More...

	Slice (int first, int last, int stride=1)
	Constructs a `Slice` with a given begin index, end index and stride. More...

int	first () const
	Returns the begin index. More...

int	last () const
	Returns the end index. More...

int	last (int ubound) const
	Returns a clipped end index. More...

int	stride () const
	Returns the stride. More...

Static Public Attributes
static const int	MAX_INDEX
	The largest representable integer. More...

Related Functions
(Note that these are not member functions.)
Slice construction functions.
SliceFromTo	slice (int first, int last)
	Constructs a `SliceFrom` object with a given begin index and end index. More...

Slice	slice (int first, int last, int stride)
	Constructs a `Slice` object with a given begin index, end index and stride. More...

SliceTo	slice (Begin, int last)
	Constructs a `SliceTo` object with a given end index. More...

Slice	slice (Begin, int last, int stride)
	Constructs a `Slice` object with a given end index and stride. More...

SliceFrom	slice (int first, End)
	Constructs a `SliceFrom` object with a given begin index. More...

Slice	slice (int first, End, int stride)
	Constructs a `Slice` object with a given begin index and stride. More...

const SliceAll &	slice (Begin, End)
	Returns a `SliceAll` object. More...

Slice	slice (Begin, End, int stride)
	Constructs a `Slice` object with a given stride. More...

const SliceAll &	slice (const SliceAll &all)
	Returns a `SliceAll` object. More...

Slice	slice (const SliceAll &all, int stride)
	Constructs a `Slice` object with a given stride. More...

Detailed Description

Slice objects are used to select parts of arrays, strings, and other array-like objects. Such a selection, or slice, is defined by three integers: a begin index, an end index and a stride. The begin index is a non-negative integer that points to the first element in the slice. The end index is an integer that points one position past the last element in the slice; it is always larger than or equal to the begin index. The stride is a positive integer that specifies the distance between two consecutive elements in the slice. For instance, if the stride is three, a slice contains only each third element of an array-like object. If the stride equals one, the slice is said to be contiguous.

The precise definition of a slice is as follows. Let s represent a slice of an array-like object a, and let first, last and stride denote the begin index, end index and stride, respectively. The elements of the slice are then given by:

s[i] = a[first + i * stride]

for all i for which the following condition is true:

first <= first + i * stride < last

The begin index, end index and stride must select a valid – possibly empty – set of elements from an array-like object. To be precise, the following conditions should be met:

0 <= first <= n and first <= last and stride > 0

where n denotes the length of the array a. The end index may be larger than the size of the array; it will be automatically adjusted so that it becomes less than or equal to the size of the array. In this way one can easily create a slice that extends to the end of an array-like object.

Slices are created by invoking the so-called slice operator of an array-like object. This operator is a member function – usually an overloaded subscripting or function call operator – that accepts a single Slice object and returns an object representing part of the array-like object. The String class, for instance, provides an overloaded version of the subscripting operator that returns a sub-string for a given Slice object.

Slice objects are normally constructed by calling the non-member function slice(), which is overloaded for several types of slices (contiguous and non-contiguous slices, for instance). These functions may be passed instances of the special classes Begin and End to create slices that start at the beginning of an array, extend to the end of an array, or include all elements of an array. For convenience, there are two pre-defined instances of these classes which are named BEGIN and END, respectively. There also exists a constant named ALL (of type SliceAll) than can be used to select all elements in an array.

The following example demonstrates how the slice() function can be used.

String a ( "Hello there!" );
String s;
s = a[ slice(1,5)     ];    // s == "ello"
s = a[ slice(1,8,2)   ];    // s == "el h"
s = a[ slice(BEGIN,5) ];    // s == "Hello"
s = a[ slice(6,END)   ];    // s == "there!"
s = a[ slice(ALL,2)   ];    // s == "Hlotee"

Most versions of the overloaded slice() function do not return an instance of the Slice class but an instance of a derived class. These derived classes identify special types of slices, such as contiguous slices, and are used to select an optimized version of the slice operator at compile time. For instance, the String class provides an overloaded slice operator for SliceFrom objects that takes advantage of the fact that the begin index of a SliceFrom equals zero.

See also: slice(), All, Begin, End, Array, String.

Constructor & Destructor Documentation

jem::Slice::Slice ( )

Creates a Slice object with a begin index, end index and stride that are equal to zero.

Postcondition: this->first() == 0 && this->last() == 0 && this->stride() == 1

jem::Slice::Slice	(	int	first,
		int	last,
		int	stride = `1`
	)

Constructs a Slice with begin index first, end index last and stride stride.

Parameters

first	- the begin index.
last	- the end index.
stride	- the stride.

Precondition: first >= 0 && last >= first && stride > 0

Postcondition: this->first() == first && this->last() == last && this->stride() == stride &&

Member Function Documentation

int jem::Slice::first ( ) const

Returns: The begin index of this Slice.

int jem::Slice::last ( ) const

Returns: The end index of this Slice.

int jem::Slice::last ( int ubound ) const

Returns: min ( ubound, last() )

int jem::Slice::stride ( ) const

Returns: The stride of this Slice.

Friends And Related Function Documentation

SliceFromTo slice	(	int	first,
		int	last
	)

Parameters

first	- the begin index.
last	- the end index.

Returns: SliceFromTo ( first, last )

Slice slice	(	int	first,
		int	last,
		int	stride
	)

Parameters

first	- the begin index.
last	- the end index.
stride	- the stride.

Returns: Slice ( first, last, stride )

SliceTo slice	(	Begin	,
		int	last
	)

Parameters

last	- the end index.

Returns: SliceTo ( last )

Slice slice	(	Begin	,
		int	last,
		int	stride
	)

Parameters

last	- the end index.
stride	- the stride.

Returns: Slice ( 0, last, stride )

SliceFrom slice	(	int	first,
		End
	)

Parameters

first - the begin index.

Returns: SliceFrom ( first )

Slice slice	(	int	first,
		End	,
		int	stride
	)

Parameters

first	- the begin index.
stride	- the stride.

Returns: Slice ( first, Slice::MAX_INDEX, stride )

const SliceAll & slice	(	Begin	,
		End
	)

Returns: ALL

Slice slice	(	Begin	,
		End	,
		int	stride
	)

Parameters

stride - the stride.

Returns: Slice ( 0, Slice::MAX_INDEX, stride )

const SliceAll & slice ( const SliceAll & all )

Parameters

all	- an instance of type `SliceAll`.

Returns: all

Slice slice	(	const SliceAll &	all,
		int	stride
	)

Parameters

all	- a reference to a `SliceAll` object (not used).
stride	- the stride.

Returns: Slice ( 0, Slice::MAX_INDEX, stride )

Member Data Documentation

const int jem::Slice::MAX_INDEX

static

The constant MAX_INDEX has the value of the largest representable integer. It can be used to construct a slice that extends to the end of an array-like object.

Public Member Functions

Static Public Attributes

Related Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation