BitCode (API documentation of hlt.language packages)
Date: 2013-01-30

hlt.osf.util

## Class BitCode

- java.lang.Object
- - java.util.BitSet
  - - hlt.osf.util.BitCode

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable

      public class BitCode
      extends java.util.BitSet

  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `BitCode()` Constructs a new bit code; (all bits set to `false`).
    `BitCode(int nbits)` Constructs a new bit code whose initial size is large enough to explicitly represent bits with indices in the range `0` through `nbits-1`; (all bits set to false).

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `BitCode` | `add(int index)` Adds the specified index to this BitCode (i.e., it sets it to true), and returns this BitCode.
    `static BitCode` | `and(BitCode c1, BitCode c2)` Returns a bit code that is the logical `and` of its arguments, which are left unchanged if locked.
    `BitCode` | `copy()` Returns a new unlocked BitCode that is an equal copy of this one.
    `BitCode` | `erase()` Removes all the true bits from this BitCode (i.e., all set to false), and returns this BitCode.
    `boolean` | `isContainedIn(BitCode code)` Returns true iff the set of set bits in this code is contained in that of the specified code.
    `boolean` | `isLocked()` Returns true iff this bit code is locked - which means that it will not be modified by the 3 boolean static dyadic operations 'not', 'and', and 'or' defined below.
    `boolean` | `isStrictlyContainedIn(BitCode code)` Returns true iff this code is strictly contained in the specified code.
    `boolean` | `isUnrelatedTo(BitCode code)` Returns true iff this code is unrelated to the specified code.
    `IntIterator` | `iterator()`
    `BitCode` | `lock()` Locks this bit code - which means that it will not be modified by the 3 boolean static dyadic operations 'not', 'and', and 'or' defined below.
    `static BitCode` | `not(BitCode c)` Returns a bit code that is the logical `not` of its bit code argument up to the sort code size.
    `static BitCode` | `or(BitCode c1, BitCode c2)` Returns a bit code that is the logical `or` of its arguments, which are left unchanged if locked.
    `BitCode` | `remove(int index)` Removes the specified index from this BitCode (i.e., it sets it to false), and returns this BitCode.
    `static void` | `setOffChar(char c)` This sets the "not set" character when displaying this as a string to the specified character.
    `static void` | `setOnChar(char c)` This sets the "set" character when displaying this as a string to the specified character.
    `java.lang.String` | `toBitString()` Returns this bit code of length equal to the sort code size as a string of ON and OFF characters (which default to 0 and 1).
    `java.lang.String` | `toString()` Returns this bit code as a bit string followed by a marker whether it is locked or not.
    `BitCode` | `unlock()` Unlocks this bit code - which means that it may be modified by the 3 boolean static dyadic operations 'not', 'and', and 'or' defined below.

    - ### Methods inherited from class java.util.BitSet

      `and, andNot, cardinality, clear, clear, clear, clone, equals, flip, flip, get, get, hashCode, intersects, isEmpty, length, nextClearBit, nextSetBit, or, previousClearBit, previousSetBit, set, set, set, set, size, toByteArray, toLongArray, valueOf, valueOf, valueOf, valueOf, xor`

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

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

- - ### Constructor Detail

    - #### BitCode

          public BitCode()

      Constructs a new bit code; (all bits set to `false`).

    - #### BitCode

          public BitCode(int nbits)

      Constructs a new bit code whose initial size is large enough to explicitly represent bits with indices in the range `0` through `nbits-1`; (all bits set to false).
      Parameters:
        `nbits` - the initial capacity of the bit code.

  - ### Method Detail

    - #### setOnChar

          public static void setOnChar(char c)

      This sets the "set" character when displaying this as a string to the specified character.

    - #### setOffChar

          public static void setOffChar(char c)

      This sets the "not set" character when displaying this as a string to the specified character.

    - #### isContainedIn

          public boolean isContainedIn(BitCode code)

      Returns true iff the set of set bits in this code is contained in that of the specified code. That is, iff `(this and code) == this`.

    - #### isStrictlyContainedIn

          public boolean isStrictlyContainedIn(BitCode code)

      Returns true iff this code is strictly contained in the specified code.

    - #### isUnrelatedTo

          public boolean isUnrelatedTo(BitCode code)

      Returns true iff this code is unrelated to the specified code.

    - #### isLocked

          public boolean isLocked()

      Returns true iff this bit code is locked - which means that it will not be modified by the 3 boolean static dyadic operations 'not', 'and', and 'or' defined below.

    - #### lock

          public BitCode lock()

      Locks this bit code - which means that it will not be modified by the 3 boolean static dyadic operations 'not', 'and', and 'or' defined below.

    - #### unlock

          public BitCode unlock()

      Unlocks this bit code - which means that it may be modified by the 3 boolean static dyadic operations 'not', 'and', and 'or' defined below.

    - #### add

          public BitCode add(int index)
                      throws LockedBitCodeException

      Adds the specified index to this BitCode (i.e., it sets it to true), and returns this BitCode.
      Throws:
        `LockedBitCodeException`

    - #### remove

          public BitCode remove(int index)
                         throws LockedBitCodeException

      Removes the specified index from this BitCode (i.e., it sets it to false), and returns this BitCode.
      Throws:
        `LockedBitCodeException`

    - #### erase

          public BitCode erase()
                        throws LockedBitCodeException

      Removes all the true bits from this BitCode (i.e., all set to false), and returns this BitCode.
      Throws:
        `LockedBitCodeException`

    - #### not

          public static BitCode not(BitCode c)

      Returns a bit code that is the logical `not` of its bit code argument up to the sort code size. The bit code argument is left unchanged if locked. If the bit code argument is not locked, the returned bit code is the argument modified in place. Otherwise, a new bit code is returned with its bits set to their appropriate values.

    - #### and

          public static BitCode and(BitCode c1,
                    BitCode c2)

      Returns a bit code that is the logical `and` of its arguments, which are left unchanged if locked. If the first argument is not locked, the returned bit code is the first argument modified in place. Otherwise, if the second argument is not locked, the returned bit code is the second argument modified in place. Otherwise, a new bit code is returned with its bits set to their appropriate values.

    - #### or

          public static BitCode or(BitCode c1,
                   BitCode c2)

      Returns a bit code that is the logical `or` of its arguments, which are left unchanged if locked. If the first argument is not locked, the returned bit code is the first argument modified in place. Otherwise, if the second argument is not locked, the returned bit code is the second argument modified in place. Otherwise, a new bit code is returned with its bits set to their appropriate values.

    - #### copy

          public BitCode copy()

      Returns a new unlocked BitCode that is an equal copy of this one.

    - #### toBitString

          public java.lang.String toBitString()

      Returns this bit code of length equal to the sort code size as a string of ON and OFF characters (which default to 0 and 1). All bits at index higher or equal to that size are always false. These can be set to different characters using the static methods setOnChar and setOffChar.

    - #### toString

          public java.lang.String toString()

      Returns this bit code as a bit string followed by a marker whether it is locked or not.
      Overrides:
        `toString` in class `java.util.BitSet`

    - #### iterator

          public IntIterator iterator()