org.abora.gold.spaces.unordered
Class SetRegion

java.lang.Object
  |
  +--org.abora.gold.java.AboraHeaper
        |
        +--org.abora.gold.xpp.basic.Heaper
              |
              +--org.abora.gold.spaces.basic.XnRegion
                    |
                    +--org.abora.gold.spaces.unordered.SetRegion

Direct Known Subclasses:

HeaperRegion

public class SetRegion

extends XnRegion

How do you make regions for spaces whose positions
a) have no orderring (i.e., either no ordering can be imposed (as
in HeaperSpace) or it is undesirable to impose one (as curently
in IDSpace)); and
b) there is an inifinte supply of new positions, and you can only
name the positions you''ve encountered?
SetRegion is our answer to that. To start with, a set region can simply be an enumeration
of the positions which are its members. However, because the complement of an XuRegion
must be a valid XuRegion, and we have no other representation of the infinite set of
positions left over, we must also be able to represent the region consisting of all
positions except those explicitly enumerated. Every SetRegion must either have a finite
number of positions, or it must cover all the space except for a finite number of
positions.
With regard to degrees of simplicity (see class comment in XuRegion), we currently only
have distinctions. There are no non-distinctions, and therefore no non-simple SetRegions.
Interesting cases are:
1) empty region
2) full region
3) singleton set (single member)
4) singleton hole (single non-member)
5) region with more than 1, but a finite number, of members
6) region with more than 1, but a finite number, of non-members
Cases 1, 3, and 5 can be considered the "positive" regions, and cases 2, 4, and 6 the
"negative" ones.
Because we only have distinctions (which we are currently doing for an internal reason
which will probably go away), we forego the ability to use the generic XuRegion protocol
to decompose complex regions into simpler ones. Instead we provide SetRegion specific
protocol ("positions" and "isComplement").
At a later time, we will probably have cases 1 thru 4 above be the only distinctions, case
6 be a simple region but not a distinction, and have case 5 be a non-simple region.
(These choices are all consistent with the letter and spirit of the simplicity framework
documented in XuRegion. Simple regions must be the *intersection* of distinctions,
therefore case 5 cannot be a simple non-distinction.) Please try to write your software
so that it''ll be insensitive to this change. Thanks.
SetRegion is an abstract superclass useful for defining regions for spaces which have the
constraints listed above.

Field Summary

protected boolean	myIsComplement
protected ImmuSet	myPositions

Fields inherited from class org.abora.gold.spaces.basic.XnRegion

CantMixCoordSpacesSignal, EmptyRegionSignal

Fields inherited from class org.abora.gold.xpp.basic.Heaper

AllBlasts, BecomeMap, GarbageCount, InGC, InitializedClasses, InitializingClasses, LastMemory, NextClientRequestNumber, NotOneElementSignal, PackageTable, PromiseNameTable, StringHashSBoxes

Fields inherited from class org.abora.gold.java.AboraHeaper

ActiveClubs, CurrentAuthor, CurrentBertCanopyCache, CurrentBertCrum, CurrentChunk, CurrentGrandMap, CurrentKeyMaster, CurrentPacker, CurrentSensorCanopyCache, CurrentServer, CurrentSession, CurrentSessions, CurrentTrace, InitialEditClub, InitialOwner, InitialReadClub, InitialSponsor, InsideTransactionFlag

Constructor Summary

SetRegion(boolean cmp, ImmuSet set)
the set should be for my use alone

SetRegion(Rcvr receiver)

Method Summary

