net.sf.sido.array
Class Range

java.lang.Object
  net.sf.sido.array.Range

public final class Range
extends Object

The Range class defines a range between two integers. It can also be a singleton (single-value range) or empty (nil). A Range is immutable.

Field Summary

static Range	NIL Empty range
static Pattern	REGEX Regular expression pattern used to parse a Range from a String.

Constructor Summary

Range(int value)
Singleton constructor

Range(int from, int to)
Constructor using two boundaries.

Method Summary

boolean	contains(int index) Tests if this range contains a given value
boolean	equals(Object obj) Compares two ranges.
Range	expand(int target) Returns a range that has been expanded to include the given target.
static Range	from(Collection<?> collection) Creates a range from the boundaries of a collection.
static Range	from(int offset, Collection<?> collection) Creates a range from the boundaries of a collection, and offsets it.
int	getFrom() Returns the minimum boundary.
int	getTo() Returns the maximum boundary.
int	hashCode() The hash code is computed from the boundaries
static int[]	indexes(Collection<?> collection) Gets a range from a collection and returns the corresponding indexes.
static int[]	indexes(int offset, Collection<?> collection) Gets a range from a collection, offsets it and returns the corresponding indexes.
boolean	isNil() Checks if this range is nil or not.
boolean	isSingleton() Checks if this range is a singleton.
static Range	nil() Returns the nil range
Range	offset(int offset) Creates a new range that is offset from this range.
int	size() Returns the size of this range.
Array<Integer>	toArray() Converts this range into an Array of Integer that contains all the indexes defined by this range.
static Array<Integer>	toArray(int from, int to) Utility method that creates an Array from a range.
static <T> Array<T>	toArray(int from, int to, com.google.common.base.Function<Integer,T> creator) Utility method that creates an Array from a range.
static <T,K> IndexedArray<T,K>	toIndexedArray(int from, int to, com.google.common.base.Function<Integer,T> creator, com.google.common.base.Function<T,K> indexer)
int[]	toIndexes() Returns the list of integers included in this range.
static <T> List<T>	toList(int from, int to, com.google.common.base.Function<Integer,T> creator)
String	toString() Returns a representation string for this range.
static Range	valueOf(String value) Parses a Range from a String.

Methods inherited from class java.lang.Object

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

Field Detail

REGEX

public static final Pattern REGEX

Regular expression pattern used to parse a Range from a String.

See Also:

valueOf(String)

NIL

public static final Range NIL

Empty range

Constructor Detail

Range

public Range(int value)

Singleton constructor

Range

public Range(int from,
             int to)

Constructor using two boundaries.

Parameters:

from - Minimum boundary

to - Maximum boundary

Throws:

IllegalArgumentException - If from is greater than to

Method Detail

from

public static Range from(Collection<?> collection)

Creates a range from the boundaries of a collection. The range will span from 0 to the size of the collection minus 1. An empty or null collection will return the nil range.

Parameters:

collection - Reference collection

Returns:

Range that spans the size of the collection

from

public static Range from(int offset,
                         Collection<?> collection)

Creates a range from the boundaries of a collection, and offsets it. The range will span from offset to the size of the collection minus 1 plus offset. An empty or null collection will return the nil range.

Parameters:

offset - Offset to apply to the range

collection - Reference collection

Returns:

Range that spans the size of the collection

See Also:

from(java.util.Collection)

indexes

public static int[] indexes(Collection<?> collection)

Gets a range from a collection and returns the corresponding indexes.

Parameters:

collection - Reference collection

Returns:

A list of indexes

See Also:

from(java.util.Collection), toIndexes()

indexes

public static int[] indexes(int offset,
                            Collection<?> collection)

Gets a range from a collection, offsets it and returns the corresponding indexes.

Parameters:

offset - Offset to apply

collection - Reference collection

Returns:

A list of indexes

See Also:

from(int, java.util.Collection), toIndexes()

nil

public static Range nil()

Returns the nil range

Returns:

nil range

toArray

public static Array<Integer> toArray(int from,
                                     int to)

Utility method that creates an Array from a range.

Parameters:

from - From boundary

to - To boundary

Returns:

An Array of Integer

See Also:

Range(int, int), toArray()

toArray

public static <T> Array<T> toArray(int from,
                                   int to,
                                   com.google.common.base.Function<Integer,T> creator)

Utility method that creates an Array from a range.

Parameters:

from - From boundary

to - To boundary

creator - Creates the item from an integer

Returns:

An Array

See Also:

Range(int, int), toArray()

valueOf

public static Range valueOf(String value)

Parses a Range from a String. The input string must be formatted like:

 [from{..to}]
 

If the input string is null, empty or equal to "[]", the returned range is nil.

Parameters:

value - Input string

Returns:

Range

contains

public boolean contains(int index)

Tests if this range contains a given value

Parameters:

index - Value to test

Returns:

true if index is included into this range, false otherwise.

equals

public boolean equals(Object obj)

Compares two ranges. Two ranges are equal if they are both not null and if their boundaries are equal.

Overrides:

equals in class Object

Parameters:

obj - Object to compare against

Returns:

Result of the comparison

expand

public Range expand(int target)

Returns a range that has been expanded to include the given target. If this range is nil, the returned range will be the single-value range that includes the target. If this range contains the target, it is returned unchanged.

Parameters:

target - Target to expand to

Returns:

Expanded range

getFrom

public int getFrom()

Returns the minimum boundary. It is 0 for a nil range.

Returns:

Minimum boundary

getTo

public int getTo()

Returns the maximum boundary. It is 0 for a nil range.

Returns:

Maximum boundary

hashCode

public int hashCode()

The hash code is computed from the boundaries

Overrides:

hashCode in class Object

Returns:

Hash code

isNil

public boolean isNil()

Checks if this range is nil or not.

Returns:

true if this range is nil, false otherwise.

isSingleton

public boolean isSingleton()

Checks if this range is a singleton. It is a singleton if it is not nil and if the two boundaries are equal to each other.

Returns:

Singleton

offset

public Range offset(int offset)

Creates a new range that is offset from this range.

A nil range is returned unchanged.

Examples:

 new Range(0,5).offset(0) ==> [0,5]
 new Range(0,5).offset(2) ==> [2,7]
 new Range(0,5).offset(-2) ==> [-2,3]
 

Parameters:

offset -

Returns:

size

public int size()

Returns the size of this range. A nil range has a size of zero.

Examples:

 Range.nil().size() ==> 0
 new Range(1).size() ==> 1
 new Range(1,2).size() ==> 2
 new Range(1,10).size() ==> 10
 new Range(5,15).size() ==> 11
 

Returns:

toArray

public Array<Integer> toArray()

Converts this range into an Array of Integer that contains all the indexes defined by this range. A nil range is converted into an empty Array.

Returns:

An Array of Integer

toIndexes

public int[] toIndexes()

Returns the list of integers included in this range. Examples:

 Range.nil().toIndexes() ==> []
 new Range(1).toIndexes() ==> [1]
 new Range(1,2).toIndexes() ==> [1,2]
 new Range(5,10).toIndexes() ==> [5,6,7,8,9,10]
 

Returns:

An array of integers

toString

public String toString()

Returns a representation string for this range.

Examples:

 Range.nil().toString() ==> "[]"
 new Range(1).toString() ==> "[1]"
 new Range(1,2).toString() ==> "[1..2]"
 new Range(5,10).toString() ==> "[5..10]"
 

Overrides:

toString in class Object

Returns:

A representation

toIndexedArray

public static <T,K> IndexedArray<T,K> toIndexedArray(int from,
                                                     int to,
                                                     com.google.common.base.Function<Integer,T> creator,
                                                     com.google.common.base.Function<T,K> indexer)

toList

public static <T> List<T> toList(int from,
                                 int to,
                                 com.google.common.base.Function<Integer,T> creator)