Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.crosswire.jsword.passage
Class VerseRange

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

All Implemented Interfaces:
  Serializable, Cloneable, Comparable, Key, VerseBase

    public final class VerseRange

extends Object
implements VerseBase

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 mis-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
`(package private) static long` | `serialVersionUID` To make serialization work across new versions
`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 contigious.
`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)` Calcualte how many verses in this range
`boolean` | `canHaveChildren()` Returns true 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.
`boolean` | `equals(Object obj)`
`Key` | `get(int index)` Gets a key from a specific point in this list.
`int` | `getBookCount()` How many books in this range
`int` | `getChapterCount()` How many chapters in this range
`int` | `getChildCount()` Returns the number of elements in this set (its cardinality).
`Verse` | `getEnd()` Fetch the last verse in this range.
`String` | `getName()` Fetch a more sensible shortened version of the name
`String` | `getName(Verse base)` Fetch a more sensible shortened version of the name
`String` | `getOsisID()` The OSIS defined id specification for this VerseRange.
`String` | `getOsisRef()` The OSIS defined reference specification for this VerseRange.
`Key` | `getParent()` All keys have parents unless they are the root of a Key.
`Verse` | `getStart()` Fetch the first verse in this range.
`int` | `getVerseCount()` How many verses in this range
`static VerseRange` | `getWholeBibleVerseRange()` Returns a VerseRange that wraps the whole Bible
`int` | `hashCode()`
`int` | `indexOf(Key that)` Reverse a Key into the position the key holds in the list
`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 Passage 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()` This just clones getName which seems the most sensible type of string to return.
`Verse[]` | `toVerseArray()` Create an array of Verses
`private void` | `verifyData()` Check to see that everything is ok with the Data
`Iterator` | `verseIterator()` Enumerate over the verse in this range
`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

  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

### 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 Everying 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()

  Fetch a more sensible shortened version of the name

  Specified by:
    `getName` in interface `Key`
  Specified by:
    `getName` in interface `VerseBase`
  Returns:
    A string like 'Gen 1:1-2'

### getName

    public String getName(Verse base)

  Fetch a more sensible shortened version of the name

  Specified by:
    `getName` in interface `VerseBase`
  Parameters:
    `base` - A reference to allow things like Gen 1:1,3,5 as an output
  Returns:
    A string like 'Gen 1:1-2'

### getOsisRef

    public String getOsisRef()

  The OSIS defined reference specification for this VerseRange. Uses osis books names, with "." as a verse part separator.

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

### getOsisID

    public String getOsisID()

  The OSIS defined id specification for this VerseRange. Uses osis books names, with "." as a verse part separator. Each verse is separated by a space.

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

### toString

    public String toString()

  This just clones getName which seems the most sensible type of string to return.

  Overrides:
    `toString` in class `Object`
  Returns:
    A string like 'Gen 1:1-2'

### 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

### getVerseCount

    public int getVerseCount()

  How many verses in this range

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

### 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)

  Overrides:
    `equals` in class `Object`

### hashCode

    public int hashCode()

  Overrides:
    `hashCode` in class `Object`

### compareTo

    public int compareTo(Object obj)

  Specified by:
    `compareTo` in interface `Comparable`

### adjacentTo

    public boolean adjacentTo(VerseRange that)

  Are the 2 VerseRanges in question contigious. ie - 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

  Specified by:
    `toVerseArray` in interface `VerseBase`
  Returns:
    The array of verses that this makes up
  See Also:
    `VerseBase.verseIterator()`

### verseIterator

    public Iterator verseIterator()

  Enumerate over the verse in this range

  Specified by:
    `verseIterator` in interface `VerseBase`
  Returns:
    A verse iterator

### 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 definately 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 definately 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

### 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)

  Calcualte 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 true 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 elements in this set (its cardinality). If this set contains more than `Integer.MAX_VALUE` elements, returns `Integer.MAX_VALUE`.

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

### isEmpty

    public boolean isEmpty()

  Description copied from interface: `Key`
  Does this Passage 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 `Key`
  Returns:
    an iterator over the elements in this set.

### 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.

  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

  Specified by:
    `indexOf` in interface `Key`
  Parameters:
    `that` - The Key to find
  Returns:
    The index of the key or -1 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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Copyright ¨ 2003-2005
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD