ucar.ma2
Class Range

java.lang.Object
  ucar.ma2.Range

public class Range
extends java.lang.Object

Represents a range of integers, used as an index set for arrays.

To extract array sections from arrays, it is necessary to define ranges of indices along axes of arrays. Range objects are used for that purpose.

Ranges are monotonically increasing. Elements must be nonnegative. Ranges can be empty, if last = first - 1.

Note last is inclusive, so standard iteration is

for (int i=range.first(); i<=range.last(); i+= range.stride()) {
   } 

Version:

$Revision:51 $ $Date:2006-07-12 17:13:13Z $

Author:

caron

Nested Class Summary

class

Range.Iterator

Constructor Summary

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(Range base, Range r)
Create a range by combining two other ranges.

Method Summary

static java.util.List	appendShape(java.util.List ranges, int size) Append a new Range(0,size-1) to the list
static java.lang.String	checkInRange(java.util.List section, int[] shape)
static long	computeSize(java.util.List section) /** Compute total number of elements represented by the section.
boolean	contains(int i) Is the ith element contained in this Range?
int	element(int i) Return the i-th element of a range.
protected int	elementNC(int i) Return the i-th element of a range, no check
boolean	equals(java.lang.Object o) Range elements with same first, last, stride are equal.
static java.util.List	factory(int[] shape) Convert shape array to List of Ranges.
static java.util.List	factory(int[] origin, int[] shape) Convert shape, origin array to List of Ranges.
int	first() first in range
int	getFirstInInterval(int 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.
Range.Iterator	getIterator() Iterate over Range index Usage:
java.lang.String	getName() Get name
static int[]	getOrigin(java.util.List ranges) Convert List of Ranges to origin array using the range.first.
static int[]	getShape(java.util.List ranges) Convert List of Ranges to shape array using the range.length.
int	hashCode() Override Object.hashCode() to implement equals.
int	last() last in range, inclusive
int	length() Return the number of elements in the range.
static java.lang.String	makeSectionSpec(java.util.List ranges) Convert List of Ranges to String Spec.
int	max() Maximum index, inclusive.
int	min() Minimum index, inclusive.
static java.util.List	parseSpec(java.lang.String sectionSpec) Parse an index section String specification, return equivilent list of ucar.ma2.Range objects.
static java.util.List	setDefaults(java.util.List rangeList, int[] shape) Check rangeList has no nulls, set from shape array.
void	setName(java.lang.String name) Set name
int	stride() stride, may be negetive
static Range[]	toArray(java.util.List ranges) Convert List of Ranges to array of Ranges.
static java.util.List	toList(Range[] ranges) Convert array of Ranges to List of Ranges.
java.lang.String	toString()
static java.lang.String	toString(java.util.List ranges)

Methods inherited from class java.lang.Object

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

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

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 (positive or negative)

Throws:

InvalidRangeException - elements must be nonnegative

Range

public Range(Range r)
      throws InvalidRangeException

Copy Constructor

Throws:

InvalidRangeException

Range

public Range(Range base,
             Range r)
      throws InvalidRangeException

Create a range by combining two other ranges.

Parameters:

base - base range

r - range reletive to base

Throws:

InvalidRangeException - elements must be nonnegative

Method Detail

factory

public static java.util.List factory(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)

Check rangeList has no nulls, set from shape array.

factory

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

Convert shape, origin array to List of Ranges.

Throws:

InvalidRangeException

getShape

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

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

toString

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

computeSize

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

/** 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

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)

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

toArray

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

Convert List of Ranges to array of Ranges.

toList

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

Convert array of Ranges to List of Ranges.

makeSectionSpec

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

Convert List of Ranges to String Spec. Inverse of parseSpec

parseSpec

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

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)

getName

public java.lang.String getName()

Get name

setName

public void setName(java.lang.String name)

Set name

length

public int length()

Return the number of elements in the range.

element

public int element(int i)
            throws InvalidRangeException

Return the i-th element of a range.

Parameters:

i - index of the element

Throws:

InvalidRangeException - 0 <= i < length

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

elementNC

protected int elementNC(int i)

Return the i-th element of a range, no check

Parameters:

i - index of the element

first

public int first()

first in range

last

public int last()

last in range, inclusive

stride

public int stride()

stride, may be negetive

min

public int min()

Minimum index, inclusive.

max

public int max()

Maximum index, inclusive.

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

getIterator

public Range.Iterator getIterator()

Iterate over Range index Usage:

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

getFirstInInterval

public int getFirstInInterval(int 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.

return -1 if there is no such element.