org.abora.white.collection.tables
Class ScruTable

java.lang.Object
  |
  +--org.abora.white.xpp.basic.Heaper
        |
        +--org.abora.white.collection.tables.ScruTable

Direct Known Subclasses:

ImmuTable, IntegerScruTable, MuTable, OffsetScruArray, OffsetScruTable

public abstract class ScruTable

extends Heaper

Please read class comment for ScruSet first.

Like Sets, Tables represent collections of Heapers, and provide protocol for storing, retrieving, and iterating over the collection. However, Tables in addition provide an organization for the Heapers collected together in the range of a Table: A Table can also be seen as a collection of associations between keys and values. A particular Table object has a particular domain coordinateSpace, and all keys in that Table are positions in that coordinate space. For each position in a Table's coordinate space there is at most one value which it maps to. This value may be any arbitrary Heaper. The same Heaper may appear as value for several keys.

When iterating over the contents of a Table with a Stepper, the normal elements enumerated by the Stepper are values (i.e., range elements) of the Table. However, ScruTable::stepper returns a TableStepper (a subclass of Stepper) which provides aditional protocol of accessing the key corresponding to the current value. (see ScruTable::stepper and TableStepper.)

Constructor Summary

protected	ScruTable()
protected	ScruTable(Rcvr rcvr)

Method Summary

