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

    • appendRange

      @Deprecated public Section appendRange()
      Deprecated.
      use builder().appendNullRange()
      Append a null Range to the Section - meaning "all"
      Returns:
      this

    • appendRange

      @Deprecated public Section appendRange(Range r)
      Deprecated.
      use builder().appendRange(r)
      Append a Range to the Section
      Returns:
      this

    • appendRange

      @Deprecated public Section appendRange(int size)
      Deprecated.
      use builder().appendRange(size)
      Append a new Range(0,size-1) to the Section
      Parameters:
      size - add this Range
      Returns:
      this

    • appendRange

      @Deprecated public Section appendRange(int first, int last) throws InvalidRangeException
      Deprecated.
      use builder().appendRange
      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

      @Deprecated public Section appendRange(int first, int last, int stride) throws InvalidRangeException
      Deprecated.
      use builder().appendRange
      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

      @Deprecated public Section appendRange(String name, int first, int last, int stride) throws InvalidRangeException
      Deprecated.
      use builder().appendRange
      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

      @Deprecated public Section insertRange(int index, Range r)
      Deprecated.
      use builder().insertRange
      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:
      IndexOutOfBoundsException - if bad index

    • removeRange

      @Deprecated public Section removeRange(int index)
      Deprecated.
      use builder().removeRange
      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:
      IndexOutOfBoundsException - if bad index

    • setRange

      @Deprecated public Section setRange(int index, Range r)
      Deprecated.
      use builder().setRange
      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:
      IndexOutOfBoundsException - if bad index

    • replaceRange

      @Deprecated public Section replaceRange(int index, Range r)
      Deprecated.
      use builder().replaceRange
      Replace a range at the specified index in the list.
      Parameters:
      index - replace here in the list.
      r - use this Range
      Returns:
      this
      Throws:
      IndexOutOfBoundsException - if bad index

    • 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

    • makeImmutable

      @Deprecated public Section makeImmutable()
      Deprecated.
      use builder()
      Makes the object immutable, so can be safely shared
      Returns:
      this Section

    • subSection

      public Section subSection(int fromIndex, int endExclusive)

    • removeLast

      @Deprecated public Section removeLast()
      Deprecated.
      use builder().removeLast()

    • removeVlen

      @Deprecated public Section removeVlen()
      Deprecated.
      use builder().removeVlen()

    • removeFirst

      public Section removeFirst(Section parentSection)

    • prepend

      public Section prepend(Section parentSection)

    • isImmutable

      public boolean isImmutable()

    • isVariableLength

      public boolean isVariableLength()

    • isStrided

      @Deprecated public boolean isStrided()
      Deprecated.
      dont assume evenly strided

    • 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()
      Deprecated.
      dont assume evenly strided
      Get stride array using the Range.stride() values.
      Returns:
      int[] stride

    • 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)
      Deprecated.
      dont assume evenly strided
      Get stride of the ith Range
      Parameters:
      i - index of Range
      Returns:
      stride 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

    • addRangeNames

      @Deprecated public Section addRangeNames(List<String> rangeNames) throws InvalidRangeException
      Deprecated.
      do not use
      Throws:
      InvalidRangeException

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