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 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
`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
`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 patch_up)` 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
`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 patch_up)

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

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