Package org.apache.pivot.wtk

Class Span

java.lang.Object

org.apache.pivot.wtk.Span

public final class Span
extends java.lang.Object

Class representing a range of integer values. The range includes all values in the interval [start, end] (inclusive). Values may be negative, and the value of start may be less than or equal to the value of end.

Field Summary

Fields

Modifier and Type	Field	Description
int	end
static java.util.Comparator<Span>	END_COMPARATOR	Comparator that determines the index of the last intersecting range.
static java.lang.String	END_KEY
static java.util.Comparator<Span>	INTERSECTION_COMPARATOR	Comparator that determines if two ranges intersect.
int	start
static java.util.Comparator<Span>	START_COMPARATOR	Comparator that determines the index of the first intersecting range.
static java.lang.String	START_KEY

Constructor Summary

Constructors

Constructor	Description
Span(int index)	Construct a new span of length 1 at the given location.
Span(int start, int end)	Construct a new span with the given bounds.
Span(Dictionary<java.lang.String,?> span)	Construct a new span from the given dictionary which must contain the START_KEY and END_KEY keys.
Span(Sequence<?> span)	Construct a new span from the given sequence with two numeric values corresponding to the start and end values respectively.
Span(Span span)	Construct a new span from another one (a "copy constructor").

Method Summary

Modifier and Type	Method	Description
boolean	adjacentTo(Span span)	Determines whether this span is adjacent to another span.
boolean	after(Span span)	Determines whether this span is "after" another span.
boolean	before(Span span)	Determines whether this span is "before" another span.
boolean	contains(Span span)	Determines whether this span contains another span.
static Span	decode(java.lang.String value)	Convert a string into a span.
boolean	equals(java.lang.Object o)
long	getLength()	Returns the length of the span.
int	hashCode()
Span	intersect(Span span)	Calculates the intersection of this span and another span.
boolean	intersects(Span span)	Determines whether this span intersects with another span.
boolean	isNormal()
Span	lengthen(int offset)	Returns a new Span with the end value offset by the given value.
Span	move(int offset)	Returns a new Span with the start value offset by the given value.
int	normalEnd()
boolean	normalEquals(Span span)	Decides whether the normalized version of this span is equal to the normalized version of the other span.
Span	normalize()
static Span	normalize(int start, int end)	Create a span where the start value is less than or equal to the end value.
int	normalStart()
Span	offset(int offset)	Returns a new Span with both values offset by the given value.
java.lang.String	toString()
Span	union(Span span)	Calculates the union of this span and another span.

Methods inherited from class java.lang.Object

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

Field Detail

start

public final int start

end

public final int end

START_KEY

public static final java.lang.String START_KEY

See Also:

Constant Field Values

END_KEY

public static final java.lang.String END_KEY

See Also:

Constant Field Values

START_COMPARATOR

public static final java.util.Comparator<Span> START_COMPARATOR

Comparator that determines the index of the first intersecting range.

END_COMPARATOR

public static final java.util.Comparator<Span> END_COMPARATOR

Comparator that determines the index of the last intersecting range.

INTERSECTION_COMPARATOR

public static final java.util.Comparator<Span> INTERSECTION_COMPARATOR

Comparator that determines if two ranges intersect.

Constructor Detail

Span

public Span(int index)

Construct a new span of length 1 at the given location.

Parameters:

index - The start and end of this span (inclusive).

Span

public Span(int start,
            int end)

Construct a new span with the given bounds.

Parameters:

start - The start of this span - inclusive.

end - The end of the span - inclusive.

Span

public Span(Span span)

Construct a new span from another one (a "copy constructor").

Parameters:

span - An existing span (which must not be null).

Throws:

java.lang.IllegalArgumentException - if the given span is null.

Span

public Span(Dictionary<java.lang.String,?> span)

Construct a new span from the given dictionary which must contain the START_KEY and END_KEY keys.

Parameters:

span - A dictionary containing start and end values.

Throws:

java.lang.IllegalArgumentException - if the given span is null or if the dictionary does not contain the start and end keys.

Span

public Span(Sequence<?> span)

Construct a new span from the given sequence with two numeric values corresponding to the start and end values respectively.

Parameters:

span - A sequence containing the start and end values.

Throws:

java.lang.IllegalArgumentException - if the given span is null.

Method Detail

getLength

public long getLength()

Returns the length of the span.

Returns:

The absolute value of (end minus start) + 1.

contains

public boolean contains(Span span)

