org.crosswire.jsword.passage
Class VerseRange

java.lang.Object
  extended by org.crosswire.jsword.passage.VerseRange
All Implemented Interfaces:
Serializable, Cloneable, Comparable, Iterable, Key

public final class VerseRange
extends Object
implements Key

A VerseRange is one step between a Verse and a Passage - it is a Verse plus a verseCount. Every VerseRange has a start, a verseCount and an end. A VerseRange is designed to be immutable. This is a necessary from a collections point of view. A VerseRange should always be valid, although some versions may not return any text for verses that they consider to be miss-translated in some way.

Author:
Joe Walker [joe at eireneh dot com], DM Smith [dmsmith555 at yahoo dot com]
See Also:
for license details. The copyright to this program is held by it's authors., Serialized Form

Nested Class Summary
private static class VerseRange.VerseIterator
          Iterate over the Verses in the VerseRange
 
Field Summary
private  Verse end
          The real data - where do we end?.
(package private) static Logger log
          The log stream
private  String originalName
          The original string for picky users
private  Key parent
          The parent key.
static String RANGE_ALLOWED_DELIMS
          What characters can we use to separate the 2 parts to a VerseRanges
static String RANGE_PREF_DELIM
          What characters should we use to separate VerseRange parts on output
(package private) static long serialVersionUID
          To make serialization work across new versions
private  NumberShaper shaper
          Allow the conversion to and from other number representations.
private  Verse start
          The real data - where do we start?.
private  int verseCount
          The real data - how many verses long are we?.
private static VerseRange whole
          The whole Bible VerseRange
 
Constructor Summary
VerseRange()
          The default VerseRange is a single verse - Genesis 1:1.
VerseRange(String original, Verse start, Verse end)
          Construct a VerseRange from 2 Verses If start is later than end then swap the two around.
VerseRange(Verse start)
          Construct a VerseRange from a Verse.
VerseRange(VerseRange a, VerseRange b)
          Merge 2 VerseRanges together.
VerseRange(Verse start, Verse end)
           
 
Method Summary
 void addAll(Key key)
          Adds the specified element to this set if it is not already present.
 boolean adjacentTo(VerseRange that)
          Are the 2 VerseRanges in question contiguous.
 void blur(int by, RestrictionType restrict)
          Widen the range of the verses/keys in this list.
private static Verse calcEnd(Verse start, int verseCount)
          Calculate the last verse in this range.
private static int calcVerseCount(Verse start, Verse end)
          Calculate how many verses in this range
 boolean canHaveChildren()
          Returns false if the receiver is a leaf node and can not have children.
 void clear()
          Removes all of the elements from this set (optional operation).
 Object clone()
          This needs to be declared here so that it is visible as a method on a derived Key.
 int compareTo(Object obj)
           
 boolean contains(Key key)
          Returns true if this set contains the specified element.
 boolean contains(Verse that)
          Is the given verse entirely within our range.
 boolean contains(VerseRange that)
          Is the given range within our range.
private  String doGetName(Key base)
           
 boolean equals(Object obj)
          This needs to be declared here so that it is visible as a method on a derived Key.
 Key get(int index)
          Gets a key from a specific point in this list of children.
 int getBookCount()
          How many books in this range
 int getCardinality()
          Returns the number of elements in this set (its cardinality).
 int getChapterCount()
          How many chapters in this range
 int getChildCount()
          Returns the number of children that this node has.
 Verse getEnd()
          Fetch the last verse in this range.
 String getName()
          A Human readable version of the Key.
 String getName(Key base)
          Translate the Key into a human readable string, with the assumption that the specified Key has just been output, so if we are in the same region, we do not need to display the region name, and so on.
 String getOsisID()
          The OSIS defined id specification for this Key.
 String getOsisRef()
          The OSIS defined reference specification for this Key.
 Key getParent()
          All keys have parents unless they are the root of a Key.
 String getRootName()
          A Human readable version of the Key's top level name.
 Verse getStart()
          Fetch the first verse in this range.
static VerseRange getWholeBibleVerseRange()
          Returns a VerseRange that wraps the whole Bible
 int hashCode()
          This needs to be declared here so that it is visible as a method on a derived Key.
 int indexOf(Key that)
          Reverse a Key into the position the key holds in the list of children