int	actualHashForEqual() See ScruTable::isEqual
abstract ImmuTable	asImmuTable() Return a side-effect-free snapshot of my current contents.
abstract MuTable	asMuTable() Return a side-effectable version of the same table.
ScruTable	backfollowFrom(Heaper value) Return the subTable with the domain of all positions whose values are equal to value.
boolean	contentsEqual(ScruTable other) Returns whether the two ScruTables have exactly the same mapping from keys to values at the moment.
int	contentsHash() Has the same relationship to contentsEqual that hashForEqual has to isEqual.
abstract CoordinateSpace	coordinateSpace() The kind of elements used to index into the table are Positions of this coordinate space.
abstract ScruTable	copy() A new one whose initial state is my current state, but that doesn't track changes.
abstract IntegerValue	count() Return the number of domain elements, which is to say, the number of associations.
abstract XnRegion	domain() Return an XuRegion representing a snapshot of the current domain.
abstract ScruTable	emptySize(IntegerValue size) Return an empty table just like the current one.
abstract Heaper	fetch(Position key) Return the range element at the domain position key.
Heaper	get(Position key) Return the range element at the domain position key.
boolean	includesIntKey(IntegerValue aKey) Unboxed version.
boolean	includesKey(Position key) includesKey is used to test for the presence of a key->value pair in the table.
Heaper	intFetch(IntegerValue key) Unboxed version.
Heaper	intGet(IntegerValue key) Unboxed version.
abstract boolean	isEmpty() Is there anything in the table? 'table->isEmpty()' iff 'table->domain()->isEmpty()'.
abstract boolean	isEqual(Heaper other) All MuTable subclasses have equality based on identity (now and forever equal.
void	printOn(java.io.PrintWriter stream) This should rarely be overridden.
void	printOnWithSimpleSyntax(java.io.PrintWriter oo, java.lang.String open, java.lang.String sep, java.lang.String close) Print the contents of the table as key1
void	printOnWithSyntax(java.io.PrintWriter stream, java.lang.String open, java.lang.String map, java.lang.String sep, java.lang.String close) Print the contents of the table as key1
static void	problems()
ImmuSet	range() A snapshot of the current range elements of the table collected together into an ImmuSet.
abstract XnRegion	runAt(Position key) Return the length of the run starting at position key.
XnRegion	runAtInt(IntegerValue key) Unboxed version.
TableStepper	stepper() implement default argument of NULL
abstract TableStepper	stepper(OrderSpec order) Return a TableStepper which will enumerate my key->value mappings.
abstract ScruTable	subTable(XnRegion region) Return a table which contains only the intersection of this table's domain and the domain specified by 'region'.
Heaper	theOne() Iff I contain exactly one range element, return it.
ScruTable	transformedBy(Dsp dsp) Return a ScruTable with the domain of the receiver transformed by the Dsp.

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

ScruTable

protected ScruTable()

ScruTable

protected ScruTable(Rcvr rcvr)

Method Detail

coordinateSpace

public abstract CoordinateSpace coordinateSpace()

The kind of elements used to index into the table are Positions of this coordinate space. Therefore, the domain of this table is an XuRegion in this coordinate space.

count

public abstract IntegerValue count()

Return the number of domain elements, which is to say, the number of associations. 'table->count()' should be equivalent to 'table->domain()->count()'. Used to say: 'Return the number of range elements'. This seems clearly wrong.

domain

public abstract XnRegion domain()

Return an XuRegion representing a snapshot of the current domain. 'table->domain()->hasMember(p)' iff 'table->fetch(p) !!= NULL'.

fetch

public abstract Heaper fetch(Position key)

Return the range element at the domain position key. The routine will return NULL if the position is not in the table.

get

public Heaper get(Position key)

Return the range element at the domain position key. BLAST if the position is not in the table.

range

public ImmuSet range()

A snapshot of the current range elements of the table collected together into an ImmuSet.

subTable

public abstract ScruTable subTable(XnRegion region)

Return a table which contains only the intersection of this table's domain and the domain specified by 'region'. table->subTable(r)->domain()->isEqual( table->domain()->intersect(r) ). It is unspecified whether the resulting table starts as a snapshot of a subset of me, after which we go our own ways; or whether the resulting table is a view onto a subset of me, such that changes to me are also visible to him. Of course, subclasses may specify more. If you want to ensure snapshot behavior, do 'table->subTable(r)->asImmuTable()'. NOTE: In the future we may specify snapshot behavior or we may specify view behavior. As a client this shouldn't effect you. However, if you implement a new kind of ScruTable, please let us know. Also, if you have an opinion as to which way you'd like the specification tightened up, please tell us.

transformedBy

public ScruTable transformedBy(Dsp dsp)

Return a ScruTable with the domain of the receiver transformed by the Dsp. 'table->transformedBy(d)->fetch(p)' is equivalent to 'table->fetch(d->of(p))'. See ScruTable::subTable for caveats regarding whether we return a snapshot or a view. All the same caveats apply.

actualHashForEqual

public int actualHashForEqual()

See ScruTable::isEqual

Overrides:

actualHashForEqual in class Heaper

contentsEqual

public boolean contentsEqual(ScruTable other)

Returns whether the two ScruTables have exactly the same mapping from keys to values at the moment. 'a->contentsEqual(b)' is equivalent to 'a->asImmuTable()->isEqual(b->asImmuTable())'. See ScruTable::contentsEqual

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. See ScruSet contentsHash.

includesKey

public boolean includesKey(Position key)

includesKey is used to test for the presence of a key->value pair in the table. This routine returns true if there is a value present at the specified key, and false otherwise. 'table->includesKey(p)' iff 'table->domain()->hasMember(p)'.

isEmpty

public abstract boolean isEmpty()

Is there anything in the table? 'table->isEmpty()' iff 'table->domain()->isEmpty()'.

isEqual

public abstract boolean isEqual(Heaper other)

All MuTable subclasses have equality based on identity (now and forever equal. Many ScruTable subclasses will represent an aspect of another table. Therefore they have hashForEqual and isEqual: based on both their contained table, and the aspect that they represent. Thus, two similar views onto the same MuTable are now (and forever) equal. The hashForEqual: must use exactly the same aspects for the hash as get used for isEqual:. ImmuTables all use contentBased comparison operations.

Specified by:

isEqual in class Heaper

stepper

public abstract TableStepper stepper(OrderSpec order)

Return a TableStepper which will enumerate my key->value mappings. The Stepper component of the TableStepper protocol will just enumerate my values (as that is what I'm a container *of*--the keys are simply how I organize my contents). TableStepper provides additional protocol to ascetain the current key. See TableStepper and XuRegion::stepper. The TableStepper I produce given an order must enumerate keys according to the same rules which specify how XuRegion::stepper must enumerate positions. I am not asserting that the actual orders are the same, only that the correctness criteria on the allowable orders are the same. Keeping in mind that we are talking about equivalence of specification and not equivalence of particular behavior, the following two statements are equivalent: { SPTR(TableStepper) stomp = table->stepper(o); SPTR(Position) key; FOR_EACH(Heaper,val,stomp, { key = stomp->key(); doSomethingWith(key, val); }); } and { SPTR(Heaper) val; SPTR(ImmuTable) snapShot = table->asImmuTable(); FOR_EACH(Position,key,(snapShot->domain()->stepper(o)), { val = snapShot->get (key); doSomethingWith(key, val); }); }

theOne

public Heaper theOne()

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

asImmuTable

public abstract ImmuTable asImmuTable()

Return a side-effect-free snapshot of my current contents. See ScruSet::asImmuSet.

asMuTable

public abstract MuTable asMuTable()

Return a side-effectable version of the same table. See ScruSet::asMuSet.

backfollowFrom

public ScruTable backfollowFrom(Heaper value)

Return the subTable with the domain of all positions whose values are equal to value. Defined by analogy with corresponding Waldo-level operation.

printOn

public void printOn(java.io.PrintWriter stream)

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)

Print the contents of the table as key1

printOnWithSyntax

public void printOnWithSyntax(java.io.PrintWriter stream,
                              java.lang.String open,
                              java.lang.String map,
                              java.lang.String sep,
                              java.lang.String close)

Print the contents of the table as key1

runAt

public abstract XnRegion runAt(Position key)

Return the length of the run starting at position key. A run is defined as a contiguous (charming) sequence of domain positions mapping to equal (isEqual) objects. Charming is defined as: Given a charming region R, for all a,c which are elements of R and a >= b >= c, b is an element of R. Where '>=' is according to the 'isGE' message. NOTE: We may retire the above definition of charming. The possible changes will only effect spaces which aren't fully ordered. OrderedRegions, TreeRegions, and IntegerRegions will be unaffected, as any future definition of 'runAt' will be equivalent for them.

copy

public abstract ScruTable 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 ImmuTable just returns itself

emptySize

public abstract ScruTable emptySize(IntegerValue size)

Return an empty table just like the current one. The 'size' argument is a hint about how big the count of the table will probably become (so that the new table can be prepared to grow to that size efficiently).

includesIntKey

public boolean includesIntKey(IntegerValue aKey)

Unboxed version. See class comment for XuInteger

intFetch

public Heaper intFetch(IntegerValue key)

Unboxed version. See class comment for XuInteger

intGet

public Heaper intGet(IntegerValue key)

Unboxed version. See class comment for XuInteger

runAtInt

public XnRegion runAtInt(IntegerValue key)

Unboxed version. See class comment for XuInteger

stepper

public TableStepper stepper()

implement default argument of NULL

problems

public static void problems()