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:

• bytes=50-100
• bytes=600-
• bytes=50-150,350-400
• bytes=200-250,300-350,600-

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