org.abora.white.spaces.unordered
Class SetRegion

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

Direct Known Subclasses:

HeaperRegion

public abstract 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

Constructor Summary

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

SetRegion(Rcvr receiver)

Method Summary

int	actualHashForEqual() Defined by subclasses to produce the value returned by hashForEqual.
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.
XnRegion	complement() Essential.
abstract CoordinateSpace	coordinateSpace() Essential.
IntegerValue	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).
boolean	isEmpty() Every coordinate space has exactly one empty region.
boolean	isEnumerable(OrderSpec order) See comment in XuRegion::stepper.
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.
abstract 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) This should rarely be overridden.
void	sendSelfTo(Xmtr xmtr)
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.white.spaces.basic.XnRegion

chooseMany, chooseMany, chooseOne, chooseOne, delta, disjointSimpleRegions, disjointSimpleRegions, immuSet, isDistinction, isEnumerable, simpleRegions, stepper, stepper

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

destroy, destruct, equals, hashForEqual, printContentsOn, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, 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.

Specified by:

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

Specified by:

simpleRegions in class XnRegion

count

public IntegerValue count()

Description copied from class: XnRegion

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

Specified by:

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)

Specified by:

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.

Specified by:

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.

Specified by:

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.

Specified by:

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.

Specified by:

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()

Description copied from class: Heaper

Defined by subclasses to produce the value returned by hashForEqual.

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.

Specified by:

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.

Specified by:

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

Specified by:

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.

Specified by:

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.

Specified by:

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)

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

makeNew

public abstract XnRegion makeNew(boolean isComplement,
                                 ImmuSet positions)

coordinateSpace

public abstract CoordinateSpace coordinateSpace()

Description copied from class: XnRegion

Essential. The coordinate space in which this is a region

Specified by:

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.

Specified by:

actualStepper in class XnRegion

sendSelfTo

public void sendSelfTo(Xmtr xmtr)

Overrides:

sendSelfTo in class Heaper