int	actualHashForEqual()
Stepper	actualStepper(OrderSpec order) Only called if I've already said I'm enumerable in the originally stated order.
XnRegion	asSimpleRegion() Return a simple region containing all positions contained by myself. If I am simple, then the result must be me.
XnRegion	complement() Essential.
CoordinateSpace	coordinateSpace() Essential.
IntegerVar	count() How many positions do I contain? If I am not 'isFinite', then this message will BLAST.
ScruSet	distinctions() Break it up into a set of non-full distinctions.
boolean	hasMember(Position atPos) Do I contain this position? More than anything else, the behavior of this message is the defining characteristic of an XuRegion.
XnRegion	intersect(XnRegion region) Essential.
boolean	intersects(XnRegion region) Essential.
boolean	isComplement() FALSE means that I'm a 'positive' region (see class comment). TRUE means I'm a negative region.
boolean	isEmpty() Every coordinate space has exactly one empty region.
boolean	isEnumerable(OrderSpec order) See comment in XuRegion::stepper. a->stepper(os) won't BLAST iff a->isEnumerable(os)
boolean	isEqual(Heaper other) Two regions are equal iff they contain exactly the same set of positions
boolean	isFinite() Essential.
boolean	isFull() true if this is the largest possible region in this space -- the region that contains all positions in the space.
boolean	isSimple() Am I a simple region.
boolean	isSubsetOf(XnRegion other) I'm a subset of other if I don't have any positions that he doesn't.
XnRegion	makeNew(boolean isComplement, ImmuSet positions)
XnRegion	minus(XnRegion other) The region containing all my position which aren't in other.
ImmuSet	positions() If I'm a positive region (see class comment and isComplement), then this is a list of those positions I contain.
void	printOn(java.io.PrintWriter oo)
void	sendSelfTo(Xmtr xmtr) do nothing
Stepper	simpleRegions(OrderSpec order) Make up a singleton set containing the whole region
XnRegion	simpleUnion(XnRegion other) The result must contain all positions contained by either of the two original regions, and the result must be simple.
Position	theOne() Iff I contain exactly one position, return it.
XnRegion	unionWith(XnRegion region) The result has as members exactly those positions which are members of either of the original two regions.
XnRegion	with(Position pos) the region with one more position.
XnRegion	without(Position pos) the region with one less position.

Methods inherited from class org.abora.gold.spaces.basic.XnRegion

asArray, chooseMany, chooseMany, chooseOne, chooseOne, delta, disjointSimpleRegions, disjointSimpleRegions, dox, immuSet, info, isDistinction, isEnumerable, mapping, simpleRegions, stepper, stepper

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

abstractDeclarationFor, abstractTypeFor, addMethodAttributeToInOf, addPackage, addPackageCategory, allClientProtocolOn, argumentTypesFor, arrow, blast, blast, BLAST, cachePromiseNameTable, cachePromiseNameTableIn, canYouBecome, cast, cleanPromiseClasses, cleanupGarbage, clientClassesDo, clientFunctionsOn, clientMethodsOn, clientProtocol, clientProtocolDo, clientProtocolOn, clientProtocolOn, collectibleClasses, compare, compileClientSubclasses, compileConstantPromiseMethods, compileCreateFromRcvr, compileEQ, compileGeneratedClassMethod, compileGeneratedMethod, compileHook, compilePromise, compilePromiseDefaultMethods, compilePromiseFluidDeclarations, compilePromiseHandlers, compilePromiseMethods, compileRequestCreateMsgInArguments, compileRequestEvaluateMsgInReturningArguments, compileRPCSpecialistEvaluateMsgForReturningArguments, compileSendSelfTo, compileSendSelfToSendHook, compileStubbleMethods, compileSubclassStubbleMethods, computeMangle, computePreorder, constantTypeValue, convert, convertCopyDeclarations, convertDeferredDeclarations, convertProxyDeclarations, convertSubclassCopyDeclarations, convertSubclassDeferredDeclarations, convertSubclassProxyDeclarations, copyReferencesToType, create, create, create, create, create, create, create, create, create, create, createRequestClassArguments, definesProxyMethods, delete, deref, destroy, destruct, destructor, enum, enumFlags, equals, exportName, fetchAttribute, fetchPackage, fetchSuperCategory, fileOutClientProtocol, findCategory, findSenderAndReceiverMethods, findTailInto, flushPromiseNameTable, foo, freezeClientClasses, freezeClientProtocol, freezeStProtocol, frozenClasses, garbageCollect, garbageCollectFrom, gcOpportunity, gcOpportunity, generatedCategory, generatePromiseNames, getCategory, getOrMakePackage, getSuperCategory, handlerSignaturesFrom, hash, hashForEqual, hasProxyMethods, info_clientClasses, info_clientSideClasses, info_promiseClasses, info_stProtocol, inGC, initializedClasses, initializingClasses, initPackages, initStringHashSBoxes, inspectPieces, instanceSize, IntegerVar, isByProxy, isConstructed, isDestructed, isEqualOrSubclassOf, isGenerated, isIntType, isKindOf, isRawType, isUnlocked, linkTimeNonInherited, make, makeClassTable, makeFillTable, makeRequestTable, mangle, markChildren, markCount, markInstances, mayBecome, mayBecomeAnySubclassOf, new1, newX, nonCopyVariables, notWorking, pack, packageClasses, packagingCategory, parseExportName, passe, pointerToStaticMember, pointerToStaticMember, pointerToVirtualMember, preorderMax, preorderNumber, PROBLEM, problems, promiseClass, promiseDefaultValue, promiseName, promiseNameTable, promiseToAbstract, registerPackageCategory, removeGeneratedCode, removeStubbleMethods, removeSubclassGeneratedCode, removeSubclassStubbleMethods, requestProcedure, requestProceduresFrom, returnTypeFor, rootName, scheduleTermination, sendProxyTo, serverNameFor, setGC, signal, signals, smalltalkSelector, stClientProtocol, stubbleSelectorTokenReturnsArguments, subclassNonCopyVariables, takeOop, togglePromiseName, togglePromiseOfParse, unimplemented, unmangle, verifyFreeze, wipeStubble

