VerseRange

java.lang.Object
- org.crosswire.jsword.passage.VerseRange

All Implemented Interfaces:

Serializable, Cloneable, Comparable<Key>, Iterable<Key>, Key, VerseKey<VerseRange>
```
public final class VerseRange
extends Object
implements VerseKey<VerseRange>
```
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, DM Smith

See Also:
The GNU Lesser General Public License for details., Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

private static class VerseRange.VerseIterator
Iterate over the Verses in the VerseRange

Nested Classes
Modifier and Type	Class and Description
`private static class`	`VerseRange.VerseIterator` Iterate over the Verses in the VerseRange

Field Summary

Fields
Modifier and Type	Field and Description
`private Verse`	`end` The last verse.
`private String`	`originalName` The original string for picky users
`private Key`	`parent` The parent key.
`static char`	`RANGE_OSIS_DELIM` What characters can we use to separate the 2 parts to a VerseRanges
`static char`	`RANGE_PREF_DELIM` What characters should we use to separate VerseRange parts on output
`(package private) static long`	`serialVersionUID` Serialization ID
`private NumberShaper`	`shaper` Allow the conversion to and from other number representations.
`private Verse`	`start` The start of the range
`private Versification`	`v11n` The Versification with which this range is defined.
`private int`	`verseCount` The number of verses in the range

Constructor Summary

Constructors
Constructor and Description
`VerseRange(VerseRange a, VerseRange b)` Merge 2 VerseRanges together.
`VerseRange(Versification v11n)` The default VerseRange is a single verse - Genesis 1:1.
`VerseRange(Versification v11n, Verse start)` Construct a VerseRange from a Verse.
`VerseRange(Versification v11n, Verse start, Verse end)`

Method Summary

Methods
Modifier and Type	Method and Description
`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 Verse`	`calcEnd()` Calculate the last verse in this range.
`private int`	`calcVerseCount()` 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).
`VerseRange`	`clone()` This needs to be declared here so that it is visible as a method on a derived Key.
`int`	`compareTo(Key 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`	`getCardinality()` Returns the number of elements in this set (its cardinality).
`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.
`Versification`	`getVersification()` Get the Versification that defines the Verses in this VerseKey.
`VerseRange`	`getWhole()` Convert this reference into one without a sub-identifier.
`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 VerseRange 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`	`isWhole()` A VerseKey that does not have an OSIS sub identifier is a whole reference.
`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<Key>`	`iterator()`
`boolean`	`overlaps(VerseRange that)` Do the 2 VerseRanges in question actually overlap.
`Iterator<VerseRange>`	`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 VerseRange 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.
`VerseRange`	`reversify(Versification newVersification)` Cast this VerseKey into another Versification.
`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_OSIS_DELIM
```
public static final char RANGE_OSIS_DELIM
```
    What characters can we use to separate the 2 parts to a VerseRanges
    
    See Also:
    Constant Field Values
  - RANGE_PREF_DELIM
```
public static final char RANGE_PREF_DELIM
```
    What characters should we use to separate VerseRange parts on output
    
    See Also:
    Constant Field Values
  - v11n
```
private transient Versification v11n
```
    The Versification with which this range is defined.
  - start
```
private Verse start
```
    The start of the range
  - verseCount
```
private int verseCount
```
    The number of verses in the range
  - end
```
private transient Verse end
```
    The last verse. Not actually needed, since it can be computed.
  - shaper
```
private transient NumberShaper shaper
```
    Allow the conversion to and from other number representations.
  - parent
```
private transient Key parent
```
    The parent key.
  - originalName
```
private transient String originalName
```
    The original string for picky users
  - serialVersionUID
```
static final long serialVersionUID
```
    Serialization ID
    
    See Also:
    Constant Field Values
- Constructor Detail
  - VerseRange
```
public VerseRange(Versification v11n)
```
    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.
    
    Parameters:
    v11n - The versification for the range
  - VerseRange
```
public VerseRange(Versification v11n,
          Verse start)
