Section (NetCDF-Java 4.2 Public and Private API)

java.lang.Object
- 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

Nested Classes
Modifier and Type Class and Description

class Section.Iterator

Nested Classes
Modifier and Type	Class and Description
`class`	`Section.Iterator`

Constructor Summary

Constructors
Constructor and Description
`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

Methods
Modifier and Type	Method and Description
`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`	`reduce()` Remove any ranges of length 1
`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
clone, finalize, 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
  - reduce
```
public Section reduce()
```
    Remove any ranges of length 1
    
    Returns:
    new Section if any Range had length 1, 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
```
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)
```

Class Section

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Section

Section

Section

Section

Section

Section

Section

Section

Method Detail

fill

compact

removeVlen

compose

intersect

offset

union

shiftOrigin

intersects

contains

toString

appendRange

appendRange

appendRange

appendRange

appendRange

appendRange

insertRange

removeRange

setRange

replaceRange

reduce

setDefaults

makeImmutable

isImmutable

getShape

getOrigin

getStride

getOrigin

getShape

getStride

getRank

computeSize

getRanges

getRange

find

addRangeNames

checkInRange

equivalent

equals

hashCode

getIterator