Package ucar.array

Class Section

java.lang.Object

ucar.array.Section

@Immutable
public class Section
extends Object

A section of multidimensional array indices. Represented as List.

TODO evaluate use of null.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Section.Builder
class	Section.Iterator

Field Summary

Fields

Modifier and Type	Field	Description
static Section	SCALAR

Constructor Summary

Constructors

Constructor	Description
Section(int[] shape)	Create Section from a shape array, assumes 0 origin.
Section(int[] origin, int[] shape)	Create Section from a shape and origin arrays.
Section(String sectionSpec)	Parse an index section String specification, return equivilent Section.
Section(List<Range> from)	Create Section from a List.
Section(List<Range> from, int[] shape)	Create Section from a List, filling in nulls with shape.
Section(Range... ranges)	Create Section from a variable length argument list of Ranges

Method Summary

Modifier and Type	Method	Description
static Section.Builder	builder()
String	checkInRange(int[] shape)	Check if this Section is legal for the given shape.
Section	compact()	Create a new Section by compacting each Range.
Section	compose(Section want)	Create a new Section by composing with a Section that is reletive to this Section.
long	computeSize()	Compute total number of elements represented by the section.
boolean	equals(Object o)
boolean	equivalent(int[] shape)	Is this section equivilent to the given shape.
Section	fill(int[] shape)	Fil any null sections with the ccorresponding value from shape.
static Section	fill(Section s, int[] shape)	Return a Section guaranteed to be non null, with no null Ranges, and within the bounds set by shape.
Range	find(String rangeName)	Find a Range by its name.
Section.Iterator	getIterator(int[] shape)	Iterate over a section, returning the index in an equivalent 1D array of shape[], and optionally the corresponding index[n] So this is a section in a (possibly) larger array described by shape[].
int[]	getOrigin()	Get origin array using the Range.first() values.
int	getOrigin(int i)	Get origin of the ith Range
Range	getRange(int i)	Get the ith Range
List<Range>	getRanges()	Get an unmodifyable list of Ranges.
int	getRank()	Get rank = number of Ranges.
int[]	getShape()	Get shape array using the Range.length() values.
int	getShape(int i)	Get length of the ith Range
int[]	getStride()	Get stride array using the Range.stride() values.
int	getStride(int i)	Get stride of the ith Range
int	hashCode()
Section	intersect(Section other)	Create a new Section by intersection with another Section
boolean	intersects(Section other)	See if this Section intersects with another Section.
static boolean	isScalar(int[] shape)	Is this a scalar Section? Allows int[], int[1] {0}, int[1] {1}
boolean	isStrided()
boolean	isVariableLength()	Does this contain a VLEN range?
int	offset(Section intersect)	Compute the element offset of an intersecting subrange of this.
Section.Builder	toBuilder()
String	toString()	Convert List of Ranges to String sectionSpec.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

SCALAR

public static final Section SCALAR

Constructor Detail

Section

public Section(int[] shape)

Create Section from a shape array, assumes 0 origin.

Parameters:

shape - array of lengths for each Range. 0 = EMPTY, < 0 = VLEN

Section

public Section(int[] origin,
               int[] shape)
        throws InvalidRangeException

Create Section from a shape and origin arrays.

Parameters:

origin - array of start for each Range

shape - array of lengths for each Range

Throws:

InvalidRangeException - if origin < 0, or shape < 1.

Section

public Section(List<Range> from)

Create Section from a List.

Section

public Section(Range... ranges)

Create Section from a variable length argument list of Ranges

Section

public Section(List<Range> from,
               int[] shape)
        throws InvalidRangeException

Create Section from a List, filling in nulls with shape.

Parameters:

from - the list of Range

shape - use this as default shape if any of the ranges are null.

Throws:

InvalidRangeException - if shape and range list dont match

Section

public Section(String sectionSpec)
        throws InvalidRangeException

Parse an index section String specification, return equivilent Section. A null Range means "all" (i.e.":") indices in that dimension.

The sectionSpec string uses fortran90 array section syntax, namely:

   sectionSpec := dims
   dims := dim | dim, dims
   dim := ':' | slice | start ':' end | start ':' end ':' stride
   slice := INTEGER
   start := INTEGER
   stride := INTEGER
   end := INTEGER

 where nonterminals are in lower case, terminals are in upper case, literals are in single quotes.

 Meaning of index selector :
  ':' = all
  slice = hold index to that value
  start:end = all indices from start to end inclusive
  start:end:stride = all indices from start to end inclusive with given stride

 

Parameters:

sectionSpec - the token to parse, eg "(1:20,:,3,10:20:2)", parenthesis optional