static VerseRange intersection(VerseRange a, VerseRange b)
          Create a DistinctPassage that is the stuff in VerseRange a that is also in VerseRange b.
 boolean isEmpty()
          Does this Key have 0 members
 boolean isMultipleBooks()
          Does this range occupy more than one book;
 boolean isWholeBook()
          Does this range represent exactly one book, no more or less.
 boolean isWholeBooks()
          Does this range represent a whole number of books.
 boolean isWholeChapter()
          Does this range represent exactly one chapter, no more or less.
 boolean isWholeChapters()
          Does this range represent a number of whole chapters
 Iterator iterator()
           
 boolean overlaps(VerseRange that)
          Do the 2 VerseRanges in question actually overlap.
 Iterator rangeIterator(RestrictionType restrict)
          Enumerate the subranges in this range
private  void readObject(ObjectInputStream in)
          Write out the object to the given ObjectOutputStream
static VerseRange[] remainder(VerseRange a, VerseRange b)
          Create a DistinctPassage that is the stuff left of VerseRange a when you remove the stuff in VerseRange b.
 void removeAll(Key key)
          Removes the specified elements from this set if it is present.
 void retainAll(Key key)
          Removes all but the specified element from this set.
 void setParent(Key parent)
          Set a parent Key.
 String toString()
           
 Verse[] toVerseArray()
          Create an array of Verses
private  void verifyData()
          Check to see that everything is ok with the Data
private  void writeObject(ObjectOutputStream out)
          Write out the object to the given ObjectOutputStream
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

RANGE_ALLOWED_DELIMS

public static final String RANGE_ALLOWED_DELIMS
What characters can we use to separate the 2 parts to a VerseRanges

See Also:
Constant Field Values

RANGE_PREF_DELIM

public static final String RANGE_PREF_DELIM
What characters should we use to separate VerseRange parts on output

See Also:
Constant Field Values

serialVersionUID

static final long serialVersionUID
To make serialization work across new versions

See Also:
Constant Field Values

verseCount

private transient int verseCount
The real data - how many verses long are we?. All ctors init this so leave default


start

private transient Verse start
The real data - where do we start?. All ctors init this so leave default


end

private transient Verse end
The real data - where do we end?. All ctors init this so leave default


shaper

private transient NumberShaper shaper
Allow the conversion to and from other number representations.


parent

private transient Key parent
The parent key. See the key interface for more information. NOTE(joe): These keys are not serialized, should we?

See Also:
Key

originalName

private transient String originalName
The original string for picky users


whole

private static transient VerseRange whole
The whole Bible VerseRange


log

static final transient Logger log
The log stream

Constructor Detail

VerseRange

public VerseRange()
The default VerseRange is a single verse - Genesis 1:1. I didn't want to provide this constructor however, you are supposed to provide a default ctor for all beans. For this reason I suggest you don't use it.


VerseRange

public VerseRange(Verse start)
Construct a VerseRange from a Verse. The resultant VerseRange will be 1 verse in verseCount.

Parameters:
start - The verse to start from

VerseRange

public VerseRange(Verse start,
                  Verse end)

VerseRange

VerseRange(String original,
           Verse start,
           Verse end)
Construct a VerseRange from 2 Verses If start is later than end then swap the two around. This constructor is deliberately package protected so that is used only by VerseFactory.

Parameters:
start - The verse to start from
end - The verse to end with

VerseRange

public VerseRange(VerseRange a,
                  VerseRange b)
Merge 2 VerseRanges together. The resulting range will encompass Everything in-between the extremities of the 2 ranges.

Parameters:
a - The first verse range to be merged
b - The second verse range to be merged
Method Detail

getName

public String getName()
Description copied from interface: Key
A Human readable version of the Key. For Biblical passages this uses short books names, and the shortest sensible rendering eg "Mat 3:1-4" and "Mar 1:1, 3, 5" and "3Jo, Jude"

Specified by:
getName in interface Key
Returns:
a String containing a description of the Key

getName

public String getName(Key base)
Description copied from interface: Key
Translate the Key into a human readable string, with the assumption that the specified Key has just been output, so if we are in the same region, we do not need to display the region name, and so on.

Specified by:
getName in interface Key
Parameters:
base - The key to use to cut down unnecessary output.
Returns:
The string representation

getRootName

public String getRootName()
Description copied from interface: Key
A Human readable version of the Key's top level name. For Biblical passages this uses short books names. For a dictionary it might return A-Z.

Specified by:
getRootName in interface Key
Returns:
a String containing a description of the Key

getOsisRef

public String getOsisRef()
Description copied from interface: Key
The OSIS defined reference specification for this Key. When the key is a single element, it is an OSIS book name with '.' separating the parts. When the key is multiple elements, it uses a range notation. Note, this will create a comma separated list of ranges, which is improper OSIS.

Specified by:
getOsisRef in interface Key
Returns:
a String containing the OSIS description of the verses

