ucar.ma2
Class Section

java.lang.Object
  extended by ucar.ma2.Section

public class Section
extends java.lang.Object

A section of multidimensional array indices. Represented as List. Immutable if makeImmutable() was called.

Author:
caron

Nested Class Summary
 class Section.Iterator
           
 
Constructor Summary
Section()
          No-arg Constructor
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(int[] origin, int[] size, int[] stride)
          Create Section from a shape, origin, and stride arrays.
Section(java.util.List<Range> from)
          Create Section from a List.
Section(java.util.List<Range> from, int[] shape)
          Create Section from a List.
Section(Section from)
          Copy Constructor.
Section(java.lang.String sectionSpec)
          Parse an index section String specification, return equivilent Section.
 
Method Summary
 Section addRangeNames(java.util.List<java.lang.String> rangeNames)
           
 Section appendRange()
          Append a null Range to the Section - meaning "all"
 Section appendRange(int size)
          Append a new Range(0,size-1) to the Section
 Section appendRange(int first, int last)
          Append a new Range(first, last) to the Section
 Section appendRange(int first, int last, int stride)
          Append a new Range(first,last,stride) to the Section
 Section appendRange(Range r)
          Append a Range to the Section
 Section appendRange(java.lang.String name, int first, int last, int stride)
          Append a new Range(name,first,last,stride) to the Section
 java.lang.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 contains(Section other)
          See if this Section contains another Section.
 boolean equals(java.lang.Object o)
          Sections with equals Ranges are equal.
 boolean equivalent(int[] shape)
          Is this section equivilent to the given shape.
