Section (NetCDF-Java All API v5.7.0)

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. 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(java.util.List<Range> from)` Create Section from a List.
`Section(java.util.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(java.lang.String sectionSpec)` Parse an index section String specification, return equivilent Section.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`Section`	`addRangeNames(java.util.List<java.lang.String> rangeNames)` Deprecated. do not use
`Section`	`appendRange()` Deprecated. use builder().appendNullRange()
`Section`	`appendRange(int size)` Deprecated. use builder().appendRange(size)
`Section`	`appendRange(int first, int last)` Deprecated. use builder().appendRange
`Section`	`appendRange(int first, int last, int stride)` Deprecated. use builder().appendRange
`Section`	`appendRange(Range r)` Deprecated. use builder().appendRange(r)
`Section`	`appendRange(java.lang.String name, int first, int last, int stride)` Deprecated. use builder().appendRange
`static Section.Builder`	`builder()`
`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.
`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 relative 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(java.lang.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(java.lang.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
`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
`long`	`getSize()`
`int[]`	`getStride()` Deprecated. dont assume evenly strided
`int`	`getStride(int i)` Deprecated. dont assume evenly strided
`int`	`hashCode()` Override Object.hashCode() to agree with equals.
`Section`	`insertRange(int index, Range r)` Deprecated. use builder().insertRange
`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`	`isStrided()` Deprecated. dont assume evenly strided
`boolean`	`isVariableLength()`
`static Section`	`make(java.util.List<RangeIterator> rangeIter)`
`Section`	`makeImmutable()` Deprecated. use builder()
`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)`
`Section`	`removeLast()` Deprecated. use builder().removeLast()
`Section`	`removeRange(int index)` Deprecated. use builder().removeRange
`Section`	`removeVlen()` Deprecated. use builder().removeVlen()
`Section`	`replaceRange(int index, Range r)` Deprecated. use builder().replaceRange
`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)` Deprecated. use builder().setRange
`Section`	`shiftOrigin(int[] newOrigin)`
`Section`	`shiftOrigin(Section newOrigin)` Create a new Section by shifting each range by newOrigin.first() The result is then a relative offset from the newOrigin.
`java.lang.String`	`show()`
`Section`	`subSection(int fromIndex, int endExclusive)`
`Section.Builder`	`toBuilder()`
`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(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(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 dont 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 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(java.util.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 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
  - show
```
public java.lang.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(java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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 java.util.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(java.lang.String rangeName)
```
    Find a Range by its name.
    
    Parameters:
    
    rangeName - find this Range
    
    Returns:
    
    named Range or null
  - addRangeNames
```
@Deprecated
public Section addRangeNames(java.util.List<java.lang.String> rangeNames)
                                  throws InvalidRangeException
```
    Deprecated. do not use
    
    Throws:
    
    InvalidRangeException
  - checkInRange
```
public java.lang.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(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)
```
    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()
```

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

fill

make

compact

compose

intersect

offset

union

shiftOrigin

shiftOrigin

intersects

contains

toString

show

appendRange

appendRange

appendRange

appendRange

appendRange

appendRange

insertRange

removeRange

setRange

replaceRange

reduce

setDefaults

makeImmutable

subSection

removeLast

removeVlen

removeFirst

prepend

isImmutable

isVariableLength

isStrided

getShape

getOrigin

getStride

getOrigin

getShape

getStride

getSize

getRank

compatibleRank

computeSize

computeSize

getRanges

getRange

find

addRangeNames

checkInRange

equivalent

conformal

equalShape

equals

hashCode

getIterator

toBuilder

builder