Section (NetCDF-Java CDM Public API v5.4.2)

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

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Section.Builder

class Section.Iterator

Nested Classes
Modifier and Type	Class and Description
`static class`	`Section.Builder`
`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(List<Range> from)` Create Section from a List.
`Section(List<Range> from, int[] shape)` Create Section from a List.
`Section(Range... ranges)` Create Section from a variable length list of Ranges
`Section(Section from)` Copy Constructor.
`Section(String sectionSpec)` Parse an index section String specification, return equivilent Section.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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.
`boolean`	`compatibleRank(Section other)` Compare this section with another upto the vlen in either
`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.
`static long`	`computeSize(int[] shape)`
`boolean`	`conformal(Section other)`
`boolean`	`contains(Section other)` See if this Section contains another Section.
`boolean`	`equals(Object o)` Sections with equals Ranges are equal.
`boolean`	`equalShape(Section other)`
`boolean`	`equivalent(int[] shape)` Is this section equivilent to the given 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 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
`long`	`getSize()`
`int`	`hashCode()` Override Object.hashCode() to agree with equals.
`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()`
`boolean`	`isVariableLength()`
`static Section`	`make(List<RangeIterator> rangeIter)`
`int`	`offset(Section intersect)` Compute the element offset of an intersecting subrange of this.
`Section`	`prepend(Section parentSection)`
`Section`	`reduce()` Remove any ranges of length 1
`Section`	`removeFirst(Section parentSection)`
`void`	`setDefaults(int[] shape)` If any of the ranges are null, which means "all", set the Range from the corresponding length in shape[].
`Section`	`shiftOrigin(int[] newOrigin)`
`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.
`String`	`show()`
`Section`	`subSection(int fromIndex, int endExclusive)`
`Section.Builder`	`toBuilder()`
`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()
```
    No-arg Constructor
  - 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(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(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(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
  - builder
```
public static Section.Builder builder()
```
  - 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
  - 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
  - compatibleRank
```
public boolean compatibleRank(Section other)
```
    Compare this section with another upto the vlen in either
  - 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
  - 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)
```
  - conformal
```
public boolean conformal(Section other)
```
  - 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
  - equals
```
public boolean equals(Object o)
```
    Sections with equals Ranges are equal.
    
    Overrides:
    
    equals in class Object
  - equalShape
```
public boolean equalShape(Section other)
```
  - 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
  - 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
  - find
```
@Nullable
public Range find(String rangeName)
```
    Find a Range by its name.
    
    Parameters:
    
    rangeName - find this Range
    
    Returns:
    
    named Range or null
  - 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
  - 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
  - getRange
```
public Range getRange(int i)
```
    Get the ith Range
    
    Parameters:
    
    i - index into the list of Ranges
    
    Returns:
    
    ith Range
  - getRanges
```
public List<Range> getRanges()
```
    Get the list of Ranges.
  - getRank
```
public int getRank()
```
    Get rank - number of Ranges.
    
    Returns:
    
    rank
  - getShape
```
public int[] getShape()
```
    Get shape array using the Range.length() values.
    
    Returns:
    
    int[] shape
  - 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()
```
  - hashCode
```
public int hashCode()
```
    Override Object.hashCode() to agree with equals.
    
    Overrides:
    
    hashCode in class Object
  - 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
  - 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(),
  - isImmutable
```
public boolean isImmutable()
```
  - isVariableLength
```
public boolean isVariableLength()
```
  - make
```
public static Section make(List<RangeIterator> rangeIter)
```
  - 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
  - prepend
```
public Section prepend(Section parentSection)
```
  - reduce
```
public Section reduce()
```
    Remove any ranges of length 1
    
    Returns:
    
    new Section if any Ranges needed replacement, else this
  - removeFirst
```
public Section removeFirst(Section parentSection)
```
  - 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
  - shiftOrigin
```
public Section shiftOrigin(int[] newOrigin)
                    throws InvalidRangeException
```
    Throws:
    
    InvalidRangeException
  - 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()
  - show
```
public String show()
```
  - subSection
```
public Section subSection(int fromIndex,
                          int endExclusive)
```
  - toBuilder
```
public Section.Builder toBuilder()
```
  - 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
  - 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

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

Section

Method Detail

builder

checkInRange

compact

compatibleRank

compose

computeSize

computeSize

conformal

contains

equals

equalShape

equivalent

fill

find

getIterator

getOrigin

getOrigin

getRange

getRanges

getRank

getShape

getShape

getSize

hashCode

intersect

intersects

isImmutable

isVariableLength

make

offset

prepend

reduce

removeFirst

setDefaults

shiftOrigin

shiftOrigin

show

subSection

toBuilder

toString

union