org.crosswire.jsword.passage

## Class BitwisePassage

- java.lang.Object
- - org.crosswire.jsword.passage.AbstractPassage
  - - org.crosswire.jsword.passage.BitwisePassage

- All Implemented Interfaces:
    Serializable, Cloneable, Comparable<Key>, Iterable<Key>, Key, Passage, VerseKey<Passage>
  Direct Known Subclasses:
    RocketPassage

      public class BitwisePassage
      extends AbstractPassage

  A Passage that is implemented using a BitSet - one for each verse. The attributes of the style are:
  - Fairly fast manipulation
  - Fairly getName()
  - Static size, poor for small Passages, good for large Passages

  The BitSet has one more bit than the number of verses in the Bible. This would waste 1 bit per BitSet but since this doesn't cause BitSet to need an extra long it doesn't, and it saves us some maths.

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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private class` | `BitwisePassage.VerseIterator` Iterate over the Verses

    - ### Nested classes/interfaces inherited from class org.crosswire.jsword.passage.AbstractPassage

      `AbstractPassage.VerseRangeIterator`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static long` | `serialVersionUID` To make serialization work across new versions
    `protected BitSet` | `store` The place the real data is stored

    - ### Fields inherited from class org.crosswire.jsword.passage.AbstractPassage

      `BITWISE, DISTINCT, listeners, METHOD_COUNT, originalName, RANGED, REF_ALLOWED_DELIMS, REF_OSIS_DELIM, REF_PREF_DELIM, skipNormalization, suppressEvents`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `BitwisePassage(Versification v11n)` Create an empty BitwisePassage.
    `protected` | `BitwisePassage(Versification v11n, String refs)` Create a Verse from a human readable string.
    `protected` | `BitwisePassage(Versification v11n, String refs, Key basis)` Create a Verse from a human readable string.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(Key obj)` Add this Verse/VerseRange to this Passage
    `void` | `addAll(Key key)` Adds the specified element to this set if it is not already present.
    `void` | `addVersifiedOrdinal(int ordinal)` A shortcut to adding a key, by ordinal.
    `void` | `blur(int verses, RestrictionType restrict)` Widen the range of the verses/keys in this list.
    `void` | `clear()` Removes all of the elements from this set (optional operation).
    `BitwisePassage` | `clone()` This needs to be declared here so that it is visible as a method on a derived Key.
    `boolean` | `contains(Key obj)` Returns true if this collection contains all the specified Verse
    `int` | `countVerses()` Returns the number of verses in this collection.
    `boolean` | `isEmpty()` Does this Key have 0 members
    `Iterator<Key>` | `iterator()`
    `private void` | `readObject(ObjectInputStream in)` Call the support mechanism in AbstractPassage
    `void` | `remove(Key obj)` Remove this Verse/VerseRange from this Passage
    `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.
    `private void` | `writeObject(ObjectOutputStream out)` Call the support mechanism in AbstractPassage

    - ### Methods inherited from class org.crosswire.jsword.passage.AbstractPassage

      `addPassageListener, addVerses, booksInPassage, canHaveChildren, compareTo, containsAll, countRanges, equals, fireContentsChanged, fireIntervalAdded, fireIntervalRemoved, get, getCardinality, getChildCount, getName, getName, getOsisID, getOsisRef, getOverview, getParent, getRangeAt, getRootName, getVerseAt, getVersification, getWhole, hashCode, hasRanges, indexOf, isWhole, lowerEventSuppressionAndTest, lowerNormalizeProtection, normalize, optimizeReads, optimizeWrites, raiseEventSuppresion, raiseNormalizeProtection, rangeIterator, readDescription, readObjectSupport, removePassageListener, reversify, setParent, toString, toVerseRange, trimRanges, trimVerses, writeDescription, writeObjectSupport`

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

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### serialVersionUID

          private static final long serialVersionUID

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

    - #### store

          protected transient BitSet store

      The place the real data is stored

  - ### Constructor Detail

    - #### BitwisePassage

          public BitwisePassage(Versification v11n)

      Create an empty BitwisePassage. There are no ctors from either Verse or VerseRange so you need to do new `DistinctPassage().add(...);`
      Parameters:
        `v11n` - The Versification to which this Passage belongs.

    - #### BitwisePassage

          protected BitwisePassage(Versification v11n,
                        String refs,
                        Key basis)
                            throws NoSuchVerseException

      Create a Verse from a human readable string. The opposite of toString(), Given any BitwisePassage v1, and the following `DistinctPassage v2 = new BitwisePassage(v1.toString());` Then `v1.equals(v2);` Theoretically, since there are many ways of representing a BitwisePassage as text string comparison along the lines of: `v1.toString().equals(v2.toString())` could be false. Practically since toString() is standardized this will be true however. We don't need to worry about thread safety in a ctor since we don't exist yet.
      Parameters:
        `v11n` - The Versification to which this Passage belongs.
        `refs` - A String containing the text of the BitwisePassage
        `basis` - The basis by which to interpret refs
      Throws:
        `NoSuchVerseException` - If the string is not parsable

    - #### BitwisePassage

          protected BitwisePassage(Versification v11n,
                        String refs)
                            throws NoSuchVerseException

      Create a Verse from a human readable string. The opposite of toString(), Given any BitwisePassage v1, and the following `DistinctPassage v2 = new BitwisePassage(v1.toString());` Then `v1.equals(v2);` Theoretically, since there are many ways of representing a BitwisePassage as text string comparison along the lines of: `v1.toString().equals(v2.toString())` could be false. Practically since toString() is standardized this will be true however. We don't need to worry about thread safety in a ctor since we don't exist yet.
      Parameters:
        `v11n` - The Versification to which this Passage belongs.
        `refs` - A String containing the text of the BitwisePassage
      Throws:
        `NoSuchVerseException` - If the string is not parsable

  - ### Method Detail

    - #### clone

          public BitwisePassage 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 `AbstractPassage`
      Returns:
        A complete copy of ourselves

    - #### countVerses

          public int countVerses()

      Description copied from interface: `Passage`
      Returns the number of verses in this collection. Like Collection.size() This does not mean the Passage needs to use Verses, just that it understands the concept.
      Specified by:
        `countVerses` in interface `Passage`
      Overrides:
        `countVerses` in class `AbstractPassage`
      Returns:
        the number of Verses in this collection
      See Also:
        `Verse`

    - #### isEmpty

          public boolean isEmpty()

      Description copied from interface: `Key`
      Does this Key have 0 members
      Specified by:
        `isEmpty` in interface `Key`
      Overrides:
        `isEmpty` in class `AbstractPassage`
      Returns:
        `true` if this set contains no elements.

    - #### iterator

          public Iterator<Key> iterator()

    - #### contains

          public boolean contains(Key obj)

      Description copied from interface: `Passage`
      Returns true if this collection contains all the specified Verse
      Specified by:
        `contains` in interface `Key`
      Specified by:
        `contains` in interface `Passage`
      Overrides:
        `contains` in class `AbstractPassage`
      Parameters:
        `obj` - Verse or VerseRange that may exist in this Passage
      Returns:
        true if this collection contains that

    - #### add

          public void add(Key obj)

      Description copied from interface: `Passage`
      Add this Verse/VerseRange to this Passage
      Parameters:
        `obj` - The Verses to be added from this Passage

    - #### addVersifiedOrdinal

          public void addVersifiedOrdinal(int ordinal)

      A shortcut to adding a key, by ordinal. The ordinal needs to be taken from the same versification as the passage being created.
      Parameters:
        `ordinal` - the ordinal

    - #### remove

          public void remove(Key obj)

      Description copied from interface: `Passage`
      Remove this Verse/VerseRange from this Passage
      Parameters:
        `obj` - The Verses to be removed from this Passage

    - #### 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`
      Overrides:
        `addAll` in class `AbstractPassage`
      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`
      Overrides:
        `removeAll` in class `AbstractPassage`
      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`
      Overrides:
        `retainAll` in class `AbstractPassage`
      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`
      Overrides:
        `clear` in class `AbstractPassage`

    - #### blur

          public void blur(int verses,
                  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`
      Overrides:
        `blur` in class `AbstractPassage`
      Parameters:
        `verses` - The number of verses/keys to widen by
        `restrict` - How should we restrict the blurring?
      See Also:
        `Passage`

    - #### writeObject

          private void writeObject(ObjectOutputStream out)
                            throws IOException

      Call the support mechanism in AbstractPassage
      Parameters:
        `out` - The stream to write our state to
      Throws:
        `IOException` - if the read fails
      See Also:
        `AbstractPassage.writeObjectSupport(ObjectOutputStream)`

    - #### readObject

          private void readObject(ObjectInputStream in)
                           throws IOException,
                                  ClassNotFoundException

      Call the support mechanism in AbstractPassage
      Parameters:
        `in` - The stream to read our state from
      Throws:
        `IOException` - if the read fails
        `ClassNotFoundException` - If the read data is incorrect
      See Also:
        `AbstractPassage.readObjectSupport(ObjectInputStream)`