Methods inherited from class org.abora.gold.java.AboraHeaper

asOop, basicInspect, displayString, error, hack, halt, inspect, knownBug, mightNotImplement, REQUIRES, shouldImplement, shouldNotImplement, stubbleForSubclassResponsibility, thingToDo, willNotImplement

Methods inherited from class java.lang.Object

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

Field Detail

myPositions

protected ImmuSet myPositions

myIsComplement

protected boolean myIsComplement

Constructor Detail

SetRegion

public SetRegion(boolean cmp,
                 ImmuSet set)

the set should be for my use alone

SetRegion

public SetRegion(Rcvr receiver)

Method Detail

asSimpleRegion

public XnRegion asSimpleRegion()

Description copied from class: XnRegion

Return a simple region containing all positions contained by myself.
If I am simple, then the result must be me. Otherwise,
the resulting region will contain more positions than I do, but it
must contain all those that I do. It would be good for the resulting
simple region to not contain many more points than it needs in order
to satisfy these constraints; but this is a preference, not a
specification. Particular spaces may specify stronger guarantees,
but as far as class XuRegion is concerned it is correct (though silly)
for this message to always return the full region for the space.

Overrides:

asSimpleRegion in class XnRegion

distinctions

public ScruSet distinctions()

Description copied from class: XnRegion

Break it up into a set of non-full distinctions. It is an error to send
this to a non-simple region. A full region will respond with the null
set. Other distinctions will respond with a singleton set containing
themselves, and simple regions will respond with a set of distinctions
which, when intersected together, yield the original region.

Overrides:

distinctions in class XnRegion

isComplement

public boolean isComplement()

FALSE means that I'm a 'positive' region (see class comment).
TRUE means I'm a negative region.

positions

public ImmuSet positions()

If I'm a positive region (see class comment and isComplement), then
this is a list of those positions I contain. If I'm negative, then it's
those positions I don't contain.

simpleRegions

public Stepper simpleRegions(OrderSpec order)

Make up a singleton set containing the whole region

Overrides:

simpleRegions in class XnRegion

count

public IntegerVar count()

Description copied from class: XnRegion

How many positions do I contain? If I am not 'isFinite', then this message will BLAST.

Overrides:

count in class XnRegion

isEnumerable

public boolean isEnumerable(OrderSpec order)

Description copied from class: XnRegion

See comment in XuRegion::stepper.
a->stepper(os) won't BLAST iff a->isEnumerable(os)

Overrides:

isEnumerable in class XnRegion

theOne

public Position theOne()

Description copied from class: XnRegion

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

Overrides:

theOne in class XnRegion

complement

public XnRegion complement()

Description copied from class: XnRegion

Essential. Return a region of containing exactly those positions not in this region. The
complement of a distinction must be a distinction.

Overrides:

complement in class XnRegion

intersect

public XnRegion intersect(XnRegion region)

Description copied from class: XnRegion

Essential. The intersection of two simple regions must be simple. The intersection of two
distinctions must therefore be a simple region. The result has exactly those members which
both the original regions have.

Overrides:

intersect in class XnRegion

minus

public XnRegion minus(XnRegion other)

Description copied from class: XnRegion

The region containing all my position which aren't in other.

Overrides:

minus in class XnRegion

simpleUnion

public XnRegion simpleUnion(XnRegion other)

Description copied from class: XnRegion

