org.crosswire.jsword.versification

## Class Versification

- java.lang.Object
- - org.crosswire.jsword.versification.Versification

- All Implemented Interfaces:
    Serializable, ReferenceSystem
  Direct Known Subclasses:
    SystemCalvin, SystemCatholic, SystemCatholic2, SystemDarbyFR, SystemDefault, SystemGerman, SystemKJV, SystemKJVA, SystemLeningrad, SystemLuther, SystemLXX, SystemMT, SystemNRSV, SystemNRSVA, SystemOrthodox, SystemSegond, SystemSynodal, SystemSynodalProt, SystemVulg

      public class Versification
      extends Object
      implements ReferenceSystem, Serializable

  A named Versification defines the order of BibleBooks by Testament, the number of chapters in each BibleBook, the number of verses in each chapter.
  Author:
    DM Smith
  See Also:
    `The GNU Lesser General Public License for details.`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private BibleBookList` | `bookList` The ordered list of books in this versification.
    `private int[][]` | `chapterStarts` Constant for the ordinal number of the first verse in each chapter.
    `private int[][]` | `lastVerse` Constant for the max verse number in each chapter
    `private String` | `name` The OSIS name of the reference system.
    `private int` | `ntMaxOrdinal` The last ordinal number of the New Testament and the maximum ordinal number of this Reference System
    `private int` | `otMaxOrdinal` The last ordinal number of the Old Testament
    `private static long` | `serialVersionUID` Serialization ID

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Versification()`
    `Versification(String name, BibleBook[] booksOT, BibleBook[] booksNT, int[][] lastVerseOT, int[][] lastVerseNT)` Construct a Versification.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Verse` | `add(Verse verse, int n)` Get the verse that is a few verses on from the one we've got.
    `boolean` | `containsBook(BibleBook book)` Does this Versification contain the BibleBook.
    `Verse` | `decodeOrdinal(int ordinal)` Where does this verse come in the Bible.
    `int` | `distance(Verse start, Verse end)` How many verses are there in between the 2 Verses.
    `static void` | `dump(PrintStream out, String name, BibleBookList bookList, int[][] array)`
    `VerseRange` | `getAllVerses()` Get a VerseRange encompassing this Versification.
    `BibleBook` | `getBook(int ordinal)` Get the BibleBook by its position in this Versification.
    `BibleBook` | `getBook(String find)` Get a book from its name.
    `int` | `getBookCount()` Get the number of books in this Versification.
    `int` | `getBookCount(Verse start, Verse end)` The number of books between two verses includes the books of the two verses and everything in between.
    `Iterator<BibleBook>` | `getBookIterator()` Get the BibleBooks in this Versification.
    `BookName` | `getBookName(BibleBook book)` Get the BookName.
    `int` | `getChapterCount(Verse start, Verse end)` The number of chapters between two verses includes the chapters of the two verses and everything in between.
    `int` | `getCount(Testament testament)` Give the count of verses in the testament or the whole Bible.
    `BibleBook` | `getFirstBook()` Return the first book in the list.
    `BibleBook` | `getLastBook()` Return the first book in the list.
    `int` | `getLastChapter(BibleBook book)` Get the last valid chapter number for a book.
    `int` | `getLastVerse(BibleBook book, int chapter)` Get the last valid verse number for a chapter.
    `String` | `getLongName(BibleBook book)` Get the full name of a book (e.g.
    `String` | `getName()` Get the OSIS name for this Versification.
    `BibleBook` | `getNextBook(BibleBook book)` Given a BibleBook, get the next BibleBook in this Versification.
    `int` | `getOrdinal(Testament testament, int testamentOrdinal)` Determine the ordinal value for this versification given the ordinal value in a testament.
    `int` | `getOrdinal(Verse verse)` Where does this verse come in the Bible.
    `String` | `getPreferredName(BibleBook book)` Get the preferred name of a book.
    `BibleBook` | `getPreviousBook(BibleBook book)` Given a BibleBook, get the previous BibleBook in this Versification.
    `String` | `getShortName(BibleBook book)` Get the short name of a book (e.g.
    `Testament` | `getTestament(int ordinal)` Get the testament of a given verse
    `int` | `getTestamentOrdinal(int ordinal)` Where does this verse come in the Bible.
    `boolean` | `isAdjacentBook(Verse first, Verse second)` Two verses are in adjacent books if one book follows the other in this versification.
    `boolean` | `isAdjacentChapter(Verse first, Verse second)` Two verse are adjacent if one immediately follows the other, even across book boundaries.
    `boolean` | `isAdjacentVerse(Verse first, Verse second)` Is this verse adjacent to another verse
    `boolean` | `isBook(String find)` Is the given string a valid book name.
    `boolean` | `isBookIntro(Verse verse)` A book introduction is an introduction that has a chapter of 0.
    `boolean` | `isChapterIntro(Verse verse)` A chapter introduction is an introduction that has a chapter other than 0
    `boolean` | `isEndOfBook(Verse verse)` The end of the book is indicated by the chapter number matching the last chapter in the book and the verse number matching the last verse in the chapter.
    `boolean` | `isEndOfChapter(Verse verse)` The end of the chapter is indicated by the verse number matching the last in the chapter.
    `boolean` | `isIntro(Verse verse)` An introduction is a Verse that has a verse number of 0.
    `boolean` | `isSameBook(Verse first, Verse second)` Two verses are in the same book when they have the same book.
    `boolean` | `isSameChapter(Verse first, Verse second)` Two verses are in the same chapter if both the book and chapter agree.
    `boolean` | `isStartOfBook(Verse verse)` The start of a book is indicated by a chapter number of 0 or 1 and a verse number of 0 or 1.
    `boolean` | `isStartOfChapter(Verse verse)` The start of a chapter is indicated by a verse number of 0 or 1
    `Verse` | `max(Verse first, Verse second)` Determine the later of the two verses.
    `int` | `maximumOrdinal()` The maximum number of verses in the Bible, including module, testament, book and chapter introductions.
    `Verse` | `min(Verse first, Verse second)` Determine the earlier of the two verses.
    `Verse` | `next(Verse verse)` Get the verse that is a verses on from the one we've got.
    `static void` | `optimize(PrintStream out, BibleBookList bookList, int[][] lastVerse)`
    `Verse` | `patch(BibleBook book, int chapter, int verse)` Fix up these verses so that they are as valid a possible.
    `Verse` | `subtract(Verse verse, int n)` Get the verse n down from here this Verse.
    `void` | `validate(BibleBook book, int chapter, int verse)` Does the following represent a real verse?.
    `boolean` | `validate(BibleBook book, int chapter, int verse, boolean silent)` Does the following represent a real verse?.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### name

          private String name

      The OSIS name of the reference system.

    - #### bookList

          private BibleBookList bookList

      The ordered list of books in this versification.

    - #### otMaxOrdinal

          private int otMaxOrdinal

      The last ordinal number of the Old Testament

    - #### ntMaxOrdinal

          private int ntMaxOrdinal

      The last ordinal number of the New Testament and the maximum ordinal number of this Reference System

    - #### lastVerse

          private int[][] lastVerse

      Constant for the max verse number in each chapter

    - #### chapterStarts

          private int[][] chapterStarts

      Constant for the ordinal number of the first verse in each chapter.

    - #### serialVersionUID

          private static final long serialVersionUID

      Serialization ID
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Versification

          public Versification()

    - #### Versification

          public Versification(String name,
                       BibleBook[] booksOT,
                       BibleBook[] booksNT,
                       int[][] lastVerseOT,
                       int[][] lastVerseNT)

      Construct a Versification.
      Parameters:
        `name` - The name of this reference system
        `booksOT` - An ordered list of books in this reference system. The list should not include INTRO_BIBLE, or INTRO_OT.
        `booksNT` - An ordered list of books in this reference system. The list should not include INTRO_NT.
        `lastVerseOT` - For each book in booksOT, this has an array with one entry for each chapter whose value is the highest numbered verse in that chapter. Do not include chapter 0.
        `lastVerseNT` - For each book in booksNT, this has an array with one entry for each chapter whose value is the highest numbered verse in that chapter. Do not include chapter 0.

  - ### Method Detail

    - #### getName

          public String getName()

      Get the OSIS name for this Versification.
      Returns:
        the OSIS name of the Versification

    - #### containsBook

          public boolean containsBook(BibleBook book)

      Does this Versification contain the BibleBook.
      Parameters:
        `book` -
      Returns:
        true if it is present.

    - #### getBook

          public BibleBook getBook(int ordinal)

      Get the BibleBook by its position in this Versification. If the position is negative, return the first book. If the position is greater than the last, return the last book.
      Parameters:
        `ordinal` -
      Returns:
        the indicated book

    - #### getBook

          public BibleBook getBook(String find)

      Get a book from its name.
      Parameters:
        `find` - The string to identify
      Returns:
        The BibleBook, On error null

    - #### getBookCount

          public int getBookCount()

      Get the number of books in this Versification.
      Returns:
        the number of books

    - #### getBookCount

          public int getBookCount(Verse start,
                         Verse end)

      The number of books between two verses includes the books of the two verses and everything in between.
      Parameters:
        `start` - The first Verse in the range
        `end` - The last Verse in the range
      Returns:
        The number of books. Always >= 1.

    - #### getFirstBook

          public BibleBook getFirstBook()

      Return the first book in the list.
      Returns:
        the first book in the list

    - #### getLastBook

          public BibleBook getLastBook()

      Return the first book in the list.
      Returns:
        the first book in the list

    - #### getNextBook

          public BibleBook getNextBook(BibleBook book)

      Given a BibleBook, get the next BibleBook in this Versification. If it is the last book, return null.
      Parameters:
        `book` - A BibleBook in the Versification
      Returns:
        the previous BibleBook or null.

    - #### getPreviousBook

          public BibleBook getPreviousBook(BibleBook book)

      Given a BibleBook, get the previous BibleBook in this Versification. If it is the first book, return null.
      Parameters:
        `book` - A BibleBook in the Versification
      Returns:
        the previous BibleBook or null.

    - #### getBookIterator

          public Iterator<BibleBook> getBookIterator()

      Get the BibleBooks in this Versification.
      Returns:
        an Iterator over the books

    - #### getBookName

          public BookName getBookName(BibleBook book)

      Get the BookName.
      Parameters:
        `book` - the desired book
      Returns:
        The requested BookName or null if not in this versification

    - #### getPreferredName

          public String getPreferredName(BibleBook book)

      Get the preferred name of a book. Altered by the case setting (see setBookCase() and isFullBookName())
      Parameters:
        `book` - the desired book
      Returns:
        The full name of the book or null if not in this versification

    - #### getLongName

          public String getLongName(BibleBook book)

      Get the full name of a book (e.g. "Genesis"). Altered by the case setting (see setBookCase())
      Parameters:
        `book` - the book of the Bible
      Returns:
        The full name of the book or null if not in this versification

    - #### getShortName

          public String getShortName(BibleBook book)

      Get the short name of a book (e.g. "Gen"). Altered by the case setting (see setBookCase())
      Parameters:
        `book` - the book of the Bible
      Returns:
        The short name of the book or null if not in this versification

    - #### isBook

          public boolean isBook(String find)

      Is the given string a valid book name. If this method returns true then getBook() will return a BibleBook and not null.
      Parameters:
        `find` - The string to identify
      Returns:
        true when the book name is recognized

    - #### getLastChapter

          public int getLastChapter(BibleBook book)

      Get the last valid chapter number for a book.
      Parameters:
        `book` - The book part of the reference.
      Returns:
        The last valid chapter number for a book.

    - #### getLastVerse

          public int getLastVerse(BibleBook book,
                         int chapter)

      Get the last valid verse number for a chapter.
      Parameters:
        `book` - The book part of the reference.
        `chapter` - The current chapter
      Returns:
        The last valid verse number for a chapter

    - #### getAllVerses

          public VerseRange getAllVerses()

      Get a VerseRange encompassing this Versification.
      Returns:
        a VerseRange for the whole versification

    - #### isIntro

          public boolean isIntro(Verse verse)

      An introduction is a Verse that has a verse number of 0.
      Parameters:
        `verse` - the verse to test
      Returns:
        true or false ...

    - #### isBookIntro

          public boolean isBookIntro(Verse verse)

      A book introduction is an introduction that has a chapter of 0.
      Parameters:
        `verse` - the verse to test
      Returns:
        true or false ...

    - #### isChapterIntro

          public boolean isChapterIntro(Verse verse)

      A chapter introduction is an introduction that has a chapter other than 0
      Parameters:
        `verse` - the verse to test
      Returns:
        true or false ...

    - #### isStartOfChapter

          public boolean isStartOfChapter(Verse verse)

      The start of a chapter is indicated by a verse number of 0 or 1
      Parameters:
        `verse` - the verse to test
      Returns:
        true or false ...

    - #### isEndOfChapter

          public boolean isEndOfChapter(Verse verse)

      The end of the chapter is indicated by the verse number matching the last in the chapter.
      Parameters:
        `verse` - the verse to test
      Returns:
        true or false ...

    - #### isStartOfBook

          public boolean isStartOfBook(Verse verse)

      The start of a book is indicated by a chapter number of 0 or 1 and a verse number of 0 or 1.
      Parameters:
        `verse` - the verse to test
      Returns:
        true or false ...

    - #### isEndOfBook

          public boolean isEndOfBook(Verse verse)

      The end of the book is indicated by the chapter number matching the last chapter in the book and the verse number matching the last verse in the chapter.
      Parameters:
        `verse` - the verse to test
      Returns:
        true or false ...

    - #### isSameChapter

          public boolean isSameChapter(Verse first,
                              Verse second)

      Two verses are in the same chapter if both the book and chapter agree.
      Parameters:
        `first` - The verse to compare to
        `second` - The verse to compare to
      Returns:
        true or false ...

    - #### isAdjacentChapter

          public boolean isAdjacentChapter(Verse first,
                                  Verse second)

      Two verse are adjacent if one immediately follows the other, even across book boundaries. Introductions are considered as having "zero width" in this determination. That is the last verse in a chapter or book is adjacent every verse that follows up to and including verse 1 of the next chapter in the versification.
      For example:
      The last verse in the Old Testament is adjacent to:
      - Intro.NT - the New Testament introduction
      - Matt 0:0 - the book introduction
      - Matt 1:0 - the chapter introduction
      - Matt 1:1 - the first verse of Matt
      Note: the verses can be in any order.
      Parameters:
        `first` - The verse to compare to
        `second` - The verse to compare to
      Returns:
        true or false ...

    - #### isSameBook

          public boolean isSameBook(Verse first,
                           Verse second)

      Two verses are in the same book when they have the same book.
      Parameters:
        `first` - The verse to compare to
        `second` - The verse to compare to
      Returns:
        true or false ...

    - #### isAdjacentBook

          public boolean isAdjacentBook(Verse first,
                               Verse second)

      Two verses are in adjacent books if one book follows the other in this versification. Note: the verses can be in any order.
      Parameters:
        `first` - The verse to compare to
        `second` - The verse to compare to
      Returns:
        true or false ...

    - #### isAdjacentVerse

          public boolean isAdjacentVerse(Verse first,
                                Verse second)

      Is this verse adjacent to another verse
      Parameters:
        `first` - The first verse in the comparison
        `second` - The second verse in the comparison
      Returns:
        true if the verses are adjacent.

    - #### distance

          public int distance(Verse start,
                     Verse end)

      How many verses are there in between the 2 Verses. The answer is -ve if start is bigger than end. The answer is inclusive of start and exclusive of end, so that `distance(gen11, gen12) == 1`
      Parameters:
        `start` - The first Verse in the range
        `end` - The last Verse in the range
      Returns:
        The count of verses between this and that.

    - #### min

          public Verse min(Verse first,
                  Verse second)

      Determine the earlier of the two verses. If first == second then return first.
      Parameters:
        `first` - the first verse to compare
        `second` - the second verse to compare
      Returns:
        The earlier of the two verses

    - #### max

          public Verse max(Verse first,
                  Verse second)

      Determine the later of the two verses. If first == second then return first.
      Parameters:
        `first` - the first verse to compare
        `second` - the second verse to compare
      Returns:
        The later of the two verses

    - #### subtract

          public Verse subtract(Verse verse,
                       int n)

      Get the verse n down from here this Verse.
      Parameters:
        `verse` - The verse to use as a start
        `n` - The number to count down by
      Returns:
        The new Verse

    - #### next

          public Verse next(Verse verse)

      Get the verse that is a verses on from the one we've got.
      Parameters:
        `verse` - The verse to use as a start
      Returns:
        The new verse or null if there is no next verse

    - #### add

          public Verse add(Verse verse,
                  int n)

      Get the verse that is a few verses on from the one we've got.
      Parameters:
        `verse` - The verse to use as a start
        `n` - the number of verses later than the one we're one
      Returns:
        The new verse

    - #### getChapterCount

          public int getChapterCount(Verse start,
                            Verse end)

      The number of chapters between two verses includes the chapters of the two verses and everything in between.
      Parameters:
        `start` - The first Verse in the range
        `end` - The last Verse in the range
      Returns:
        The number of chapters. Always >= 1.

    - #### maximumOrdinal

          public int maximumOrdinal()

      The maximum number of verses in the Bible, including module, testament, book and chapter introductions.
      Returns:
        the number of addressable verses in this versification.

    - #### getOrdinal

          public int getOrdinal(Verse verse)

      Where does this verse come in the Bible. The value that this returns should be treated as opaque, useful for a bit set. The introductions to the Book, OT/NT Testaments, Bible books and chapters are included here.
      - 0 - INTRO_BIBLE 0:0 - The Book introduction
      - 1 - INTRO_OT 0:0 - The OT Testament introduction
      - 2 - Gen 0:0 - The introduction to the book of Genesis
      - 3 - Gen 1:0 - The introduction to Genesis chapter 1
      - 4 - Gen 1:1
      - ...
      - 35 - Gen 1:31
      - 36 - Gen 2:0 - The introduction to Genesis chapter 2
      - 37 - Gen 2:1
      - ...
      - n - last verse in the OT
      - n + 1 - INTRO_NT, 0, 0 - The New Testament introduction
      - n + 2 - Matt 0:0 - The introduction to Matt
      - n + 3 - Matt 1:0 - The introduction to Matt 1
      - n + 4 - Matt 1:1
      - ...
      If the verse is not in this versification, return 0.
      Parameters:
        `verse` - The verse to convert
      Returns:
        The ordinal number of verses

    - #### getOrdinal

          public int getOrdinal(Testament testament,
                       int testamentOrdinal)

      Determine the ordinal value for this versification given the ordinal value in a testament. If the ordinal is out of bounds it is constrained to be within the boundaries of the testament. This unwinds getTestamentOrdinal.
      Parameters:
        `testament` - the testament in which the ordinal value pertains
        `testamentOrdinal` - the ordinal value within the testament
      Returns:
        the ordinal value for the versification as a whole

    - #### getTestamentOrdinal

          public int getTestamentOrdinal(int ordinal)

      Where does this verse come in the Bible. The value that this returns should be treated as opaque, useful for a bit set. The introductions to the Book, OT/NT Testaments, Bible books and chapters are included here.
      - 0 - INTRO_BIBLE 0:0 - The Book introduction
      - 1 - INTRO_OT 0:0 - The OT Testament introduction
      - 2 - Gen 0:0 - The introduction to the book of Genesis
      - 3 - Gen 1:0 - The introduction to Genesis chapter 1
      - 4 - Gen 1:1
      - ...
      - 35 - Gen 1:31
      - 36 - Gen 2:0 - The introduction to Genesis chapter 2
      - 37 - Genesis 2:1
      - ...
      - n - last verse in the OT
      - 0 - INTRO_NT, 0, 0 - The New Testament introduction
      - 1 - Matt 0:0 - The introduction to Matt
      - 2 - Matt 1:0 - The introduction to Matt 1
      - 3 - Matt 1:1
      - ...
      Parameters:
        `ordinal` - The ordinal number of the verse to convert
      Returns:
        The ordinal number of the Verse within its Testament

    - #### getTestament

          public Testament getTestament(int ordinal)

      Get the testament of a given verse
      Parameters:
        `ordinal` - the ordinal position of the verse in the whole Bible
      Returns:
        the testament in which that verse is found

    - #### getCount

          public int getCount(Testament testament)

      Give the count of verses in the testament or the whole Bible.
      Parameters:
        `testament` - The testament to count. If null, then all testaments.
      Returns:
        the number of verses in the testament

    - #### decodeOrdinal

          public Verse decodeOrdinal(int ordinal)

      Where does this verse come in the Bible. This will unwind the value returned by getOrdinal(Verse). If the ordinal value is less than 0 or greater than the last verse in this Versification, then constrain it to the first or last verse in this Versification.
      Parameters:
        `ordinal` - The ordinal number of the verse
      Returns:
        A Verse

    - #### validate

          public void validate(BibleBook book,
                      int chapter,
                      int verse)
                        throws NoSuchVerseException

      Does the following represent a real verse?. It is code like this that makes me wonder if I18 is done well/worth doing. All this code does is check if the numbers are valid, but the exception handling code is huge :(
      Parameters:
        `book` - The book part of the reference.
        `chapter` - The chapter part of the reference.
        `verse` - The verse part of the reference.
      Throws:
        `NoSuchVerseException` - If the reference is illegal

    - #### validate

          public boolean validate(BibleBook book,
                         int chapter,
                         int verse,
                         boolean silent)
                           throws NoSuchVerseException

      Does the following represent a real verse?. It is code like this that makes me wonder if I18 is done well/worth doing. All this code does is check if the numbers are valid, but the exception handling code is huge :(
      Parameters:
        `book` - The book part of the reference.
        `chapter` - The chapter part of the reference.
        `verse` - The verse part of the reference.
        `silent` - true to indicate we do not want to throw an exception
      Returns:
        true if validation was succesful
      Throws:
        `NoSuchVerseException` - If the reference is illegal and silent was false

    - #### patch

          public Verse patch(BibleBook book,
                    int chapter,
                    int verse)

      Fix up these verses so that they are as valid a possible. This is currently done so that we can say "Gen 1:1" + 31 = "Gen 1:32" and "Gen 1:32".patch() is "Gen 2:1".

      There is another patch system that allows us to use large numbers to mean "the end of" so "Gen 1:32".otherPatch() gives "Gen 1:31". This could be useful to allow the user to enter things like "Gen 1:99" meaning the end of the chapter. Or "Isa 99:1" to mean the last chapter in Isaiah verse 1 or even "Rev 99:99" to mean the last verse in the Bible.

      However I have not implemented this because I've used a different convention: "Gen 1:$" (OLB compatible) or "Gen 1:ff" (common commentary usage) to mean the end of the chapter - So the functionality is there anyway.

      I think that getting into the habit of typing "Gen 1:99" is bad. It could be the source of surprises "Psa 119:99" is not what you'd might expect, and neither is "Psa 99:1" is you wanted the last chapter in Psalms - expecting us to type "Psa 999:1" seems like we're getting silly.

      However despite this maybe we should provide the functionality anyway.

      Parameters:
        `book` - the book to obtain
        `chapter` - the supposed chapter
        `verse` - the supposed verse
      Returns:
        The resultant verse.

    - #### dump

          public static void dump(PrintStream out,
                  String name,
                  BibleBookList bookList,
                  int[][] array)

    - #### optimize

          public static void optimize(PrintStream out,
                      BibleBookList bookList,
                      int[][] lastVerse)