com.adobe.acrobat.bytearray
Class ByteRange

java.lang.Object
  |
  +--java.util.AbstractCollection
        |
        +--java.util.AbstractList
              |
              +--java.util.Vector
                    |
                    +--com.adobe.acrobat.bytearray.ByteRange

public class ByteRange
extends java.util.Vector

Object used to describe subsets of ByteArrays. A ByteRange is really just a set of integers stored in a way optimized for the most common case, i.e., small numbers of comparatively large nonoverlapping sequences of byte-offsets (integers).

A ByteRange is a set of integers and as such supports all basic set operations, e.g., intersection, union, and subtraction.

ByteRanges contain integers ranging in value from 0 to Integer.MAX_VALUE-1. ByteRanges are also immutable; it is impossible to "change" the value of an instantiated ByteRange. Instead one must construct ByteRanges using the accessor methods for the empty and universal ByteRange, and the various ByteRange operator methods.

Version:
1.0 19 March 1997 Copyright (c) 1997, Adobe Systems Inc., All Rights Reserved.
See Also:
Serialized Form

Fields inherited from class java.util.Vector
capacityIncrement, elementCount, elementData

 

Fields inherited from class java.util.AbstractList
modCount

 

Constructor Summary
ByteRange(ContiguousByteRange cbr)
          Create a ByteRange which delimits all the integers in the given ContiguousByteRange.
ByteRange(int start, int end)
          Create a ByteRange which contains all the integers between start and end inclusive.
ByteRange(java.lang.String s)
          Create a new ByteRange based on a String representation.

 

Method Summary
 int byteIndex(int n)
          Returns the number of integers in this ByteRange less than or equal to the given integer.
 boolean contains(ByteRange br)
          Returns true if the given ByteRange is completely enclosed in this ByteRange, i.e., every integer appearing in br appears in this ByteRange.
 boolean contains(ContiguousByteRange cbr)
          Returns true if the ContiguousByteRange is completely enclosed in the ByteRange, i.e., every integer in cbr in contained in this ByteRange.
 boolean contains(int n)
          Test the ByteRange for inclusion of a particular integer.
 ByteRange decapitate(int start)
          Return a new ByteRange which contains all the integers in this ByteRange except those whose values are less than start.
 boolean equals(java.lang.Object o)
          Determine if two ByteRanges are equal.
static ByteRange getEmptyByteRange()
          Get the empty ByteRange.
 ContiguousByteRange getEnclosingRange()
          Get the ContiguousByteRange enclosing the entire ByteRange.
 int getEnd()
          Gets the last integer in the ByteRange.
 ContiguousByteRange getFirstIntersection(ContiguousByteRange br)
          Returns a Contiguous byte range that intersects this byte range
 int getLength()
           
 ContiguousByteRange getNthContiguousByteRange(int n)
          Get the nth contiguous range.
 int getStart()
          Gets the first integer in a ByteRange.
static ByteRange getUniversalByteRange()
          Get the ByteRange that contains all integers from 0 to Integer.MAX_VALUE-.
 ByteRange intersect(ByteRange r2)
          Intersect a ByteRange with another ByteRange.
 boolean intersects(ByteRange br2)
          Returns true if the two ByteRanges have a non-empty intersection.
 boolean isUniversal()
          Returns true if every integer between 0 and Integer.MAX_VALUE-1 inclusive is included in this ByteRange.
 int numRanges()
          Get the number of continguous ranges in this ByteRange.
 ByteRange subtract(ByteRange subtractor)
          Subtract all the integers in subtractor from this ByteRange, and return the result.
 ByteRange subtract(ContiguousByteRange subtractor)
           
 java.lang.String toRangeString()
          Create a string representation of this ByteRange.
 ByteRange truncate(int end)
          Return a new ByteRange which contains all the integers in this ByteRange except those whose values are greater than or equal to end.
 ByteRange union(ByteRange r2)
          Union a ByteRange with another ByteRange.
 ByteRange union(ContiguousByteRange cbr)
           

 

Methods inherited from class java.util.Vector
add, add, addAll, addAll, addElement, capacity, clear, clone, contains, containsAll, copyInto, elementAt, elements, ensureCapacity, firstElement, get, hashCode, indexOf, indexOf, insertElementAt, isEmpty, lastElement, lastIndexOf, lastIndexOf, remove, remove, removeAll, removeAllElements, removeElement, removeElementAt, removeRange, retainAll, set, setElementAt, setSize, size, subList, toArray, toArray, toString, trimToSize

 

Methods inherited from class java.util.AbstractList
iterator, listIterator, listIterator

 

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

 

Constructor Detail

ByteRange

public ByteRange(ContiguousByteRange cbr)
Create a ByteRange which delimits all the integers in the given ContiguousByteRange.
Parameters:
cbr - the ContiguousByteRange being copied

ByteRange

public ByteRange(int start,
                 int end)
Create a ByteRange which contains all the integers between start and end inclusive.
Parameters:
start - the first integer to be included in the ByteRange
end - the last integer to be included in the ByteRange

ByteRange

public ByteRange(java.lang.String s)
Create a new ByteRange based on a String representation. The String must be of the form specified for byte ranges in the HTTP/1.1 spec. For example, the following are all legal representations:
Parameters:
s - the String from which to derive the contents of this ByteRange
Method Detail

getEmptyByteRange