static Section fill(Section s, int[] shape)
          Return a Section guarenteed to be non null, with no null Ranges, and within the bounds set by shape.
 Range find(java.lang.String rangeName)
          Find a Range by its name.
 Section.Iterator getIterator(int[] 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
 java.util.List<Range> getRanges()
          Get the 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()
          Override Object.hashCode() to agree with equals.
 Section insertRange(int index, Range r)
          Insert a range at the specified index in the list.
 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.
 boolean isImmutable()
           
 Section makeImmutable()
          Makes the object immutable, so can be safely shared
 int offset(Section intersect)
           
 Section removeRange(int index)
          Remove a range at the specified index in the list.
 Section removeVlen()
          Create a new Section by compacting each Range.
 Section replaceRange(int index, Range r)
          Replace a range at the specified index in the list.
 void setDefaults(int[] shape)
          If any of the ranges are null, which means "all", set the Range from the corresponding length in shape[].
 Section setRange(int index, Range r)
          Set the range at the specified index in the list, previous Range is discarded
 Section shiftOrigin(Section newOrigin)
          Create a new Section by shifting each range by newOrigin.first() The result is then a reletive offset from the newOrigin.
 java.lang.String toString()
          Convert List of Ranges to String Spec.
 Section union(Section other)
          Create a new Section by union with another Section
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

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(int[] origin,
               int[] size,
               int[] stride)
        throws InvalidRangeException
Create Section from a shape, origin, and stride arrays.

Parameters:
origin - array of start for each Range
size - array of lengths for each Range (last = origin + size -1)
stride - stride between consecutive elements, must be > 0
Throws:
InvalidRangeException - if origin < 0, or shape < 1.

Section

public Section(java.util.List<Range> from)
Create Section from a List.

Parameters:
from - the list of Range

Section

public Section(Section from)
Copy Constructor. Returned copy is mutable

Parameters:
from - the Section to copy

Section

public Section(java.util.List<Range> from,
               int[] shape)
        throws InvalidRangeException
Create Section from a List.

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 done match

Section

public Section(java.lang.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
java.lang.IllegalArgumentException - when sectionSpec is misformed

Section

public Section()
No-arg Constructor

Method Detail

fill

public static Section fill(Section s,
                           int[] shape)
                    throws InvalidRangeException
Return a Section guarenteed to be non null, with no null Ranges, and within the bounds set by shape. A section with no nulls is called "filled". If s 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

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

removeVlen

public Section removeVlen()
                   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
Throws:
InvalidRangeException

union

public Section union(Section other)
              throws InvalidRangeException
Create a new Section by union with another Section

Parameters:
other - Section other section
Returns:
new Section, union of the two
Throws:
InvalidRangeException - if want.getRank() not equal to this.getRank(), or invalid component Range

shiftOrigin

public Section shiftOrigin(Section newOrigin)
                    throws InvalidRangeException
Create a new Section by shifting each range by newOrigin.first() The result is then a reletive offset from the newOrigin.

Parameters:
newOrigin - this becomes the origin of the result
Returns:
new Section, shifted
Throws:
InvalidRangeException - if want.getRank() not equal to this.getRank()

intersects

public boolean intersects(Section other)
                   throws InvalidRangeException
See if this Section intersects with another Section. ignores strides

Parameters:
other - another section
Returns:
true if intersection is non-empty
Throws:
InvalidRangeException - if want.getRank() not equal to this.getRank()

contains

public boolean contains(Section other)
See if this Section contains another Section. ignores strides Must have same rank and last >= other.last.

Parameters:
other - another section
Returns:
true if its a subset

toString

public java.lang.String toString()
Convert List of Ranges to String Spec. Inverse of new Section(String sectionSpec)

Overrides:
toString in class java.lang.Object
Returns:
index section String specification

appendRange

public Section appendRange()
Append a null Range to the Section - meaning "all"

Returns:
this

appendRange

public Section appendRange(Range r)
Append a Range to the Section

Returns:
this

appendRange

public Section appendRange(int size)
                    throws InvalidRangeException
Append a new Range(0,size-1) to the Section

Parameters:
size - add this Range
Returns:
this
Throws:
InvalidRangeException - if size < 1

appendRange

public Section appendRange(int first,
                           int last)
                    throws InvalidRangeException
Append a new Range(first, last) to the Section

Parameters:
first - starting index
last - last index, inclusive
Returns:
this
Throws:
InvalidRangeException - if last < first

appendRange

public Section appendRange(int first,
                           int last,
                           int stride)
                    throws InvalidRangeException
Append a new Range(first,last,stride) to the Section

Parameters:
first - starting index
last - last index, inclusive
stride - stride
Returns:
this
Throws:
InvalidRangeException - if last < first

appendRange

public Section appendRange(java.lang.String name,
                           int first,
                           int last,
                           int stride)
                    throws InvalidRangeException
Append a new Range(name,first,last,stride) to the Section

Parameters:
name - name of Range
first - starting index
last - last index, inclusive
stride - stride
Returns:
this
Throws:
InvalidRangeException - if last < first

insertRange

public Section insertRange(int index,
                           Range r)
Insert a range at the specified index in the list.

Parameters:
index - insert here in the list, existing ranges at or after this index get shifted by one
r - insert this Range
Returns:
this
Throws:
java.lang.IndexOutOfBoundsException - if bad index

removeRange

public Section removeRange(int index)
Remove a range at the specified index in the list.

Parameters:
index - remove here in the list, existing ranges after this index get shifted by one
Returns:
this
Throws:
java.lang.IndexOutOfBoundsException - if bad index

setRange

public Section setRange(int index,
                        Range r)
Set the range at the specified index in the list, previous Range is discarded

Parameters:
index - list index, must be in interval [0,size).
r - insert this Range
Returns:
this
Throws:
java.lang.IndexOutOfBoundsException - if bad index

replaceRange

public Section replaceRange(int index,
                            Range r)
Replace a range at the specified index in the list.

Parameters:
index - replace here in the list.
r - use this Range
Returns:
this
Throws:
java.lang.IndexOutOfBoundsException - if bad index

setDefaults

public void setDefaults(int[] shape)
                 throws InvalidRangeException
If any of the ranges are null, which means "all", set the Range from the corresponding length in shape[].

Parameters:
shape - default length for each Range; must have matching rank.
Throws:
InvalidRangeException - if rank is wrong

makeImmutable

public Section makeImmutable()
Makes the object immutable, so can be safely shared

Returns:
this Section

isImmutable

public boolean isImmutable()

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[] origin

getOrigin

public int getOrigin(int i)
Get origin of the ith Range

Parameters:
i - index of Range
Returns:
origin of ith Range

getShape

public int getShape(int i)
Get length of the ith Range

Parameters:
i - index of Range
Returns:
length of ith Range

getStride

public int getStride(int i)
Get stride of the ith Range

Parameters:
i - index of Range
Returns:
stride of ith Range

getRank

public int getRank()
Get rank - number of Ranges.

Returns:
rank

computeSize

public long computeSize()
Compute total number of elements represented by the section. Any VLEN Ranges are effectively skipped.

Returns:
total number of elements

getRanges

public java.util.List<Range> getRanges()
Get the list of Ranges.

Returns:
the List

getRange

public Range getRange(int i)
Get the ith Range

Parameters:
i - index into the list of Ranges
Returns:
ith Range

find

public Range find(java.lang.String rangeName)
Find a Range by its name.

Parameters:
rangeName - find this Range
Returns:
named Range or null

addRangeNames

public Section addRangeNames(java.util.List<java.lang.String> rangeNames)
                      throws InvalidRangeException
Throws:
InvalidRangeException

checkInRange

public java.lang.String checkInRange(int[] shape)
Check if this Section is legal for the given shape.

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]

Parameters:
shape - the given shape.
Returns:
true if equivilent
Throws:
InvalidRangeException - if setion rank doesnt match shape length

equals

public boolean equals(java.lang.Object o)
Sections with equals Ranges are equal.

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Override Object.hashCode() to agree with equals.

Overrides:
hashCode in class java.lang.Object

getIterator

public Section.Iterator getIterator(int[] shape)