Home · Pages · Index · Overviews

Slice Class Reference

A sub-array of an Array defined by any two corner coordinates. More...

 #include <array.h>

Routines

Slice * Make_SliceG (Array *target I, Coordinate *beg S, Coordinate *end S)

Coordinate * Slice_First (Slice *s)
Coordinate * Slice_Last (Slice *s)
Indx_Type Slice_Index (Slice *s)
Coordinate * Slice_Coordinate (Slice *s)

boolean Set_Slice_To_Index (Slice *s M, Indx_Type idx)
boolean Inc_Slice_Index (Slice *s M)
boolean Dec_Slice_Index (Slice *s M)
boolean Inside_Slice (Slice *s)

Indx_Type Set_Slice_To_First (Slice *s M)
Indx_Type Set_Slice_To_Last (Slice *s M)
Indx_Type Next_Slice_Index (Slice *s M)
Indx_Type Prev_Slice_Index (Slice *s M)

Array * Make_Array_From_SliceG (Slice *s)

Detailed Description

A Slice of an n-dimensional array is an n-dimensional sub-array of all the elements within a rectangular grid specified by giving its minimum and maximum coordinates as a pair of n-dimensional Coordinates. For example, if A is a 10x10x10 array, then the slice defined by the coordinates (2,3,4) and (4,6,8) is the sub-array A[2..4][3..6][4..8]. The type and scale of a slice are the same as its underlying array. The kind of a slice is the same as its underlying array except that it is PLAIN_KIND if it takes a proper subset of the outer dimension of an RGB_KIND or RGBA_KIND array, or if it takes the innermost dimension of a COMPLEX_KIND array. This class has the full complement of conventional class primitives save that reading and writing are not available as a Slice is intrinsically short lived.

Slices, along with Arrays and Frames, are considered array forms that are modeled in Mylib by the class AForm. These three separate classes all model a rectangular lattice of values in n-dimensions and hence many of the routines in the Mylib library operate on AForms as opposed to a specific one of the three types. One of the major purposes of a slice is to allow a user to apply an operation or a routine to a rectangular sub-region of an array. Thus there are many routines not listed on this page that apply to Slices indirectly as they operate on AForms.

There other major reason for a slice, is to allow a user to conveniently iterate over the elements of a slice in order to realize their own codes that operate on slices. Note that this is difficult because an array is layed out in row major order, and hence the elements of a slice consist of a collection of non-consecutive segments within the linear data vector of the underlying array.

A Slice maintains a current index into its underlying array along with auxiliary information so that one can efficiently get to the next index within the slice or report if an index is in the slice. Note carefully, that the current index need not necessarily be in the rectangular hyper-volume of the slice.

A slice is created with Make_Slice, and its mininum coordinate, maximum coordinate, current index, and coordinate (in the underlying array) for the current index can be retrieved with Slice_First, Slice_Last, Slice_Index, and Slice_Coordinate. Note that a slice is an opaque object, i.e. unlike say an Array, you cannot directly access any of its fields.

As mentioned previously a slice is an AForm and as such it is guaranteed to have an underlying array, kind, size, and shape which can be fetched with AForm_Array, AForm_Kind, AForm_Kind, and AForm_Shape. Moreover, you can ask if an array form is a slice via AForm_Class or Is_Slice.

One can set the current index, increase it by 1, decrease it by 1, and ask if the current index is inside the slice with Set_Slice_To_Index, Inc_Slice_Index, Dec_Slice_Index, and Inside_Slice. This group of routines allows one to traverse the array and efficiently know if one is inside or outside the slice as Inc_Slice_Index and Dec_Slice_Index take O(1) expected time regardless of the dimensionality of the slice. For example, suppose A is a 10x10x10 array:

 Indx_Type p;
 Slice    *s = Make_Slice(A,Coord3(2,3,4),Coord3(4,6,8));

 Set_Slice_To_Index(0);
 for (p = 0; p < A->size; p++)
   { if (Inside(s))
       ; // p is inside slice
     else
       ; // p is oustide slice
     Inc_Slice_Index(s);
   }

