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

hlt.language.util

## Class SetOf

- java.lang.Object
- - hlt.language.util.SetOf

-     public class SetOf
      extends java.lang.Object

  This class is a generic data type for sets of objects. Instances of this class denote subsets of a fixed reference set - an `AbstractList` of Objects - called the base structure. All sets operations are implemented efficiently using an underlying bitset representation. In effect, using this class alleviates the need to deal directly with the represention and always manipulate sets as implicit collections of objects.

  This package also defines classes for iterating through `SetOf` objects: an `Enumeration` class (`SetEnumeration`) an `IndexEnumeration` class (`SetIndices`), and an `Iterator` class (`SetIterator`).

  NB: There are some caveats to be aware of when using `SetOf`:

  - this class will work correctly assuming that no element is ever removed from the base structure;
  - for efficiency reasons, no check is made that the base structure is indeed a set (i.e., contains no duplicates);
  Version:
    Last modified on Fri Oct 19 17:36:25 2012 by hak
  Author:
    Hassan Aït-Kaci
  See Also:
    `SetEnumeration`, `SetIndices`, `SetIterator`
  Copyright:
    © Hassan Aït-Kaci

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SetOf(java.util.AbstractList base)` Constructs a new (empty) set with the specified AbstractList base.
    `SetOf(java.util.AbstractList base, java.util.BitSet carrier)` Constructs a new set with the specified base and underlying bitset representation.
    `SetOf(java.util.AbstractList base, int index)` Constructs a new singleton set containing the single specified index with the specified AbstractList base.
    `SetOf(java.util.AbstractList base, java.lang.Object object)` Constructs a new singleton set containing the single specified object with the specified AbstractList base.
    `SetOf(java.lang.Object[] base)` Constructs a new (empty) set with the specified array base.
    `SetOf(java.lang.Object[] base, java.util.BitSet carrier)` Constructs a new set with the specified base and underlying bitset representation.
    `SetOf(java.lang.Object[] base, boolean synchronize)` Constructs a new (empty) set with the specified array base, which is built as a `Vector` if `synchronize` is `true`, or as an `ArrayList` otherwise.
    `SetOf(java.lang.Object[] base, int index)` Constructs a new singleton set containing the single specified index with the specified array base.
    `SetOf(java.lang.Object[] base, java.lang.Object object)` Constructs a new singleton set containing the single specified object with the specified array base.
    `SetOf(SetOf set)` Constructs a copy of the specified set.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `SetOf` | `add(int index)` Adds the element of specified index into this set.
    `SetOf` | `add(java.lang.Object object)` Adds a specified object into this set.
    `static SetOf` | `add(SetOf s, int index)` Returns a new set obtained from the given set after adding the given index.
    `boolean` | `contains(int index)` Returns true iff the specified index is that of an element of this set.
    `boolean` | `contains(java.lang.Object object)` Returns true iff the specified object is an element of this set.
    `java.util.Enumeration` | `elements()` Returns an Enumeration over the object elements of this set.
    `boolean` | `equals(java.lang.Object other)` Returns true iff the specified object is a set equal to this.
    `java.lang.Object` | `firstElement()` Returns the first element in this set.
    `int` | `firstIndex()` Returns the base index of the first element in this set.
    `int` | `hashCode()` Returns a hashcode for this set.
    `int` | `indexOf(java.lang.Object object)` Returns the index of a specified object element of this set.
    `IndexEnumeration` | `indices()` Returns an enumeration-like object over the base structure's indices for the elements of this set.
    `SetOf` | `intersection(SetOf other)` Modifies this set to the intersection of this set and the specified set.
    `static SetOf` | `intersection(SetOf s1, SetOf s2)` Returns the intersection of two sets without modifying either one.
    `boolean` | `isEmpty()` Returns true iff this set is empty.
    `boolean` | `isEqualTo(SetOf other)` Returns true iff this set is equal to the specified set.
    `boolean` | `isFull()` Returns true iff this set contains all the base structure's elements.
    `boolean` | `isStrictSubsetOf(SetOf other)` Returns true iff this set is strictly included in the specified set.
    `boolean` | `isSubsetOf(SetOf other)` Returns true iff this set is included in or equal to the specified set.
    `java.util.Iterator` | `iterator()` Returns an Iterator over the object elements of this set.
    `SetOf` | `minus(SetOf other)` Modifies this set to the difference of this set and the specified set.
    `static SetOf` | `minus(SetOf s1, SetOf s2)` Returns the difference of two sets without modifying either one.
    `SetOf` | `not()` Modifies this set to its complement (relative to the base).
    `static SetOf` | `not(SetOf s)` Returns the complement (relative to the base) of the specified set without modifying it.
    `SetOf` | `remove(int index)` Removes the element of specified index from this set.
    `SetOf` | `remove(java.lang.Object object)` Removes the specified object from this set.
    `static SetOf` | `remove(SetOf s, int index)` Returns a new set obtained from the given set after removing the given index.
    `int` | `size()` Returns the number of elements in this set.
    `java.lang.String` | `toBitString()` Returns a string representation of this set as a bit string of 0's and 1's.
    `java.lang.String` | `toBitString(char out, char in)` Returns a string representation of this set as a bit string of two specified characters standing for "absent" and "present" respectively.
    `SetOf` | `top()` Returns a set representing the reference set; that is, a set containing all the base structure's elements.
    `java.lang.String` | `toString()` Returns a string representation of this set as a comma-separated list of elements between curly braces.
    `SetOf` | `union(SetOf other)` Modifies this set to the union of this set and the specified set.
    `static SetOf` | `union(SetOf s1, SetOf s2)` Returns the union of two sets without modifying either one.

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

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

- - ### Constructor Detail

    - #### SetOf

          public SetOf(java.lang.Object[] base,
               boolean synchronize)

      Constructs a new (empty) set with the specified array base, which is built as a `Vector` if `synchronize` is `true`, or as an `ArrayList` otherwise.
      Parameters:
        `base` - the reference set as an array
        `synchronize` - if `true`, the base structure is synchronized

    - #### SetOf

          public SetOf(java.lang.Object[] base)

      Constructs a new (empty) set with the specified array base. NB: the concrete base structure used is an `ArrayList` - that is, it is unsynchronized. For a synchronized base, use `SetOf(Object[],true)`.
      Parameters:
        `base` - the reference set as an array

    - #### SetOf

          public SetOf(java.util.AbstractList base)

      Constructs a new (empty) set with the specified AbstractList base.
      Parameters:
        `base` - the reference set as an AbstractList.

    - #### SetOf

          public SetOf(java.util.AbstractList base,
               int index)

      Constructs a new singleton set containing the single specified index with the specified AbstractList base.
      Parameters:
        `base` - the reference set as a AbstractList
        `index` - the index of the object

    - #### SetOf

          public SetOf(java.lang.Object[] base,
               int index)

      Constructs a new singleton set containing the single specified index with the specified array base.
      Parameters:
        `base` - the reference set as an array
        `index` - the index of the object

    - #### SetOf

          public SetOf(java.util.AbstractList base,
               java.lang.Object object)

      Constructs a new singleton set containing the single specified object with the specified AbstractList base.
      Parameters:
        `base` - the reference set as a AbstractList
        `object` - the object

    - #### SetOf

          public SetOf(java.lang.Object[] base,
               java.lang.Object object)

      Constructs a new singleton set containing the single specified object with the specified array base.
      Parameters:
        `base` - the reference set as an array
        `object` - the object

    - #### SetOf

          public SetOf(SetOf set)

      Constructs a copy of the specified set.
      Parameters:
        `set` - the set to copy

    - #### SetOf

          public SetOf(java.lang.Object[] base,
               java.util.BitSet carrier)

      Constructs a new set with the specified base and underlying bitset representation.
      Parameters:
        `base` - the reference set as an array
        `carrier` - the bitset representation

    - #### SetOf

          public SetOf(java.util.AbstractList base,
               java.util.BitSet carrier)

      Constructs a new set with the specified base and underlying bitset representation.
      Parameters:
        `base` - the reference set as a AbstractList
        `carrier` - the bitset representation

  - ### Method Detail

    - #### size

          public final int size()

      Returns the number of elements in this set.

    - #### top

          public final SetOf top()

      Returns a set representing the reference set; that is, a set containing all the base structure's elements.

    - #### isFull

          public final boolean isFull()

      Returns true iff this set contains all the base structure's elements.

    - #### isEmpty

          public final boolean isEmpty()

      Returns true iff this set is empty.

    - #### indexOf

          public final int indexOf(java.lang.Object object)

      Returns the index of a specified object element of this set.
      Parameters:
        `object` - the object
      Returns:
        the desired index or -1 if the object is not there

    - #### add

          public final SetOf add(int index)

      Adds the element of specified index into this set.
      Parameters:
        `index` - the index
      Returns:
        this set

    - #### add

          public final SetOf add(java.lang.Object object)

      Adds a specified object into this set.
      Parameters:
        `object` - the object
      Returns:
        this set

    - #### add

          public static final SetOf add(SetOf s,
                  int index)

      Returns a new set obtained from the given set after adding the given index.
      Parameters:
        `s` - a set
        `index` - the index
      Returns:
        a new set which is s with the object at index added

    - #### remove

          public final SetOf remove(int index)

      Removes the element of specified index from this set.
      Parameters:
        `index` - the index
      Returns:
        this set

    - #### remove

          public final SetOf remove(java.lang.Object object)

      Removes the specified object from this set.
      Parameters:
        `object` - the object
      Returns:
        this set

    - #### remove

          public static final SetOf remove(SetOf s,
                     int index)

      Returns a new set obtained from the given set after removing the given index.
      Parameters:
        `s` - a set
        `index` - the index
      Returns:
        a new set which is s deprived of the object at index

    - #### firstIndex

          public final int firstIndex()

      Returns the base index of the first element in this set.
      Returns:
        the desired index or -1 if empty.

    - #### firstElement

          public final java.lang.Object firstElement()

      Returns the first element in this set.
      Returns:
        the desired element or null if empty.

    - #### union

          public final SetOf union(SetOf other)

      Modifies this set to the union of this set and the specified set.
      Parameters:
        `other` - a set
      Returns:
        this set

    - #### union

          public static final SetOf union(SetOf s1,
                    SetOf s2)

      Returns the union of two sets without modifying either one.
      Parameters:
        `s1` - a set
        `s2` - a set
      Returns:
        a new set which is the union of s1 and s2

    - #### intersection

          public final SetOf intersection(SetOf other)

      Modifies this set to the intersection of this set and the specified set.
      Parameters:
        `other` - a set
      Returns:
        this set

    - #### intersection

          public static final SetOf intersection(SetOf s1,
                           SetOf s2)

      Returns the intersection of two sets without modifying either one.
      Parameters:
        `s1` - a set
        `s2` - a set
      Returns:
        a new set which is the intersection of s1 and s2

    - #### minus

          public final SetOf minus(SetOf other)

      Modifies this set to the difference of this set and the specified set.
      Parameters:
        `other` - a set
      Returns:
        this set

    - #### minus

          public static final SetOf minus(SetOf s1,
                    SetOf s2)

      Returns the difference of two sets without modifying either one.
      Parameters:
        `s1` - a set
        `s2` - a set
      Returns:
        a new set which is the difference of s1 and s2

    - #### not

          public final SetOf not()

      Modifies this set to its complement (relative to the base).
      Returns:
        this set

    - #### not

          public static final SetOf not(SetOf s)

      Returns the complement (relative to the base) of the specified set without modifying it.
      Parameters:
        `s` - a set

    - #### contains

          public final boolean contains(int index)

      Returns true iff the specified index is that of an element of this set.
      Parameters:
        `index` - the index

    - #### contains

          public final boolean contains(java.lang.Object object)

      Returns true iff the specified object is an element of this set.
      Parameters:
        `object` - the object

    - #### isSubsetOf

          public final boolean isSubsetOf(SetOf other)

      Returns true iff this set is included in or equal to the specified set.
      Parameters:
        `other` - a set

    - #### isStrictSubsetOf

          public final boolean isStrictSubsetOf(SetOf other)

      Returns true iff this set is strictly included in the specified set.
      Parameters:
        `other` - a set

    - #### isEqualTo

          public final boolean isEqualTo(SetOf other)

      Returns true iff this set is equal to the specified set.
      Parameters:
        `other` - a set

    - #### equals

          public final boolean equals(java.lang.Object other)

      Returns true iff the specified object is a set equal to this.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `other` - an object

    - #### hashCode

          public final int hashCode()

      Returns a hashcode for this set.
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public final java.lang.String toString()

      Returns a string representation of this set as a comma-separated list of elements between curly braces.
      Overrides:
        `toString` in class `java.lang.Object`

    - #### toBitString

          public final java.lang.String toBitString()

      Returns a string representation of this set as a bit string of 0's and 1's.

    - #### toBitString

          public final java.lang.String toBitString(char out,
                                     char in)

      Returns a string representation of this set as a bit string of two specified characters standing for "absent" and "present" respectively.
      Parameters:
        `out` - a character
        `in` - a character

    - #### elements

          public final java.util.Enumeration elements()

      Returns an Enumeration over the object elements of this set.

    - #### iterator

          public final java.util.Iterator iterator()

      Returns an Iterator over the object elements of this set.

    - #### indices

          public final IndexEnumeration indices()

      Returns an enumeration-like object over the base structure's indices for the elements of this set.