Determines whether this span contains another span.

Parameters:

span - The span to test for containment.

Returns:

true if this span contains span; false, otherwise.

Throws:

java.lang.IllegalArgumentException - if the given span is null.

adjacentTo

public boolean adjacentTo(Span span)

Determines whether this span is adjacent to another span.

Adjacency means that one end of this span is +/-1 from either end of the other span (since start and end are inclusive).

Parameters:

span - The span to test for adjacency.

Returns:

true if this span is adjacent span; false, otherwise.

Throws:

java.lang.IllegalArgumentException - if the given span is null.

before

public boolean before(Span span)

Determines whether this span is "before" another span.

"Before" means that the normalized end of this span is < the normalized start of the other span.

Parameters:

span - The span to test.

Returns:

true if this span is "before" span; false, otherwise.

Throws:

java.lang.IllegalArgumentException - if the given span is null.

after

public boolean after(Span span)

Determines whether this span is "after" another span.

"After" means that the normalized start of this span is > the normalized end of the other span.

Parameters:

span - The span to test.

Returns:

true if this span is "after" span; false, otherwise.

Throws:

java.lang.IllegalArgumentException - if the given span is null.

intersects

public boolean intersects(Span span)

Determines whether this span intersects with another span.

Parameters:

span - The span to test for intersection.

Returns:

true if this span intersects with span; false, otherwise.

Throws:

java.lang.IllegalArgumentException - if the given span is null.

intersect

public Span intersect(Span span)

Calculates the intersection of this span and another span.

Parameters:

span - The span to intersect with this span.

Returns:

A new Span instance representing the intersection of this span and span, or null if the spans do not intersect.

Throws:

java.lang.IllegalArgumentException - if the given span is null.

union

public Span union(Span span)

Calculates the union of this span and another span.

Parameters:

span - The span to union with this span.

Returns:

A new Span instance representing the union of this span and span.

normalStart

public int normalStart()

Returns:

The normalized start of this span, which is the lesser of the current start and end.

normalEnd

public int normalEnd()

Returns:

The normalized end of this span, which is the greater of the current start and end.

isNormal

public boolean isNormal()

Returns:

true if the span is "normal", meaning the start is less or equal the end.

normalize

public static Span normalize(int start,
                             int end)

Create a span where the start value is less than or equal to the end value.

Parameters:

start - The new proposed start value.

end - The new proposed end.

Returns:

A span containing the normalized range.

normalize

public Span normalize()

Returns:

A normalized equivalent of the span in which start is guaranteed to be less or equal to end.

Note: if the span is already "normal", then no new object is created.

offset

public Span offset(int offset)

Returns a new Span with both values offset by the given value.

This is useful while moving through a TextPane document for instance, where you have to subtract off the starting offset for child nodes.

Parameters:

offset - The positive or negative amount by which to "move" this span (both start and end).

Returns:

A new Span with updated values.

lengthen

public Span lengthen(int offset)

Returns a new Span with the end value offset by the given value.

Parameters:

offset - The positive or negative amount by which to "lengthen" this span (only the end).

Returns:

A new Span with updated value.

move

public Span move(int offset)

Returns a new Span with the start value offset by the given value.

Parameters:

offset - The positive or negative amount by which to "shift" this span (only the start).

Returns:

A new Span with updated value.

normalEquals

public boolean normalEquals(Span span)

Decides whether the normalized version of this span is equal to the normalized version of the other span. Saves the overhead of making a new object (with normalize(int, int)).

Parameters:

span - The span to test against this span.

Returns:

Whether or not the normalized values of both spans are the same.

Throws:

java.lang.IllegalArgumentException - if the other span is null.

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

decode

public static Span decode(java.lang.String value)

Convert a string into a span.

If the string value is a JSON map, then parse the map and construct using the Span(Dictionary) method.

If the string value is a JSON list, then parse the list and construct using the first two values as start and end respectively, using the Span(int, int) constructor.

Also accepted is a simple list of two integer values separated by comma or semicolon.

Otherwise the string should be a single integer value that will be used to construct the span using the Span(int) constructor.

Parameters:

value - The string value to decode into a new span.

Returns:

The decoded span.

Throws:

java.lang.IllegalArgumentException - if the value is null or if the string starts with "{" but it cannot be parsed as a JSON map, or if it starts with "[" but cannot be parsed as a JSON list.

See Also:

Span(Dictionary), Span(Sequence), Span(int, int), Span(int)