ucar.ma2

Class Range

java.lang.Object

ucar.ma2.Range

public final class Range
extends java.lang.Object

Represents a set of integers, used as an index for arrays. It should be considered as a subset of the interval of integers [0, length-1] inclusive. For example Range(1:11:3) represents the set of integers {1,4,7,10} Immutable.

Ranges are monotonically increasing. Elements must be nonnegative. EMPTY is the empty Range. VLEN is for variable length dimensions.

Note last is inclusive, so standard iteration is

 for (int i=range.first(); i<=range.last(); i+= range.stride()) {
   ...
 }
 or use:
 Range.Iterator iter = timeRange.getIterator();
 while (iter.hasNext()) {
   int index = iter.next();
   ...
 }
 

Author:

caron

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Range.Iterator

Field Summary

Fields

Modifier and Type	Field and Description
static Range	EMPTY
static Range	VLEN

Constructor Summary

Constructors

Constructor and Description
Range(int length) Create a range starting at zero, with unit stride.
Range(int first, int last) Create a range with unit stride.
Range(int first, int last, int stride) Create a range with a specified stride.
Range(Range r) Copy Constructor
Range(java.lang.String name, int first, int last) Create a named range with unit stride.
Range(java.lang.String name, int first, int last, int stride) Create a named range with a specified stride.
Range(java.lang.String name, Range r) Copy Constructor with name

Method Summary

Methods

Modifier and Type	Method and Description
static java.util.List	appendShape(java.util.List ranges, int size) Deprecated. use Section.appendRange(int size)
static java.lang.String	checkInRange(java.util.List section, int[] shape) Deprecated. use Section.checkInRange(int shape[])
Range	compact() Create a new Range by compacting this Range by removing the stride.
Range	compose(Range r) Create a new Range by composing a Range that is reletive to this Range.
static long	computeSize(java.util.List section) Deprecated. use Section.computeSize()
boolean	contains(int i) Is the ith element contained in this Range?
int	element(int i) Get ith element
boolean	equals(java.lang.Object o) Range elements with same first, last, stride are equal.
static java.util.List	factory(int[] shape) Deprecated. use Section(int[] shape)
static java.util.List	factory(int[] origin, int[] shape) Deprecated. use Section(int[] origin, int[] shape)
int	first()
int	getFirstInInterval(int start) Find the first element in a strided array after some index start.
Range.Iterator	getIterator() Iterate over Range index Usage:
java.lang.String	getName() Get name
static int[]	getOrigin(java.util.List ranges) Deprecated. use Section.getOrigin()
static int[]	getShape(java.util.List ranges) Deprecated. use Section.getShape()
int	hashCode() Override Object.hashCode() to implement equals.
int	index(int elem) Get the index for this element: inverse of element
Range	intersect(Range r) Create a new Range by intersecting with a Range using same interval as this Range.
boolean	intersects(Range r) Determine if a given Range intersects this one.
int	last()
int	length() Get the number of elements in the range.
static java.lang.String	makeSectionSpec(java.util.List ranges) Deprecated. use Section.toString()
int	max() Deprecated. use last()
int	min() Deprecated. use first()
static java.util.List	parseSpec(java.lang.String sectionSpec) Deprecated. use new Section(String sectionSpec)
boolean	past(Range want) If this range is completely past the wanted range
static java.util.List	setDefaults(java.util.List rangeList, int[] shape) Deprecated. use Section.setDefaults(int[] shape)
Range	shiftOrigin(int origin) Create a new Range shifting this range by a constant factor.
int	stride()
static Range[]	toArray(java.util.List ranges) Deprecated. use Section.getRanges()
static java.util.List	toList(Range[] ranges) Deprecated. use Section.getRanges()
java.lang.String	toString()
static java.lang.String	toString(java.util.List ranges) Deprecated. use Section.toString()
Range	union(Range r) Create a new Range by making the union with a Range using same interval as this Range.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY

public static final Range EMPTY

VLEN

public static final Range VLEN

Constructor Detail