Throws:

InvalidRangeException - when the Range is illegal

IllegalArgumentException - when sectionSpec is misformed

Method Detail

fill

public static Section fill(Section s,
                           int[] shape)
                    throws InvalidRangeException

Return a Section guaranteed to be non null, with no null Ranges, and within the bounds set by shape. A section with no nulls is called "filled". If it is already filled, return it, otherwise return a new Section, filled from the shape.

Parameters:

s - the original Section, may be null or not filled

shape - use this as default shape if any of the ranges are null.

Returns:

a filled Section

Throws:

InvalidRangeException - if shape and s and shape rank dont match, or if s has invalid range compared to shape

isScalar

public static boolean isScalar(int[] shape)

Is this a scalar Section? Allows int[], int[1] {0}, int[1] {1}

compact

public Section compact()
                throws InvalidRangeException

Create a new Section by compacting each Range. first = first/stride, last=last/stride, stride=1.

Returns:

compacted Section

Throws:

InvalidRangeException - elements must be nonnegative, 0 ≤ first ≤ last

compose

public Section compose(Section want)
                throws InvalidRangeException

Create a new Section by composing with a Section that is reletive to this Section.

Parameters:

want - Section reletive to this one. If null, return this. If individual ranges are null, use corresponding Range in this.

Returns:

new Section, composed

Throws:

InvalidRangeException - if want.getRank() not equal to this.getRank(), or invalid component Range

intersect

public Section intersect(Section other)
                  throws InvalidRangeException

Create a new Section by intersection with another Section

Parameters:

other - Section other section

Returns:

new Section, composed

Throws:

InvalidRangeException - if want.getRank() not equal to this.getRank(), or invalid component Range

offset

public int offset(Section intersect)
           throws InvalidRangeException

Compute the element offset of an intersecting subrange of this.

Parameters:

intersect - the subrange

Returns:

element offset

Throws:

InvalidRangeException

intersects

public boolean intersects(Section other)
                   throws InvalidRangeException

See if this Section intersects with another Section. ignores strides, vlen

Parameters:

other - another section

Returns:

true if intersection is non-empty

Throws:

InvalidRangeException - if want.getRank() not equal to this.getRank(),

toString

public String toString()

Convert List of Ranges to String sectionSpec. Inverse of new Section(String sectionSpec)

Overrides:

toString in class Object

Returns:

index section String specification

isVariableLength

public boolean isVariableLength()

Does this contain a VLEN range?

isStrided

public boolean isStrided()

getShape

public int[] getShape()

Get shape array using the Range.length() values.

Returns:

int[] shape

getOrigin

public int[] getOrigin()

Get origin array using the Range.first() values.

Returns:

int[] origin

getStride

public int[] getStride()

Get stride array using the Range.stride() values.

Returns:

int[] stride

getOrigin

public int getOrigin(int i)

Get origin of the ith Range

getShape

public int getShape(int i)

Get length of the ith Range

getStride

public int getStride(int i)

Get stride of the ith Range

getRank

public int getRank()

Get rank = number of Ranges.

computeSize

public long computeSize()

Compute total number of elements represented by the section. Any null or VLEN Ranges are skipped.

Returns:

total number of elements

getRanges

public List<Range> getRanges()

Get an unmodifyable list of Ranges.

getRange

public Range getRange(int i)

Get the ith Range

Parameters:

i - index into the list of Ranges

Returns:

ith Range

fill

public Section fill(int[] shape)
             throws InvalidRangeException

Fil any null sections with the ccorresponding value from shape.

Throws:

InvalidRangeException

find

@Nullable
public Range find(String rangeName)

Find a Range by its name.

Parameters:

rangeName - find this Range

Returns:

named Range or null

checkInRange

public String checkInRange(int[] shape)

Check if this Section is legal for the given shape. [Note: modified by dmh to address the case of unlimited where the size is zero]

Parameters:

shape - range must fit within this shape, rank must match.

Returns:

error message if illegal, null if all ok

equivalent

public boolean equivalent(int[] shape)
                   throws InvalidRangeException

Is this section equivilent to the given shape. All non-null ranges must have origin 0 and length = shape[i]

Throws:

InvalidRangeException

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

getIterator

public Section.Iterator getIterator(int[] shape)

Iterate over a section, returning the index in an equivalent 1D array of shape[], and optionally the corresponding index[n] So this is a section in a (possibly) larger array described by shape[]. The index is in the "source" array.

Parameters:

shape - total array shape

Returns:

iterator over this section

toBuilder

public Section.Builder toBuilder()

builder

public static Section.Builder builder()