org.abora.white.collection.sets
Class ScruSet

java.lang.Object
  |
  +--org.abora.white.xpp.basic.Heaper
        |
        +--org.abora.white.collection.sets.ScruSet

Direct Known Subclasses:

ImmuSet, MuSet

public abstract class ScruSet

extends Heaper

X++ has three basic kinds of collection classes. Tables, Sets and XuRegions. XuRegions are not-necessarily-discrete collections of positions, and are documented in the space module. Sets and Tables are both discrete and finite, and similar in many ways. Both originate in a three-way type distinction between:

• ScruX -- The protocol for examining one. I.e., it is *Scru*table
• ImmuX -- The contract guarantees that the set or table you''re looking at won't change (though the things it contains may change)
• MuX -- Additional protocol for changing it.

Concrete classes may be a subclass of any of the above. It makes sense to have a concrete subclass of ScruX which isn''t a subclass of either MuX or ImmuX when, for example, it represents a tracking, filtered view of some other set which is itself changing. All kinds of collection can be iterated over when appropriate using Steppers--our basic iteration abstraction (see Stepper).

Immu's are sort of like Stamps -- they represent a particular state a colection can have.

Mu's are sort of like Berts -- they represent a continuing collection identity which can change its current state.

Sets are pure collections--their contents are just a set of Heapers. Sets (as opposed to tables) do not provide any organization of these contents.

Constructor Summary

protected	ScruSet()
protected	ScruSet(Rcvr rcvr)

Method Summary

int	actualHashForEqual() Defined by subclasses to produce the value returned by hashForEqual.
PtrArray	asArray() The elements in the set in an array, in some random order
abstract ImmuSet	asImmuSet() Return an immu snapshot of my current state.
abstract MuSet	asMuSet() Return a Mu whose initial state is the same as my current state, but which will now deviate independently of me.
boolean	contentsEqual(ScruSet other) Returns whether the two ScruSets have exactly the same set of elements at the moment.
int	contentsHash() Has the same relationship to contentsEqual that hashForEqual has to isEqual.
abstract ScruSet	copy() A new one whose initial state is my current state, but that doesn't track changes.
abstract IntegerValue	count() How many elements are currently in the set.
abstract boolean	hasMember(Heaper someone) Is someone a member of the set now?
boolean	intersects(ScruSet other) Return true if this set and the other set have any elements in common.
abstract boolean	isEmpty() Return true if this set does not currently have any elements.
abstract boolean	isEqual(Heaper other) Return true if the two objects are equal.
boolean	isSubsetOf(ScruSet another) Whether another currently has all my elements
void	printOn(java.io.PrintWriter oo) This should rarely be overridden.
void	printOnWithSimpleSyntax(java.io.PrintWriter oo, java.lang.String open, java.lang.String sep, java.lang.String close)
void	printOnWithSyntax(java.io.PrintWriter oo, java.lang.String openMarker, java.lang.String separator, java.lang.String closeMarker, boolean fullPrint) For example, if we have the set '{a, b, c}' and we print it with 'p->printOnWithSyntax(oo,
abstract Stepper	stepper() Returns a stepper which will enumerate all the elements of the set in some unspecified order
Heaper	theOne() Iff I contain exactly one member, return it.

Methods inherited from class org.abora.white.xpp.basic.Heaper

destroy, destruct, equals, hashForEqual, printContentsOn, sendSelfTo, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ScruSet

protected ScruSet()

ScruSet

protected ScruSet(Rcvr rcvr)

Method Detail

actualHashForEqual

public int actualHashForEqual()

Description copied from class: Heaper

Defined by subclasses to produce the value returned by hashForEqual.

Overrides:

actualHashForEqual in class Heaper

contentsEqual

public boolean contentsEqual(ScruSet other)

Returns whether the two ScruSets have exactly the same set of elements at the moment. 'a->contentsEqual(b)' is equivalent to 'a->asImmuSet()->isEqual(b->asImmuSet())'.

contentsHash

public int contentsHash()

Has the same relationship to contentsEqual that hashForEqual has to isEqual. I.e., if 'a->contentsEqual (b)', then 'a->contentsHash() == b->contentsHash()'. The same complex caveats apply as to the stability and portability of the hash values as apply for hashForEqual.

hasMember

public abstract boolean hasMember(Heaper someone)

Is someone a member of the set now?

intersects

public boolean intersects(ScruSet other)

Return true if this set and the other set have any elements in common.

Subclasses may want to override for efficiency.

Parameters:

other - other set to test for an intersection with

Returns:

true if there are any elements in common

isEmpty

public abstract boolean isEmpty()

Return true if this set does not currently have any elements.

Returns:

true if this set does not currently have any elements.

isEqual

public abstract boolean isEqual(Heaper other)

Description copied from class: Heaper

Return true if the two objects are equal.

Specified by:

isEqual in class Heaper

isSubsetOf

public boolean isSubsetOf(ScruSet another)

Whether another currently has all my elements

copy

public abstract ScruSet copy()

A new one whose initial state is my current state, but that doesn't track changes. Note that there is no implication that these can be 'destroy'ed separately, because (for example) an ImmuSet just returns itself

asArray

public PtrArray asArray()

The elements in the set in an array, in some random order

asImmuSet

public abstract ImmuSet asImmuSet()

Return an immu snapshot of my current state. Should probably be done with a Converter rather than with a message (for the reasons listed in the Converter class comment). In terms of the Stamp/Bert analogy mentioned in the class comment, asImmuSet is like asking for the current Stamp.

asMuSet

public abstract MuSet asMuSet()

Return a Mu whose initial state is the same as my current state, but which will now deviate independently of me. In terms of the Stamp/Bert analogy mentioned in the class comment, asMuSet is like asking for a new Bert starting on the current Stamp.

printOn

public void printOn(java.io.PrintWriter oo)

Description copied from class: Heaper

This should rarely be overridden. In Tofu, it prints ClassName(...), where ... is either produced by printInsideOn or is ??? if printInsideOn it not overridden.

Overrides:

printOn in class Heaper

printOnWithSimpleSyntax

public void printOnWithSimpleSyntax(java.io.PrintWriter oo,
                                    java.lang.String open,
                                    java.lang.String sep,
                                    java.lang.String close)

printOnWithSyntax

public void printOnWithSyntax(java.io.PrintWriter oo,
                              java.lang.String openMarker,
                              java.lang.String separator,
                              java.lang.String closeMarker,
                              boolean fullPrint)

For example, if we have the set '{a, b, c}' and we print it with 'p->printOnWithSyntax(oo,

count

public abstract IntegerValue count()

How many elements are currently in the set. Being a set, if the same element is put into the set twice, it is only in the set once. 'Same' above is according to 'isEqual'.

stepper

public abstract Stepper stepper()

Returns a stepper which will enumerate all the elements of the set in some unspecified order

theOne

public Heaper theOne()

Iff I contain exactly one member, return it. Otherwise BLAST. The idea for this message is taken from the THE function of ONTIC (reference McAllester)