Range

public Range(int first,
     int last)
      throws InvalidRangeException

Create a range with unit stride.

Parameters:

first - first value in range

last - last value in range, inclusive

Throws:

InvalidRangeException - elements must be nonnegative, 0 <= first <= last

Range

public Range(int length)

Create a range starting at zero, with unit stride.

Parameters:

length - number of elements in the Rnage

Range

public Range(java.lang.String name,
     int first,
     int last)
      throws InvalidRangeException

Create a named range with unit stride.

Parameters:

name - name of Range

first - first value in range

last - last value in range, inclusive

Throws:

InvalidRangeException - elements must be nonnegative, 0 <= first <= last

Range

public Range(int first,
     int last,
     int stride)
      throws InvalidRangeException

Create a range with a specified stride.

Parameters:

first - first value in range

last - last value in range, inclusive

stride - stride between consecutive elements, must be > 0

Throws:

InvalidRangeException - elements must be nonnegative: 0 <= first <= last, stride > 0

Range

public Range(java.lang.String name,
     int first,
     int last,
     int stride)
      throws InvalidRangeException

Create a named range with a specified stride.

Parameters:

name - name of Range

first - first value in range

last - last value in range, inclusive

stride - stride between consecutive elements, must be > 0

Throws:

InvalidRangeException - elements must be nonnegative: 0 <= first <= last, stride > 0

Range

public Range(Range r)

Copy Constructor

Parameters:

r - copy from here

Range

public Range(java.lang.String name,
     Range r)

Copy Constructor with name

Parameters:

name - result name

r - copy from here

Method Detail

compose

public Range compose(Range r)
              throws InvalidRangeException

Create a new Range by composing a Range that is reletive to this Range.

Parameters:

r - range reletive to base

Returns:

combined Range, may be EMPTY

Throws:

InvalidRangeException - elements must be nonnegative, 0 <= first <= last

compact

public Range compact()
              throws InvalidRangeException

Create a new Range by compacting this Range by removing the stride. first = first/stride, last=last/stride, stride=1.

Returns:

compacted Range

Throws:

InvalidRangeException - elements must be nonnegative, 0 <= first <= last

shiftOrigin

public Range shiftOrigin(int origin)
                  throws InvalidRangeException

Create a new Range shifting this range by a constant factor.

Parameters:

origin - subtract this from first, last

Returns:

shiften range

Throws:

InvalidRangeException - elements must be nonnegative, 0 <= first <= last

intersect

public Range intersect(Range r)
                throws InvalidRangeException

Create a new Range by intersecting with a Range using same interval as this Range. NOTE: we dont yet support intersection when both Ranges have strides

Parameters:

r - range to intersect

Returns:

intersected Range, may be EMPTY

Throws:

InvalidRangeException - elements must be nonnegative

intersects

public boolean intersects(Range r)

Determine if a given Range intersects this one. NOTE: we dont yet support intersection when both Ranges have strides

Parameters:

r - range to intersect

Returns:

true if they intersect

Throws:

java.lang.UnsupportedOperationException - if both Ranges have strides

past

public boolean past(Range want)

If this range is completely past the wanted range

Parameters:

want - desired range

Returns:

true if first() > want.last()

union

public Range union(Range r)
            throws InvalidRangeException

Create a new Range by making the union with a Range using same interval as this Range. NOTE: no strides

Parameters:

r - range to add

Returns:

intersected Range, may be EMPTY

Throws:

InvalidRangeException - elements must be nonnegative

length

public int length()

Get the number of elements in the range.

Returns:

the number of elements in the range.

element

public int element(int i)
            throws InvalidRangeException

Get ith element

Parameters:

i - index of the element

Returns:

the i-th element of a range.

Throws:

InvalidRangeException - i must be: 0 <= i < length

index

public int index(int elem)
          throws InvalidRangeException

Get the index for this element: inverse of element

Parameters:

elem - the element of the range

Returns:

index

Throws:

InvalidRangeException - if illegal elem

contains

public boolean contains(int i)