```
    Construct a VerseRange from a Verse. The resultant VerseRange will be 1 verse in verseCount.
    
    Parameters:
    v11n - The versification for the range
    start - The verse to start from
  - VerseRange
```
public VerseRange(Versification v11n,
          Verse start,
          Verse end)
```
  - 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
  - getVersification
```
public Versification getVersification()
```
    Description copied from interface: VerseKey
    
    Get the Versification that defines the Verses in this VerseKey.
    
    Specified by:
    
    getVersification in interface VerseKey<VerseRange>
    
    Returns:
    this VerseKey Versification.
  - reversify
```
public VerseRange reversify(Versification newVersification)
```
    Description copied from interface: VerseKey
    
    Cast this VerseKey into another Versification. OSIS Sub Identifiers are ignored.
    Note: This is dangerous as it does not consider chapter boundaries or whether the verses in this VerseKey are actually part of the new versification. It should only be used when the start and end verses are in both Versifications. You have been warned.
    
    Specified by:
    
    reversify in interface VerseKey<VerseRange>
    
    Returns:
    this VerseKey Versification.
  - isWhole
```
public boolean isWhole()
```
    Description copied from interface: VerseKey
    
    A VerseKey that does not have an OSIS sub identifier is a whole reference.
    
    Specified by:
    
    isWhole in interface VerseKey<VerseRange>
    
    Returns:
    whether this is a whole reference
  - getWhole
```
public VerseRange getWhole()
```
    Description copied from interface: VerseKey
    
    Convert this reference into one without a sub-identifier. A Verse with an OSIS sub-identifier represents part of a reference.
    
    Specified by:
    
    getWhole in interface VerseKey<VerseRange>
    
    Returns:
    a whole reference
  - 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, for example "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
  - clone
```
public VerseRange 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(Key obj)
```
    Specified by:
    
    compareTo in interface Comparable<Key>
  - 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.
  - 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.
  - 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<VerseRange> rangeIterator(RestrictionType restrict)
```
    Enumerate the subranges in this range
    
    Parameters:
    restrict -
    
    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 VerseRange that is the stuff left of VerseRange a when you remove the stuff in VerseRange b.
    
    Parameters:
    a - Verses at the start or end of b
    b - All the verses
    
    Returns:
    A list of the Verses outstanding
  - intersection
```
public static VerseRange intersection(VerseRange a,
                      VerseRange b)
```
    Create a VerseRange 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
  - doGetName
```
private String doGetName(Key base)
```
  - calcEnd
```
private Verse calcEnd()
```
    Calculate the last verse in this range.
    
    Returns:
    The last verse in the range
  - calcVerseCount
```
private int calcVerseCount()
```
    Calculate how many verses in this 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() will throw
    
    Specified by:
    
    canHaveChildren in interface Key
    
    Returns:
    true if the key can have children
  - 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
    
    Returns:
    the number of children for the node
  - 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.
    This method is potentially expensive, as it often requires cycling through all the keys in the set.
    
    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.
  - iterator
```
public Iterator<Key> iterator()
```
    Specified by:
    
    iterator in interface Iterable<Key>
  - 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

Class VerseRange

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

RANGE_OSIS_DELIM

RANGE_PREF_DELIM

v11n

start

verseCount

end

shaper

parent

originalName

serialVersionUID

Constructor Detail

VerseRange

VerseRange

VerseRange

VerseRange

Method Detail

getVersification

reversify

isWhole

getWhole

getName

getName

getRootName

getOsisRef

getOsisID

toString

getStart

getEnd

clone

equals

hashCode

compareTo

adjacentTo

overlaps

contains

contains

contains

isWholeChapter

isWholeChapters

isWholeBook

isWholeBooks

isMultipleBooks

toVerseArray

rangeIterator

getParent

setParent

remainder

intersection

doGetName

calcEnd

calcVerseCount

verifyData

writeObject

readObject

canHaveChildren

getChildCount

getCardinality

isEmpty

iterator

addAll

removeAll

retainAll

clear

get

indexOf

blur