public static ByteRange getEmptyByteRange()
Get the empty ByteRange. Since there is no need to create more than one empty ByteRange, this is a global accessor method rather than a constructor.
Returns:
the empty ByteRange

getUniversalByteRange

public static ByteRange getUniversalByteRange()
Get the ByteRange that contains all integers from 0 to Integer.MAX_VALUE-. Since there is no need to create more than one universal ByteRange, this is a global accessor method rather than a constructor.
Returns:
the empty ByteRange

equals

public boolean equals(java.lang.Object o)
Determine if two ByteRanges are equal.
Parameters:
o - the object whose value is being compared
Returns:
true if o is a ByteRange containing exactly the same set of integers as this ByteRange; false otherwise
Overrides:
equals in class java.util.Vector

getStart

public int getStart()
Gets the first integer in a ByteRange. Throws an exception if this is an empty ByteRange.
Returns:
the value of the lowest integer contained in this ByteRange
Throws:
java.lang.RuntimeException - if the ByteRange is empty

getEnd

public int getEnd()
Gets the last integer in the ByteRange. Throws an exception if this is an empty ByteRange.
Returns:
the value of the highest integer contained in this ByteRange
Throws:
java.lang.RuntimeException - if the ByteRange is empty

getLength

public int getLength()

truncate

public ByteRange truncate(int end)
Return a new ByteRange which contains all the integers in this ByteRange except those whose values are greater than or equal to end.
Parameters:
end - the upper bound of the returned value
Returns:
a new ByteRange truncated at end.
See Also:
decapitate

decapitate

public ByteRange decapitate(int start)
Return a new ByteRange which contains all the integers in this ByteRange except those whose values are less than start.
Parameters:
start - the lower bound of the returned value
Returns:
a new ByteRange decapitated at start.
See Also:
truncate

getFirstIntersection

public ContiguousByteRange getFirstIntersection(ContiguousByteRange br)
Returns a Contiguous byte range that intersects this byte range

numRanges

public int numRanges()
Get the number of continguous ranges in this ByteRange.
Returns:
the number of non-overlapping, non-adjacent contiguous sets of integers in this ByteRange.

getNthContiguousByteRange

public ContiguousByteRange getNthContiguousByteRange(int n)
Get the nth contiguous range.
Parameters:
n - the index of the requested contiguous range.
Returns:
the nth ContiguousByteRange
Throws:
ArrayIndexOutOfBoundsException - if n the number of ContiguousByteRanges in this ByteRange

isUniversal

public boolean isUniversal()
Returns true if every integer between 0 and Integer.MAX_VALUE-1 inclusive is included in this ByteRange.
Returns:
true if all integers are in this ByteRange.

byteIndex

public int byteIndex(int n)
Returns the number of integers in this ByteRange less than or equal to the given integer. Used for determinining an approximate wait time for a reqested byte.
Parameters:
n - an integer whose ordinality within the integers contained in this ByteRange is requested
Returns:
the "position" of n within this ByteRange
See Also:
nthByte

getEnclosingRange

public ContiguousByteRange getEnclosingRange()
Get the ContiguousByteRange enclosing the entire ByteRange.
Returns:
a new ContiguousByteRange that contains all the integers greater than or equal to this ByteRange's minimum and less than or equal to this ByteRange's maximum

union

public ByteRange union(ByteRange r2)
Union a ByteRange with another ByteRange. The result contains all the integers found in either this ByteRange or in r2.
Parameters:
r2 - the ByteRange to union with this ByteRange
Returns:
the union of this ByteRange and r2.

union

public ByteRange union(ContiguousByteRange cbr)

contains

public boolean contains(ContiguousByteRange cbr)
Returns true if the ContiguousByteRange is completely enclosed in the ByteRange, i.e., every integer in cbr in contained in this ByteRange.
Parameters:
cbr - the ContiguousByteRange being tested
Returns:
true if cbr is completely contained in this ByteRange

contains

public boolean contains(ByteRange br)
Returns true if the given ByteRange is completely enclosed in this ByteRange, i.e., every integer appearing in br appears in this ByteRange.
Parameters:
br - the ByteRange being tested
Returns:
true if br is completely contained in this ByteRange

contains

public boolean contains(int n)
Test the ByteRange for inclusion of a particular integer.
Parameters:
n - the integer being tested for inclusion
Returns:
true if n appears in this ByteRange, false otherwise

intersects

public boolean intersects(ByteRange br2)
Returns true if the two ByteRanges have a non-empty intersection.
Parameters:
br2 - the ByteRange being tested for intersection with this ByteRange
Returns:
true if there exists an integer contained both in this ByteRange and br2

intersect

public ByteRange intersect(ByteRange r2)
Intersect a ByteRange with another ByteRange.
Parameters:
r2 - the ByteRange to be intersected with this ByteRange
Returns:
a new ByteRange containing all the integers in both this ByteRange and r2

subtract

public ByteRange subtract(ByteRange subtractor)
Subtract all the integers in subtractor from this ByteRange, and return the result.
Parameters:
subtractor - the ByteRange to be subtracted from this ByteRange
Returns:
a new ByteRange with all the integers in this ByteRange but not in subtractor

subtract

public ByteRange subtract(ContiguousByteRange subtractor)

toRangeString

public java.lang.String toRangeString()
Create a string representation of this ByteRange.
Returns:
a String enumerating the integers in this ByteRange