org.crosswire.jsword.passage

## Class Verse

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

- All Implemented Interfaces:
    Serializable, Cloneable, Comparable<Key>, Iterable<Key>, Key, VerseKey<Verse>

      public final class Verse
      extends Object
      implements VerseKey<Verse>

  A Verse is a pointer to a single verse. Externally its unique identifier is a String of the form "Gen 1:1" Internally we use `( v11n, book, chapter, verse )`

  A Verse is designed to be immutable. This is a necessary from a collections point of view. A Verse should always be valid, although some versions may not return any text for verses that they consider to be untranslated in some way.

  Author:
    Joe Walker, DM Smith
  See Also:
    `The GNU Lesser General Public License for details.`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private BibleBook` | `book` The book of the Bible.
    `private int` | `chapter` The chapter number
    `static Verse` | `DEFAULT` The default verse
    `private static org.slf4j.Logger` | `log`
    `private int` | `ordinal` The ordinal value for this verse within its versification.
    `private static long` | `serialVersionUID` To make serialization work across new versions
    `private static NumberShaper` | `shaper` Allow the conversion to and from other number representations.
    `private String` | `subIdentifier` The OSIS Sub-identifier if present.
    `private Versification` | `v11n` The versification for this verse.
    `private int` | `verse` The verse number
    `static char` | `VERSE_OSIS_DELIM` What characters should we use to separate parts of an OSIS verse reference
    `static char` | `VERSE_OSIS_SUB_PREFIX` What characters should we use to start an OSIS sub identifier
    `static char` | `VERSE_PREF_DELIM1` What characters should we use to separate the book from the chapter
    `static char` | `VERSE_PREF_DELIM2` What characters should we use to separate the chapter from the verse

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Verse(Versification v11n, BibleBook book, int chapter, int verse)` Create a Verse from book, chapter and verse numbers, throwing up if the specified Verse does not exist.
    `Verse(Versification v11n, BibleBook book, int chapter, int verse, boolean patchUp)` Create a Verse from book, chapter and verse numbers, patching up if the specified verse does not exist.
    `Verse(Versification v11n, BibleBook book, int chapter, int verse, String subIdentifier)` Create a Verse from book, chapter and verse numbers, throwing up if the specified Verse does not exist.
    `Verse(Versification v11n, int ordinal)` Set a Verse using a verse ordinal number - WARNING Do not use this method unless you really know the dangers of doing so.

  - ### 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.
    `void` | `blur(int by, RestrictionType restrict)` Widen the range of the verses/keys in this list.
    `static boolean` | `bothNullOrEqual(Object x, Object y)` Determine whether two objects are equal, allowing nulls
    `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).
    `Verse` | `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.
    `private String` | `doGetName(Verse verseBase)` Compute the verse representation given the context.
    `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.
    `BibleBook` | `getBook()` Return the book that we refer to
    `int` | `getCardinality()` Returns the number of elements in this set (its cardinality).
    `int` | `getChapter()` Return the chapter that we refer to
    `int` | `getChildCount()` Returns the number of children that this node has.
    `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.
    `int` | `getOrdinal()` Return the ordinal value of the verse in its versification.
    `String` | `getOsisID()` The OSIS defined id specification for this Key.
    `String` | `getOsisIDNoSubIdentifier()`
    `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.
    `String` | `getSubIdentifier()` Return the sub identifier if any
    `int` | `getVerse()` Return the verse that we refer to
    `private StringBuilder` | `getVerseIdentifier()` Gets the common name of the verse, excluding any !abc sub-identifier
    `Versification` | `getVersification()` Get the Versification that defines the Verses in this VerseKey.
    `Verse` | `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
    `boolean` | `isEmpty()` Does this Key have 0 members
    `boolean` | `isWhole()` A VerseKey that does not have an OSIS sub identifier is a whole reference.
    `Iterator<Key>` | `iterator()`
    `protected static int` | `parseInt(String text)` This is simply a convenience function to wrap Integer.parseInt() and give us a reasonable exception on failure.
    `private void` | `readObject(ObjectInputStream in)` Write out the object to the given ObjectOutputStream
    `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.
    `Verse` | `reversify(Versification newVersification)` Cast this VerseKey into another Versification.
    `String` | `toString()`
    `Verse[]` | `toVerseArray()` Create an array of Verses
    `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

    - #### VERSE_OSIS_DELIM

          public static final char VERSE_OSIS_DELIM

      What characters should we use to separate parts of an OSIS verse reference
      See Also:
        Constant Field Values

    - #### VERSE_OSIS_SUB_PREFIX

          public static final char VERSE_OSIS_SUB_PREFIX

      What characters should we use to start an OSIS sub identifier
      See Also:
        Constant Field Values

    - #### VERSE_PREF_DELIM1

          public static final char VERSE_PREF_DELIM1

      What characters should we use to separate the book from the chapter
      See Also:
        Constant Field Values

    - #### VERSE_PREF_DELIM2

          public static final char VERSE_PREF_DELIM2

      What characters should we use to separate the chapter from the verse
      See Also:
        Constant Field Values

    - #### DEFAULT

          public static final Verse DEFAULT

      The default verse

    - #### shaper

          private static NumberShaper shaper

      Allow the conversion to and from other number representations.

    - #### v11n

          private transient Versification v11n

      The versification for this verse.

    - #### ordinal

          private int ordinal

      The ordinal value for this verse within its versification.

    - #### book

          private transient BibleBook book

      The book of the Bible.

    - #### chapter

          private transient int chapter

      The chapter number

    - #### verse

          private transient int verse

      The verse number

    - #### subIdentifier

          private String subIdentifier

      The OSIS Sub-identifier if present. This should be a string that allows for the likes of: a.xy.asdf.qr

    - #### log

          private static final org.slf4j.Logger log

    - #### serialVersionUID

          private static final long serialVersionUID

      To make serialization work across new versions
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Verse

          public Verse(Versification v11n,
               BibleBook book,
               int chapter,
               int verse)

      Create a Verse from book, chapter and verse numbers, throwing up if the specified Verse does not exist.
      Parameters:
        `v11n` - The versification to which this verse belongs
        `book` - The book number (Genesis = 1)
        `chapter` - The chapter number
        `verse` - The verse number

    - #### Verse

          public Verse(Versification v11n,
               BibleBook book,
               int chapter,
               int verse,
               String subIdentifier)

      Create a Verse from book, chapter and verse numbers, throwing up if the specified Verse does not exist.
      Parameters:
        `v11n` - The versification to which this verse belongs
        `book` - The book number (Genesis = 1)
        `chapter` - The chapter number
        `verse` - The verse number
        `subIdentifier` - The optional sub identifier

    - #### Verse

          public Verse(Versification v11n,
               BibleBook book,
               int chapter,
               int verse,
               boolean patchUp)

      Create a Verse from book, chapter and verse numbers, patching up if the specified verse does not exist.

      The actual value of the boolean is ignored. However for future proofing you should only use 'true'. Do not use patch_up=false, use `Verse(int, int, int)` This so that we can declare this constructor to not throw an exception. Is there a better way of doing this?

      Parameters:
        `v11n` - The versification to which this verse belongs
        `book` - The book number (Genesis = 1)
        `chapter` - The chapter number
        `verse` - The verse number
        `patchUp` - True to trigger reference fixing

    - #### Verse

          public Verse(Versification v11n,
               int ordinal)

      Set a Verse using a verse ordinal number - WARNING Do not use this method unless you really know the dangers of doing so. Ordinals are not always going to be the same. So you should use Versification, Book, Chapter and Verse in preference to an int ordinal whenever possible. Ordinal numbers are 1 based and not 0 based.
      Parameters:
        `v11n` - The versification to which this verse belongs
        `ordinal` - The verse id

  - ### Method Detail

    - #### 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<Verse>`
      Returns:
        whether this is a whole reference

    - #### getWhole

          public Verse 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<Verse>`
      Returns:
        a whole reference

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

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

    - #### getOsisIDNoSubIdentifier

          public String getOsisIDNoSubIdentifier()

    - #### getVerseIdentifier

          private StringBuilder getVerseIdentifier()

      Gets the common name of the verse, excluding any !abc sub-identifier
      Returns:
        the verse OSIS-ID, excluding the sub-identifier

    - #### clone

          public Verse 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>`

    - #### 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<Verse>`
      Returns:
        this VerseKey Versification.

    - #### reversify

          public Verse 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<Verse>`
      Returns:
        this VerseKey Versification.

    - #### getBook

          public BibleBook getBook()

      Return the book that we refer to
      Returns:
        The book of the Bible

    - #### getChapter

          public int getChapter()

      Return the chapter that we refer to
      Returns:
        The chapter number

    - #### getVerse

          public int getVerse()

      Return the verse that we refer to
      Returns:
        The verse number

    - #### getSubIdentifier

          public String getSubIdentifier()

      Return the sub identifier if any
      Returns:
        The optional OSIS sub identifier

    - #### getOrdinal

          public int getOrdinal()

      Return the ordinal value of the verse in its versification.
      Returns:
        The verse number

    - #### toVerseArray

          public Verse[] toVerseArray()

      Create an array of Verses
      Returns:
        The array of verses that this makes up

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

    - #### bothNullOrEqual

          public static boolean bothNullOrEqual(Object x,
                                Object y)

      Determine whether two objects are equal, allowing nulls
      Parameters:
        `x` -
        `y` -
      Returns:
        true if both are null or the two are equal

    - #### doGetName

          private String doGetName(Verse verseBase)

      Compute the verse representation given the context.
      Parameters:
        `verseBase` - the context or null if there is none
      Returns:
        the verse representation

    - #### parseInt

          protected static int parseInt(String text)
                                 throws NoSuchVerseException

      This is simply a convenience function to wrap Integer.parseInt() and give us a reasonable exception on failure. It is called by VerseRange hence protected, however I would prefer private
      Parameters:
        `text` - The string to be parsed
      Returns:
        The correctly parsed chapter or verse
      Throws:
        `NoSuchVerseException`

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

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