Class IntRanges

In this topic

Package com.ms.util Previous This
Package Next

Class IntRanges

public class IntRanges implements Cloneable, SetComparison
{
  // Constructors
  public IntRanges ();
  public IntRanges (String str);
  public IntRanges (String str, String delims);

  // Methods
  public synchronized void addRange (int s, int e);
  public synchronized void addRanges (IntRanges r);
  public synchronized void addSingleton (int n);
  public StringBuffer appendToStringBuffer (StringBuffer sb);
  protected Object clone ();
  public int compare (IntRanges other);
  public int compare (IntRanges other, IIntRangeComparator judge);
  public int compareSet (Object other);
  public static String ComparisonResulttoString (int cmp);
  public synchronized void condense (IIntRangeComparator judge);
  public void condense ();
  public boolean contains (int find);
  public synchronized boolean contains (int s, int e);
  public synchronized IntRanges copy ();
  public int getRangeEnd (int idx);
  public synchronized int[] getRanges ();
  public int getRangeStart (int idx);
  public synchronized int indexOf (int find, int fromRange);
  public int indexOf (int find);
  public IntRanges intersect (IntRanges other,
        IIntRangeComparator judge);
  public IntRanges intersect (IntRanges other);
  public static int invertComparisonResult (int cmp);
  public boolean isEmpty ();
  public synchronized boolean lock (Object key);
  public synchronized void parse (String str, String delims);
  public void parse (String str);
  public boolean removeRange (int rs, int re);
  public void removeRange (int i, IIntRangeComparator hook);
  public void removeRange (int i);
  public synchronized boolean removeRange (int s, int e,
        IIntRangeComparator hook);
  public synchronized void removeRanges (int i, int count,
        IIntRangeComparator hook);
  public void removeRanges (int i, int count);
  public boolean removeSingleton (int n);
  public boolean removeSingleton (int n, IIntRangeComparator hook);
  public synchronized void setRanges (int[] array);
  public int size ();
  public synchronized void sort (IIntRangeComparator judge);
  public void sort ();
  public String toString ();
  public synchronized boolean unlock (Object key);
}

This class maintains a list of integer ranges. Readers and writers of this list should be externally synchronized.

Constructors

IntRanges

public IntRanges ();
Constructs an empty set of ranges as an IntArrayOutputStream object.

IntRanges

public IntRanges (String str);
Constructs a set of ranges from the given string.

Parameter Description

str A string containing ranges of integers, where the bounds of each range are separated by a dash (-), and separate ranges are delimited by commas. A range of a single integer can be entered by including just the single integer, separated by delimiters. For example: 1-5,9-11,44,13-120.

IntRanges

public IntRanges (String str, String delims);
Constructs a set of ranges from the given string with specified delimiters.

Parameter Description

str A string containing ranges of integers, where the bounds of each range are separated by a dash (-). A range of a single integer can be entered by including just the single integer, separated by delimiters.
delims The character or characters that separate the ranges.

Methods

addRange

public synchronized void addRange (int s, int e);
Adds a range to the IntRange object.
Return Value:
No return value.

Parameter Description

s The lower limit of the range.
e The upper limit of the range.

addRanges

public synchronized void addRanges (IntRanges r);
Adds another set of ranges to this object's set of ranges.
Return Value:
No return value.

Parameter Description

r Another IntRanges object to add to this IntRanges object.

addSingleton

public synchronized void addSingleton (int n);
Adds a range of a single integer to the IntRange object.

Parameter Description

n The integer range. For example, if n is 43, a range of 43-43 is added.

appendToStringBuffer

public StringBuffer appendToStringBuffer (StringBuffer sb);
Appends a string representation of the integer ranges to a given string buffer. Used by toString.
Return Value:
Returns a string buffer containing the concatenated strings.

Parameter Description

sb The string buffer to append the set of integer range pairs to.

clone

protected Object clone ();
Creates a copy of the set of ranges.
Return Value:
Returns an identical object to this object.

compare

public int compare (IntRanges other);
Compares this set of ranges to another.
Return Value:
Returns the following:

OVERLAP
the sets of integers are not equal but have a common set of integers.
DISJOINT
the sets of integers have no integers in common
SUBSET
the second set of integers includes all of the integers in the first set, plus some integers that are not in the first set.
EQUAL
the sets of integers are identical
SUPERSET
the first set of integers includes all of the integers in the second set, plus some integers that are not in the second set.

Parameter Description

other The set of ranges to compare with.

compare

public int compare (IntRanges other, IIntRangeComparator judge);
Compares this set of ranges to another.
Return Value:
Returns the following:

OVERLAP
the sets of integers are not equal, but have a common set of integers.
DISJOINT
the sets of integers have no integers in common
SUBSET
the second set of integers includes all of the integers in the first set, plus some integers that are not in the first set.
EQUAL
the sets of integers are identical
SUPERSET
the first set of integers includes all of the integers in the second set, plus some integers that are not in the second set.
EMPTY
both sets of integers are empty.
EMPTY_SUBSET
pairs1 is empty and pairs2 is not empty.
EMPTY_SUPERSET
pairs2 is empty and pairs1 is not empty.

Parameter Description

other The set of ranges to compare with.
judge A helper interface for the comparison.

compareSet

public int compareSet (Object other);
Compares this set of ranges to another.
Return Value:
Returns SetComparison.DISJOINT if other is not an instance of IntRanges, or else a SetComparison.compareSet result:

SetComparison.OVERLAP
The sets of integers are not equal but have a common set of integers.
SetComparison.DISJOINT
The sets of integers have no integers in common.
SetComparison.SUBSET
other includes all the integers in this set, plus some integers that are not in this set.
SetComparison.EQUAL
The sets of integers are identical.
SetComparison.SUPERSET
This set of integers includes all of the integers in other, plus some integers that are not in other.
SetComparison.EMPTY
Both sets of integers are empty.
SetComparison.EMPTY_SUBSET
This set is empty and other is not empty.
SetComparison.EMPTY_SUPERSET
other is empty and this set is not empty.

Parameter Description

other The set of ranges to compare with.

ComparisonResulttoString

public static String ComparisonResulttoString (int cmp);
Converts comparison result flags to a string format.
Return Value:
Returns the result string as follows:
"empty" (EMPTY)
"equal" (EQUAL)
"notequal" (DISJOINT)
"overlap" (OVERLAP)
"inclusive subset" (SUBSET)
"inclusive superset" (SUPERSET)
"empty subset" (EMPTY_SUBSET)
"empty superset" (EMPTY_SUPERSET)

Parameter Description

cmp A comparison result from the compare method.

condense

public synchronized void condense (IIntRangeComparator judge);
Merges overlapping ranges. This method assumes the ranges have already been sorted.
Return Value:
No return value.

Parameter Description

judge The interface to help compare equal integer ranges while sorting. This parameter value can be null.

condense

public void condense ();
Merges overlapping ranges. This method assumes the ranges have already been sorted.
Return Value:
No return value.

contains

public boolean contains (int find);
Searches from the beginning of a range for a given number.
Return Value:
Returns true if the number was found; otherwise, returns false.

Parameter Description

find The number to search for.

contains

public synchronized boolean contains (int s, int e);
Searches from the beginning of a range for a given range of numbers.
Return Value:
Returns true if the entire search range was found; otherwise, returns false.

Parameter Description

s The lower limit of the range.
e The upper limit of the range.

copy

public synchronized IntRanges copy ();
Creates a copy of the set of ranges.
Return Value:
Returns an identical object to this object.

getRangeEnd

public int getRangeEnd (int idx);
Retrieves the end of a range at a specified index.
Return Value:
Returns the last integer of the range pair.

Parameter Description

idx The index of the range pair.

getRanges

public synchronized int[] getRanges ();
Retrieves the integer range pairs as an integer array.
Return Value:
Returns the integer ranges.

getRangeStart

public int getRangeStart (int idx);
Retrieves the start of a range at a specified index.
Return Value:
Returns the first integer of the range pair.

Parameter Description

idx The index of the range pair.

indexOf

public synchronized int indexOf (int find, int fromRange);
Searches from a starting index for a range pair containing a given a number.
Return Value:
Returns the index of the range pair that includes the number if found; otherwise, returns -1.

Parameter Description

find The number to search for.
fromRange The index of the range pair to start the search from.

indexOf

public int indexOf (int find);
Searches from the beginning for a range pair containing a given number.
Return Value:
Returns the index of the range pair that includes the number (if found); otherwise, returns -1.

Parameter Description

find The number to search for.

intersect

public IntRanges intersect (IntRanges other, IIntRangeComparator judge);
Constructs a new IntRanges object with the set of integers that are common to both this object and another object.
Return Value:
Returns an IntRanges object for the intersection of this object and other.

Parameter Description

other The other IntRanges object to find an intersection with.
judge The hook interface to notify using IIntRangeComparator.intersectRanges of intersecting ranges that will be added to the new IntRanges object.

intersect

public IntRanges intersect (IntRanges other);
Constructs a new IntRanges object with the set of integers that are common to both this object and another object.
Return Value:
Returns an IntRanges object for the intersection of this object and other.

Parameter Description

other The other IntRanges object to find an intersection with.

invertComparisonResult

public static int invertComparisonResult (int cmp);
Inverts comparison results.
Return Value:
Returns the inverted comparison result.