Is the ith element contained in this Range?

Parameters:

i - index in the original Range

Returns:

true if the ith element would be returned by the Range iterator

first

public int first()

Returns:

first in range

last

public int last()

Returns:

last in range, inclusive

stride

public int stride()

Returns:

stride, must be >= 1

getName

public java.lang.String getName()

Get name

Returns:

name, or null if none

getIterator

public Range.Iterator getIterator()

Iterate over Range index Usage:

 Iterator iter = range.getIterator();
 while (iter.hasNext()) {
   int index = iter.next();
   doSomething(index);
 }
 

Returns:

Iterator over element indices

getFirstInInterval

public int getFirstInInterval(int start)

Find the first element in a strided array after some index start. Return the smallest element k in the Range, such that

• k >= first
• k >= start
• k <= last
• k = first + i * stride for some integer i.

Parameters:

start - starting index

Returns:

first in interval, else -1 if there is no such element.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Range elements with same first, last, stride are equal.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Override Object.hashCode() to implement equals.

Overrides:

hashCode in class java.lang.Object

min

public int min()

Deprecated. use first()

Returns:

Minimum index, inclusive.

max

public int max()

Deprecated. use last()

Returns:

Maximum index, inclusive.

factory

public static java.util.List factory(int[] shape)

Deprecated. use Section(int[] shape)

Convert shape array to List of Ranges. Assume 0 origin for all.

setDefaults

public static java.util.List setDefaults(java.util.List rangeList,
                         int[] shape)

Deprecated. use Section.setDefaults(int[] shape)

Check rangeList has no nulls, set from shape array.

factory

public static java.util.List factory(int[] origin,
                     int[] shape)
                              throws InvalidRangeException

Deprecated. use Section(int[] origin, int[] shape)

Convert shape, origin array to List of Ranges.

Throws:

InvalidRangeException

getShape

public static int[] getShape(java.util.List ranges)

Deprecated. use Section.getShape()

Convert List of Ranges to shape array using the range.length.

toString

public static java.lang.String toString(java.util.List ranges)

Deprecated. use Section.toString()

computeSize

public static long computeSize(java.util.List section)

Deprecated. use Section.computeSize()

/** Compute total number of elements represented by the section.

Parameters:

section - List of Range objects

Returns:

total number of elements

appendShape

public static java.util.List appendShape(java.util.List ranges,
                         int size)
                                  throws InvalidRangeException

Deprecated. use Section.appendRange(int size)

Append a new Range(0,size-1) to the list

Parameters:

ranges - list of Range

size - add this Range

Returns:

same list

Throws:

InvalidRangeException - if size < 1

getOrigin

public static int[] getOrigin(java.util.List ranges)

Deprecated. use Section.getOrigin()

Convert List of Ranges to origin array using the range.first.

toArray

public static Range[] toArray(java.util.List ranges)

Deprecated. use Section.getRanges()

Convert List of Ranges to array of Ranges. *

toList

public static java.util.List toList(Range[] ranges)

Deprecated. use Section.getRanges()

Convert array of Ranges to List of Ranges.

makeSectionSpec

public static java.lang.String makeSectionSpec(java.util.List ranges)

Deprecated. use Section.toString()

Convert List of Ranges to String Spec. Inverse of parseSpec

parseSpec

public static java.util.List parseSpec(java.lang.String sectionSpec)
                                throws InvalidRangeException

Deprecated. use new Section(String sectionSpec)

Parse an index section String specification, return equivilent list of ucar.ma2.Range objects. 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

Returns:

return List of ucar.ma2.Range objects corresponding to the index selection. A null Range means "all" (i.e.":") indices in that dimension.

Throws:

java.lang.IllegalArgumentException - when sectionSpec is misformed

InvalidRangeException

checkInRange

public static java.lang.String checkInRange(java.util.List section,
                            int[] shape)

Deprecated. use Section.checkInRange(int shape[])

Check ranges are valid

Parameters:

section -

shape -

Returns:

error message, or null if all ok