Perhaps most importantly, one can set the current index to the minimum or maxiumum coordinate, and advance the current index to the next or previous index in the slice, with Set_Slice_To_First, Set_Slice_To_Last, Next_Slice_Index, and Prev_Slice_Index. This group of routines allows one to iterate over the elements in the rectangular region of the slice efficiently as Next_Slice_Index and Prev_Slice_Index take O(1) expected time regardless of the dimensionality of the slice. For example, suppose A is a 10x10x10 array:

 Indx_Type p, e;
 Slice    *s = Make_Slice(A,Coord3(2,3,4),Coord3(4,6,8));

 e = Set_Slice_To_Last(s);
 for (p = Set_Slice_To_First(s); 1; p = Next_Slice_Index(s))
   { // operate on next index p in the slice
     if (p == e) break;
   }

Finally, one can create an Array that has the shape and values of a slice with Make_Array_From_Slice.


Routine Documentation

Slice * Make_SliceG (Array *target I, Coordinate *beg S, Coordinate *end S)

Creates a slice object given a target array target and the minimum and maximum coordinates, beg and end, respectively, defining the rectangle of the slice. If the underlying array is RGB_KIND, RGBA_KIND, or COMPLEX_KIND, then one is free to specify only core coordinates for the beg and end coordinates in which case the entire range of the special dimension is assumed. NB: A reference to target is created and held by the slice so that target cannot disappear until the slice does. Also, the Coordinates beg and end are subsumed by this routine, meaning that they must have a reference count of 1 upon entry and that those references will be taken over by the slice object being created.

Coordinate * Slice_First (Slice *s)

Return a pointer to the minimum Coordinate (beg in Make_Slice) of the slice s. This is not a reference, one should not free or kill this pointer.

Coordinate * Slice_Last (Slice *s)

Return a pointer to the maximum Coordinate (end in Make_Slice) of the slice s. This is not a reference, one should not free or kill this pointer.

Indx_Type Slice_Index (Slice *s)

Return the current index of slice s which is an index into the data vector of s's underlying array.

Coordinate * Slice_Coordinate (Slice *s)

Return the Coordinate corresponding to the current index of slice s which is an index into the data vector of s's underlying array. This is not a reference, one should not free or kill this pointer.

boolean Set_Slice_To_Index (Slice *s M, Indx_Type idx)

Set slice s's current index within its underlying array to idx and return true only if this position is within the slice.

boolean Inc_Slice_Index (Slice *s M)

Increase slice s's index by 1 and return true if the new position is within the slice.

boolean Dec_Slice_Index (Slice *s M)

Decrease slice s's index by 1 and return true if the new position is within the slice.

boolean Inside_Slice (Slice *s)

Return true only if the current index of s is within the slice.

Indx_Type Set_Slice_To_First (Slice *s M)

Set slice s's current index to that corresponding to its minimum coordinate and return this index.

Indx_Type Set_Slice_To_Last (Slice *s M)

Set slice s's current index to that corresponding to its maximum coordinate and return this index.

Indx_Type Next_Slice_Index (Slice *s M)

The current index of the slice s must be within the slice upon entry. The routine advances the index to the next value that is within the slice. If the current index is that of the last index in the slice, then the index is advanced to the first index of the slice in a circular fashion. This routine serves as the basic forward iterator for enumerating all the indices of elements in a slice. The routine returns the updated index.

Indx_Type Prev_Slice_Index (Slice *s M)

Exactly the same as Next_Slice_Index except the index moves backwards through the indices of slice s in a cyclic fashion.

Array * Make_Array_From_SliceG (Slice *s)

Generate an array whose shape and value is that modeled by the slices s. The array has the kind (as returned by AForm_Kind), type, and scale of the slice. See also Clip_Array Clip_Array_Inplace for similar but distinct functionality.