Package ucar.array
Class Section
- 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 Description static class
Section.Builder
class
Section.Iterator
-
Constructor Summary
Constructors Constructor 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(String sectionSpec)
Parse an index section String specification, return equivilent Section.Section(List<Range> from)
Create Section from a List. Section(List<Range> from, int[] shape)
Create Section from a List, filling in nulls with shape. Section(Range... ranges)
Create Section from a variable length argument list of Ranges
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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.Section
fill(int[] shape)
Fil any null sections with the ccorresponding value from 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 RangeRange
getRange(int i)
Get the ith RangeList<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 Rangeint[]
getStride()
Get stride array using the Range.stride() values.int
getStride(int i)
Get stride of the ith Rangeint
hashCode()
Section
intersect(Section other)
Create a new Section by intersection with another Sectionboolean
intersects(Section other)
See if this Section intersects with another Section.static boolean
isScalar(int[] shape)
Is this a scalar Section? Allows int[], int[1] {0}, int[1] {1}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.
-
-
-
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 Rangeshape
- array of lengths for each Range- Throws:
InvalidRangeException
- if origin < 0, or shape < 1.
-
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
Create Section from a List, filling in nulls with shape. - Parameters:
from
- the list of Rangeshape
- 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 illegalIllegalArgumentException
- 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 filledshape
- 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
-
isScalar
public static boolean isScalar(int[] shape)
Is this a scalar Section? Allows int[], int[1] {0}, int[1] {1}
-
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)
-
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
-
getRange
public Range getRange(int i)
Get the ith Range- Parameters:
i
- index into the list of Ranges- Returns:
- ith Range
-
fill
public Section fill(int[] shape) throws InvalidRangeException
Fil any null sections with the ccorresponding value from shape.- Throws:
InvalidRangeException
-
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
-
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()
-
-