getOsisID

public String getOsisID()
Description copied from interface: Key
The OSIS defined id specification for this Key. When the key is a single element, it is an OSIS book name with '.' separating the parts. When the key is multiple elements, it uses a space to separate each.

Specified by:
getOsisID in interface Key
Returns:
a String containing the OSIS description of the verses

toString

public String toString()
Overrides:
toString in class Object

getStart

public Verse getStart()
Fetch the first verse in this range.

Returns:
The first verse in the range

getEnd

public Verse getEnd()
Fetch the last verse in this range.

Returns:
The last verse in the range

getChapterCount

public int getChapterCount()
How many chapters in this range

Returns:
The number of chapters. Always >= 1.

getBookCount

public int getBookCount()
How many books in this range

Returns:
The number of books. Always >= 1.

clone

public Object clone()
Description copied from interface: Key
This needs to be declared here so that it is visible as a method on a derived Key.

Specified by:
clone in interface Key
Overrides:
clone in class Object
Returns:
A complete copy of ourselves

equals

public boolean equals(Object obj)
Description copied from interface: Key
This needs to be declared here so that it is visible as a method on a derived Key.

Specified by:
equals in interface Key
Overrides:
equals in class Object
Returns:
true if equal

hashCode

public int hashCode()
Description copied from interface: Key
This needs to be declared here so that it is visible as a method on a derived Key.

Specified by:
hashCode in interface Key
Overrides:
hashCode in class Object
Returns:
the hashcode

compareTo

public int compareTo(Object obj)
Specified by:
compareTo in interface Comparable

adjacentTo

public boolean adjacentTo(VerseRange that)
Are the 2 VerseRanges in question contiguous. that is - could they be represented by a single VerseRange. Note that one range could be entirely contained within the other and they would be considered adjacentTo() For example Gen 1:1-2 is adjacent to Gen 1:1-5 and Gen 1:3-4 but not to Gen 1:4-10. Also Gen 1:29-30 is adjacent to Gen 2:1-10

Parameters:
that - The VerseRange to compare to
Returns:
true if the ranges are adjacent

overlaps

public boolean overlaps(VerseRange that)
Do the 2 VerseRanges in question actually overlap. This is slightly more restrictive than the adjacentTo() test which could be satisfied by ranges like Gen 1:1-2 and Gen 1:3-4. overlaps() however would return false given these ranges. For example Gen 1:1-2 is adjacent to Gen 1:1-5 but not to Gen 1:3-4 not to Gen 1:4-10. Also Gen 1:29-30 does not overlap Gen 2:1-10

Parameters:
that - The VerseRange to compare to
Returns:
true if the ranges are adjacent

contains

public boolean contains(Verse that)
Is the given verse entirely within our range. For example if this = "Gen 1:1-31" then: contains(Verse("Gen 1:3")) == true contains(Verse("Gen 2:1")) == false

Parameters:
that - The Verse to compare to
Returns:
true if we contain it.

contains

public boolean contains(VerseRange that)
Is the given range within our range. For example if this = "Gen 1:1-31" then: this.contains(Verse("Gen 1:3-10")) == true this.contains(Verse("Gen 2:1-1")) == false

Parameters:
that - The Verse to compare to
Returns:
true if we contain it.

isWholeChapter

public boolean isWholeChapter()
Does this range represent exactly one chapter, no more or less.

Returns:
true if we are exactly one chapter.

isWholeChapters

public boolean isWholeChapters()
Does this range represent a number of whole chapters

Returns:
true if we are a whole number of chapters.

isWholeBook

public boolean isWholeBook()
Does this range represent exactly one book, no more or less.

Returns:
true if we are exactly one book.

isWholeBooks

public boolean isWholeBooks()
Does this range represent a whole number of books.

Returns:
true if we are a whole number of books.

isMultipleBooks

public boolean isMultipleBooks()
Does this range occupy more than one book;

Returns:
true if we occupy 2 or more books

toVerseArray

public Verse[] toVerseArray()
Create an array of Verses

Returns:
The array of verses that this makes up

rangeIterator

public Iterator rangeIterator(RestrictionType restrict)
Enumerate the subranges in this range

Returns:
a range iterator

getParent

public Key getParent()
Description copied from interface: Key
All keys have parents unless they are the root of a Key.

Specified by:
getParent in interface Key
Returns:
The parent of this tree, or null if this Key is the root.

setParent

public void setParent(Key parent)
Set a parent Key. This allows us to follow the Key interface more closely, although the concept of a parent for a verse is fairly alien.

Parameters:
parent - The parent Key for this verse

remainder