The result must contain all positions contained by either of the two
original regions, and the result must be simple. However, the result
may contain additional positions. See the comment on
'XuRegion::asSimpleRegion'. a->simpleUnion(b) satisfies the same specification
as (a->unionWith(b))->asSimpleRegion(). However, the two results do
not have to be the same region.

Overrides:

simpleUnion in class XnRegion

unionWith

public XnRegion unionWith(XnRegion region)

Description copied from class: XnRegion

The result has as members exactly those positions which are members of either of the
original two regions. No matter how simple the two original regions are, the result may be
non-simple.
The only reason this is called 'unionWith' instead of 'union' is that the latter is a C++
keyword.

Overrides:

unionWith in class XnRegion

with

public XnRegion with(Position pos)

Description copied from class: XnRegion

the region with one more position. Actually, if I already contain pos, then the result is
just me.

Overrides:

with in class XnRegion

without

public XnRegion without(Position pos)

Description copied from class: XnRegion

the region with one less position. Actually if I already don't contain pos, then the
result is just me.

Overrides:

without in class XnRegion

actualHashForEqual

public int actualHashForEqual()

Overrides:

actualHashForEqual in class XnRegion

hasMember

public boolean hasMember(Position atPos)

Description copied from class: XnRegion

Do I contain this position? More than anything else, the behavior of this message is the
defining characteristic of an XuRegion. All other messages (except for the simplicity
characterization) should be specifiable in terms of the behavior of this message. What an
XuRegion *is* (mostly) is a finite decision procedure for accepting or rejecting any given
position.

Overrides:

hasMember in class XnRegion

intersects

public boolean intersects(XnRegion region)

Description copied from class: XnRegion

Essential. tell whether it has any points in common

Overrides:

intersects in class XnRegion

isEmpty

public boolean isEmpty()

Description copied from class: XnRegion

Every coordinate space has exactly one empty region. It is the one containing no
positions. It and only it responds 'true' to this message.

Overrides:

isEmpty in class XnRegion

isEqual

public boolean isEqual(Heaper other)

Description copied from class: XnRegion

Two regions are equal iff they contain exactly the same set of positions

Overrides:

isEqual in class XnRegion

isFinite

public boolean isFinite()

Description copied from class: XnRegion

Essential. Do I contain a finite number of positions? If I do, then the 'count' message
will say how many, and I will gladly provide a stepper which will step over all of them.
I.e., isFinite implies isEnumerable.

Overrides:

isFinite in class XnRegion

isFull

public boolean isFull()

Description copied from class: XnRegion

true if this is the largest possible region in this space -- the region that contains all
positions in the space. Note that in a space which has no positions (which is perfectly
valid), the one XuRegion would be both empty (since it has no positions) and full (since
it has all the positions in the space).

Overrides:

isFull in class XnRegion

isSimple

public boolean isSimple()

Description copied from class: XnRegion

Am I a simple region. See XuRegion class comment for implications of being simple.

Overrides:

isSimple in class XnRegion

isSubsetOf

public boolean isSubsetOf(XnRegion other)

Description copied from class: XnRegion

I'm a subset of other if I don't have any positions that he doesn't. Note that if we are
equal, then I am still a subset of him. If you want to know if I'm a strict subset, you
can ask
a->isSubsetOf(b) && !! a->isEqual(b)

Overrides:

isSubsetOf in class XnRegion

printOn

public void printOn(java.io.PrintWriter oo)

Overrides:

printOn in class Heaper

makeNew

public XnRegion makeNew(boolean isComplement,
                        ImmuSet positions)

coordinateSpace

public CoordinateSpace coordinateSpace()

Description copied from class: XnRegion

Essential. The coordinate space in which this is a region

Overrides:

coordinateSpace in class XnRegion

actualStepper

public Stepper actualStepper(OrderSpec order)

Description copied from class: XnRegion

Only called if I've already said I'm enumerable in the originally stated order. Also, if
the originally stated order was NULL, I get a guaranteed non-null order. Subclasses which
override 'stepper' to a method which doesn't send 'actualStepper' may override
'actualStepper' to a stub method which always BLASTs.

Overrides:

actualStepper in class XnRegion

sendSelfTo

public void sendSelfTo(Xmtr xmtr)

Description copied from class: Heaper

do nothing

Overrides:

sendSelfTo in class Heaper