Section (cdm-core 6.0.0-beta1 API)

java.lang.Object
- ucar.array.Section

```
@Immutable
public class Section
extends Object
```
A section of multidimensional array indices. Represented as List.
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`

Field Summary

Fields
Modifier and Type Field and Description

static Section SCALAR

Fields
Modifier and Type	Field and Description
`static Section`	`SCALAR`

Constructor Summary

Constructors
Constructor and Description
`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(List<Range> from)` Create Section from a List.
`Section(List<Range> from, int[] shape)` LOOK can this replace ParsedSectionSpec ?? Create Section from a List, filling in nulls with shape.
`Section(Range... ranges)` Create Section from a variable length argument list of Ranges
`Section(String sectionSpec)` LOOK can this replace ParsedSectionSpec ?? 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.
`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`	`equals(Object o)`
`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 an unmodifyable 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()`
`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`	`isVariableLength()` Does this contain a VLEN range?
`int`	`offset(Section intersect)` Compute the element offset of an intersecting subrange of this.
`Section.Builder`	`toBuilder()`
`String`	`toString()` Convert List of Ranges to String sectionSpec.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - SCALAR
```
public static final Section SCALAR
```
- 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(List<Range> from)
```
    Create Section from a List.
  - Section
```
public Section(Range... ranges)
```
    Create Section from a variable length argument list of Ranges
  - Section
```
public Section(List<Range> from,
               int[] shape)
        throws InvalidRangeException
```
    LOOK can this replace ParsedSectionSpec ?? Create Section from a List, filling in nulls with shape.
    
    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
```
    LOOK can this replace ParsedSectionSpec ?? 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
  - 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 it 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
  - 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
```
    Compute the element offset of an intersecting subrange of this.
    
    Parameters:
    
    intersect - the subrange
    
    Returns:
    
    element offset
    
    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(),
  - toString
```
public String toString()
```
    Convert List of Ranges to String sectionSpec. Inverse of new Section(String sectionSpec)
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    index section String specification
  - isVariableLength
```
public boolean isVariableLength()
```
    Does this contain a VLEN range?
  - 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[] stride
  - getOrigin
```
public int getOrigin(int i)
```
    Get origin of the ith Range
  - getShape
```
public int getShape(int i)
```
    Get length of the ith Range
  - getStride
```
public int getStride(int i)
```
    Get stride of the ith Range
  - getRank
```
public int getRank()
```
    Get rank = number of Ranges.
  - computeSize
```
public long computeSize()
```
    Compute total number of elements represented by the section. Any null or VLEN Ranges are skipped.
    
    Returns:
    
    total number of elements
  - getRanges
```
public List<Range> getRanges()
```
    Get an unmodifyable 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]
    
    Throws:
    
    InvalidRangeException
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    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()
```

Class Section

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SCALAR

Constructor Detail

Section

Section

Section

Section

Section

Section

Method Detail

fill

compact

compose

intersect

offset

intersects

toString

isVariableLength

getShape

getOrigin

getStride

getOrigin

getShape

getStride

getRank

computeSize

getRanges

getRange

find

checkInRange

equivalent

equals

hashCode

getIterator

toBuilder

builder