public static VerseRange[] remainder(VerseRange a,
                                     VerseRange b)
Create a DistinctPassage that is the stuff left of VerseRange a when you remove the stuff in VerseRange b.

Parameters:
a - The verses that you might want
b - The verses that you definitely don't
Returns:
A list of the Verses outstanding

intersection

public static VerseRange intersection(VerseRange a,
                                      VerseRange b)
Create a DistinctPassage that is the stuff in VerseRange a that is also in VerseRange b.

Parameters:
a - The verses that you might want
b - The verses that you definitely don't
Returns:
A list of the Verses outstanding

getWholeBibleVerseRange

public static VerseRange getWholeBibleVerseRange()
Returns a VerseRange that wraps the whole Bible

Returns:
The whole bible VerseRange

doGetName

private String doGetName(Key base)
                  throws NoSuchVerseException
Throws:
NoSuchVerseException

calcEnd

private static Verse calcEnd(Verse start,
                             int verseCount)
Calculate the last verse in this range.

Parameters:
start - The first verse in the range
verseCount - The number of verses
Returns:
The last verse in the range

calcVerseCount

private static int calcVerseCount(Verse start,
                                  Verse end)
Calculate how many verses in this range

Parameters:
start - The first verse in the range
end - The last verse in the range
Returns:
The number of verses. Always >= 1.

verifyData

private void verifyData()
Check to see that everything is ok with the Data


writeObject

private void writeObject(ObjectOutputStream out)
                  throws IOException
Write out the object to the given ObjectOutputStream

Parameters:
out - The stream to write our state to
Throws:
IOException - If the write fails

readObject

private void readObject(ObjectInputStream in)
                 throws IOException,
                        ClassNotFoundException
Write out the object to the given ObjectOutputStream

Parameters:
in - The stream to read our state from
Throws:
IOException - If the write fails
ClassNotFoundException - If the read data is incorrect

canHaveChildren

public boolean canHaveChildren()
Description copied from interface: Key
Returns false if the receiver is a leaf node and can not have children. Any attempt to add()/remove() wlll throw

Specified by:
canHaveChildren in interface Key

getChildCount

public int getChildCount()
Description copied from interface: Key
Returns the number of children that this node has. Leaf nodes return 0.

Specified by:
getChildCount in interface Key

getCardinality

public int getCardinality()
Description copied from interface: Key
Returns the number of elements in this set (its cardinality). If this set contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:
getCardinality in interface Key
Returns:
the number of elements in this set (its cardinality).

isEmpty

public boolean isEmpty()
Description copied from interface: Key
Does this Key have 0 members

Specified by:
isEmpty in interface Key
Returns:
true if this set contains no elements.

contains

public boolean contains(Key key)
Description copied from interface: Key
Returns true if this set contains the specified element.

Specified by:
contains in interface Key
Parameters:
key - element whose presence in this set is to be tested.
Returns:
true if this set contains the specified element.

iterator

public Iterator iterator()
Specified by:
iterator in interface Iterable

addAll

public void addAll(Key key)
Description copied from interface: Key
Adds the specified element to this set if it is not already present.

Specified by:
addAll in interface Key
Parameters:
key - element to be added to this set.

removeAll

public void removeAll(Key key)
Description copied from interface: Key
Removes the specified elements from this set if it is present.

Specified by:
removeAll in interface Key
Parameters:
key - object to be removed from this set, if present.

retainAll

public void retainAll(Key key)
Description copied from interface: Key
Removes all but the specified element from this set.

Specified by:
retainAll in interface Key
Parameters:
key - object to be left in this set.

clear

public void clear()
Description copied from interface: Key
Removes all of the elements from this set (optional operation). This set will be empty after this call returns (unless it throws an exception).

Specified by:
clear in interface Key

get

public Key get(int index)
Description copied from interface: Key
Gets a key from a specific point in this list of children.

Specified by:
get in interface Key
Parameters:
index - The index of the Key to retrieve
Returns:
The specified key

indexOf

public int indexOf(Key that)
Description copied from interface: Key
Reverse a Key into the position the key holds in the list of children

Specified by:
indexOf in interface Key
Parameters:
that - The Key to find
Returns:
The index of the key or < 0 if the key is not in the list

blur

public void blur(int by,
                 RestrictionType restrict)
Description copied from interface: Key
Widen the range of the verses/keys in this list. This is primarily for "find x within n verses of y" type applications.

Specified by:
blur in interface Key
Parameters:
by - The number of verses/keys to widen by
restrict - How should we restrict the blurring?
See Also:
Passage

Copyright ยจ 2003-2007