Parameter Description

cmp Any comparison result of the compare method, which is inverted as follows:
SUBSET returns SUPERSET.
SUPERSET returns SUBSET.
EMPTY_SET returns EMPTY_SUPERSET.
EMPTY_SUPERSET returns EMPTY_SUBSET.
any other result is not affected and is simply returned. Note that EQUAL and DISJOINT are not inverted by this function.

isEmpty

public boolean isEmpty ();
Determines if the IntRanges object is empty.
Return Value:
Returns true if the object contains no ranges; otherwise, returns false.

lock

public synchronized boolean lock (Object key);
Assigns a key and locks the IntRanges object.
Return Value:
Returns true if successful; returns false if the object is already locked.

Parameter Description

key The key object to be used for unlocking the object.

Exceptions:
NullPointerException if the key is null.

parse

public synchronized void parse (String str, String delims);
Parses the ranges in the string, separated with specified delimiters. This method tokenizes using StringTokenizer.
Return Value:
No return value.

Parameter Description

str The string to be parsed.
delims The delimiters.

parse

public void parse (String str);
Parses comma-delimited ranges in the string.
Return Value:
No return value.

Parameter Description

str A string containing ranges of integers, where the bounds of each range are separated by a dash (-). A range of a single integer can be entered by including just the single integer, separated by delimiters.

removeRange

public boolean removeRange (int rs, int re);
Removes a range of integers from the IntRange object.
Return Value:
Returns true if any integers in the range were removed; returns false if the set contains no integers in the range.

Parameter Description

rs The lower limit of the range.
re The upper limit of the range.

removeRange

public void removeRange (int i, IIntRangeComparator hook);
Removes a single range specified by index from the IntRange object.
Return Value:
No return value.

Parameter Description

i The index of the range to remove.
hook The interface to notify through IIntRangeComparator.shiftRanges that the ranges were deleted.

removeRange

public void removeRange (int i);
Removes a single range specified by index from the IntRange object.
Return Value:
No return value.

Parameter Description

i The index of the range to remove.

removeRange

public synchronized boolean removeRange (int s, int e,
        IIntRangeComparator hook);
Removes a range of integers from the IntRange object.
Return Value:
Returns true if any integers in the range were removed; returns false if the set contains no integers in the range.

Parameter Description

rs The lower limit of the range.
re The upper limit of the range.
hook The interface to notify through IIntRangeComparator.shiftRanges that the ranges were deleted or IIntRangeComparator.splitRange that a range was split.

removeRanges

public synchronized void removeRanges (int i, int count,
        IIntRangeComparator hook);
Removes ranges specified by index from the IntRange object.
Return Value:
No return value.

Parameter Description

i The index of the range to remove.
count The number ranges to remove.
hook The interface to notify through IIntRangeComparator.shiftRanges that the ranges were deleted.

removeRanges

public void removeRanges (int i, int count);
Removes ranges specified by index from the IntRange object.
Return Value:
No return value.

Parameter Description

i the index of the range to remove.
count the number ranges to remove.

removeSingleton

public boolean removeSingleton (int n);
Removes a single integer from the IntRange object.
Return Value:
Returns true if the integer was removed returns false if the integer was not found in the set.

Parameter Description

n The integer to remove.

removeSingleton

public boolean removeSingleton (int n, IIntRangeComparator hook);
Removes a single integer from the IntRange object.
Return Value:
Returns true if the integer was removed. This method returns false if the integer was not found in the set.

Parameter Description

n The integer to remove.
hook The interface to notify through IIntRangeComparator.shiftRanges that ranges were deleted or IIntRangeComparator.splitRange that a range was split.

setRanges

public synchronized void setRanges (int[] array);
Sets the integer ranges from an existing integer array.
Return Value:
No return value.

Parameter Description

array The array of integer ranges. Each range is specified by two adjacent integers in this array.

size

public int size ();
Retrieves the size of the IntRanges object.
Return Value:
Returns the number of elements in the object.

sort

public synchronized void sort (IIntRangeComparator judge);
Sorts the ranges by the first element in each range pair.
Return Value:
No return value.

Parameter Description

judge The interface to help compare equal ranges while sorting. This parameter value can be null.

sort

public void sort ();
Sorts the ranges by left endpoints.
Return Value:
No return value.

toString

public String toString ();
Retrieves a string representation of the IntRanges object.
Return Value:
Returns a string containing "{" followed by the set of integer range pairs, followed by "}".

unlock

public synchronized boolean unlock (Object key);
Unlocks the IntRanges using a previously-assigned key.
Return Value:
Returns true if the object is successfully unlocked; otherwise, returns false.

Parameter Description

key The key object previously assigned to lock the object.

Exceptions:
NullPointerException if the key is null.