Package ucar.ma2

Class Section

java.lang.Object
ucar.ma2.Section
public class Section extends Object
A section of multidimensional array indices. Represented as List. Immutable if makeImmutable() was called. TODO Will be immutable in ver6. TODO evaluate use of null in ver7

  • Constructor Details

    • 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(List<Range> from)
      Create Section from a List.
      Parameters:
      from - the list of Range

    • Section

      public Section(Range... ranges)
      Create Section from a variable length list of Ranges
      Parameters:
      ranges - the list

    • Section

      public Section(Section from)
      Copy Constructor. Returned copy is mutable
      Parameters:
      from - the Section to copy

    • Section

      public Section(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 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

    • Section

      public Section()
      No-arg Constructor

  • Method Details

    • 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 its 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

    • make

      public static Section make(List<RangeIterator> rangeIter)

    • 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 relative to this Section.
      Parameters:
      want - Section relative 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

    • 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 relative 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()

    • shiftOrigin

      public Section shiftOrigin(int[] newOrigin) throws InvalidRangeException
      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(),

    • 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 String toString()
      Convert List of Ranges to String Spec. Inverse of new Section(String sectionSpec)
      Overrides:
      toString in class Object
      Returns:
      index section String specification

    • show

      public String show()

    • reduce

      public Section reduce()
      Remove any ranges of length 1
      Returns:
      new Section if any Ranges needed replacement, else this

    • 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

    • subSection

      public Section subSection(int fromIndex, int endExclusive)

    • removeFirst

      public Section removeFirst(Section parentSection)

    • prepend

      public Section prepend(Section parentSection)

    • isImmutable

      public boolean isImmutable()

    • isVariableLength

      public boolean isVariableLength()

    • 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

    • 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

    • getSize

      public long getSize()

    • getRank

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

    • compatibleRank

      public boolean compatibleRank(Section other)
      Compare this section with another upto the vlen in either

    • computeSize

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

    • computeSize

      public static long computeSize(int[] shape)

    • getRanges

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

    • getRange

      public Range getRange(int i)
      Get the ith Range
      Parameters:
      i - index into the list of Ranges
      Returns:
      ith Range

    • 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]
      Parameters:
      shape - the given shape.
      Returns:
      true if equivilent
      Throws:
      InvalidRangeException - if section rank doesnt match shape length

    • conformal

      public boolean conformal(Section other)

    • equalShape

      public boolean equalShape(Section other)

    • equals

      public boolean equals(Object o)
      Sections with equals Ranges are equal.
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Override Object.hashCode() to agree with equals.
      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()