Package ucar.array

Class Range

java.lang.Object

ucar.array.Range

All Implemented Interfaces:

Iterable<Integer>, RangeIterator

@Immutable
public class Range
extends Object
implements RangeIterator

A strided subset of the interval of positive integers [first(), last()] inclusive. For example Range(1:11:3) represents the set of integers {1,4,7,10}

Elements must be nonnegative and unique. EMPTY is the empty Range. SCALAR is the set {0}. 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	SCALAR
static Range	VLEN

Constructor Summary

Constructors

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 first, last, stride.
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, first, last, stride.

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 reletive 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)	Does not include the name.
int	first()	The first value in range
int	getFirstInInterval(int start)	Find the first element in a strided array after some index start.
int	hashCode()
int	index(int want)	Given an element in the Range, find its index in the array of elements.
Range	intersect(Range other)	Create a new Range by intersecting with another Range.
boolean	intersects(Range other)	Determine if a given Range interval intersects this one.
Iterator<Integer>	iterator()
int	last()	The last value in range, inclusive
int	length()	The number of elements in the range.
static Range	make(int first, int last)	Make an unnamed Range from first to last.
static Range	make(int first, int last, int stride)	Make an unnamed Range from first to last with stride.
static Range	make(String name, int len)	Make a named Range from 0 to len-1.
String	name()	The name of this Range iterator.
int	stride()	The stride, must be ≥ 1.
String	toString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

EMPTY

public static final Range EMPTY

SCALAR

public static final Range SCALAR

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

Create a named range with a specified name, first, last, 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

Method Detail

make

public static Range make(String name,
                         int len)

Make a named Range from 0 to len-1. RuntimeException on error.

make

public static Range make(int first,
                         int last)

Make an unnamed Range from first to last. RuntimeException on error.

make

public static Range make(int first,
                         int last,
                         int stride)

Make an unnamed Range from first to last with stride. RuntimeException on error.

copyWithStride

public Range copyWithStride(int stride)
                     throws InvalidRangeException

Make a copy with a different stride.

Throws:

InvalidRangeException

copyWithName

public Range copyWithName(String name)

Make a copy with a different name.

Specified by:

copyWithName in interface RangeIterator

name

@Nullable
public String name()

Description copied from interface: RangeIterator

The name of this Range iterator.

Specified by:

name in interface RangeIterator

Returns:

name, or null if none

first

public int first()

The first value in range

last

public int last()

The last value in range, inclusive

length

public int length()

The number of elements in the range.

Specified by:

length in interface RangeIterator

stride

public int stride()

The stride, must be ≥ 1.

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 reletive to this Range.

Parameters:

r - range elements are reletive to this

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

Given an element in the Range, find its index in the array of elements.

Parameters:

want - the element of the range

Returns:

index

Throws:

InvalidRangeException - if illegal elem

intersect

public Range intersect(Range other)
                throws InvalidRangeException

Create a new Range by intersecting with another Range. One of them must have stride 1.

Parameters:

other - range to intersect..

Returns:

intersected Range, may be EMPTY

Throws:

InvalidRangeException

intersects

public boolean intersects(Range other)

Determine if a given Range interval intersects this one.

Parameters:

other - range to intersect

Returns:

true if their intervals intersect, ignoring stride.

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)

Does not include the name.

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

iterator

public Iterator<Integer> iterator()

Specified by:

iterator in interface Iterable<Integer>

Specified by:

iterator in interface RangeIterator