Package ucar.ma2

Class Range

java.lang.Object

ucar.ma2.Range

All Implemented Interfaces:

Iterable<Integer>, RangeIterator

@Immutable
public class Range
extends Object
implements RangeIterator

Represents a set of integers, used as an index for arrays. No duplicates are allowed. It should be considered as a subset of the interval of integers [first(), last()] inclusive. For example Range(1:11:3) represents the set of integers {1,4,7,10} Note that Range no longer is always strided or monotonic. Immutable.

Elements must be nonnegative and unique. EMPTY is the empty Range. VLEN is for variable length dimensions.

Standard iteration is

  for (int idx : range) {
    ...
  }
 

Field Summary

Fields

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

Constructor Summary

Constructors

Modifier	Constructor	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 values.
	Range(String name, int first, int last)	Create a named range with unit stride.
	Range(String name, int first, int last, int stride)	Create a named range with a specified name and values.
protected	Range(String name, int first, int last, int stride, int length)

Method Summary

Modifier and Type	Method	Description
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 relative to this Range.
boolean	contains(int want)	Is want contained in this Range?
Range	copyWithName(String name)	Make a copy with a different name.
Range	copyWithStride(int stride)	Make a copy with a different stride.
int	element(int i)	Get ith element
boolean	equals(Object o)	Range elements with same first, last, stride are equal.
int	first()
int	getFirstInInterval(int start)	Find the first element in a strided array after some index start.
Iterator<Integer>	getIterator()	Deprecated. use iterator() or foreach
String	getName()	The name of this Range iterator.
int	hashCode()	Override Object.hashCode() to implement equals.
int	index(int want)	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.
Iterator<Integer>	iterator()
int	last()
int	length()	The number of index in this iterator.
static Range	make(int first, int last)
static Range	make(String name, int len)
boolean	past(Range want)	If this range is completely past the wanted range
Range	setName(String name)	Deprecated. use copyWithName()
Range	setStride(int stride)	Deprecated. use copyWithStride()
Range	shiftOrigin(int origin)	Create a new Range shifting this range by a constant factor.
int	stride()
String	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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

EMPTY

public static final Range EMPTY

ONE

public static final Range ONE

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 Range

Range

public Range(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 values.

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(String name,
             int first,
             int last,
             int stride)
      throws InvalidRangeException

Create a named range with a specified name and values.

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

protected Range(String name,
                int first,
                int last,
                int stride,
                int length)
         throws InvalidRangeException

Throws:

InvalidRangeException

Method Detail

make

public static Range make(String name,
                         int len)

make

public static Range make(int first,
                         int last)

setStride

@Deprecated
public Range setStride(int stride)
                throws InvalidRangeException

Deprecated.

use copyWithStride()

Throws:

InvalidRangeException

copyWithStride

public Range copyWithStride(int stride)
                     throws InvalidRangeException

Make a copy with a different stride.

Throws:

InvalidRangeException

setName

@Deprecated
public Range setName(String name)

Deprecated.

use copyWithName()

Specified by:

setName in interface RangeIterator

copyWithName

public Range copyWithName(String name)

Make a copy with a different name.

Specified by:

copyWithName in interface RangeIterator

getName

public String getName()

Description copied from interface: RangeIterator

The name of this Range iterator.

Specified by:

getName in interface RangeIterator

Returns:

name, or null if none

first

public int first()

Returns:

first in range

last

public int last()

Returns:

last in range, inclusive

length

public int length()

Description copied from interface: RangeIterator

The number of index in this iterator.

Specified by:

length in interface RangeIterator

Returns:

the number of elements in the range.

stride

public int stride()

Returns:

stride, must be >= 1 when evenly strided, -1 if not // * @deprecated use iterator(), dont assume evenly strided

contains

public boolean contains(int want)

Is want contained in this Range?

Parameters:

want - index in the original Range

Returns:

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

compose

public Range compose(Range r)
              throws InvalidRangeException

Create a new Range by composing a Range that is relative to this Range. Revised 2013/04/19 by Dennis Heimbigner to handle edge cases. See the commentary associated with the netcdf-c file dceconstraints.h, function dceslicecompose().

Parameters:

r - range relative 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

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 want)
          throws InvalidRangeException

Get the index for this element: inverse of element

Parameters:

want - the element of the range

Returns:

index

Throws:

InvalidRangeException - if illegal elem

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:

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()

shiftOrigin

public Range shiftOrigin(int origin)
                  throws InvalidRangeException

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

Parameters:

origin - subtract this from each element

Returns:

shifted range

Throws:

InvalidRangeException - elements must be nonnegative, 0 <= first <= 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

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 = element of this Range

Parameters:

start - starting index

Returns:

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

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

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

Overrides:

equals in class Object

hashCode

public int hashCode()

Override Object.hashCode() to implement equals.

Overrides:

hashCode in class Object

getIterator

public Iterator<Integer> getIterator()

Deprecated.

use iterator() or foreach

Iterate over Range index

Returns:

Iterator over element indices

iterator

public Iterator<Integer> iterator()

Specified by:

iterator in interface Iterable<Integer>

Specified by:

iterator in interface RangeIterator