org.abora.white.filter
Class Filter

java.lang.Object
  |
  +--org.abora.white.xpp.basic.Heaper
        |
        +--org.abora.white.spaces.basic.XnRegion
              |
              +--org.abora.white.filter.Filter

Direct Known Subclasses:

AndFilter, ClosedFilter, NotSubsetFilter, NotSupersetFilter, OpenFilter, OrFilter, SubsetFilter, SupersetFilter

public abstract class Filter

extends XnRegion

A position in a FilterSpace is a region in the baseSpace, and a filter is a set of regions in the baseSpace. It is often more useful to think of a Filter as a Boolean function whose input is a region in the baseSpace, and of unions, intersections, and complements of filters as ORs, ANDs, and NOTs of functions. Not all possible such functions can be represented as Filters, since there is an uncountable infinity of them for any non-finite CoordinateSpace. There are representations for some basic filters, and any filters resulting from a finite sequence of unions, intersections, and complements among them. The basic filters are: subsetFilter(cs,R) -- all subsets of R (i.e. all R1 such that R1->isSubsetOf(R)) supersetFilter(cs,R) -- all supersets of R (i.e. all R1 such that R->isSubsetOf(R1)) Mathematically, this is all that is necessary, since other useful filters like intersection filters can be generated from these. (e.g. intersectionFilter(R) is subsetFilter(R->complement())->complement()). However, there are several more pseudo constructors provided as shortcuts, including intersectionFilters, closedFilters, emptyFilters, and intersections and unions of sets of filters.

Field Summary

protected FilterSpace

myCS

Constructor Summary

Filter(FilterSpace cs)

Filter(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.
static Filter	andFilter(CoordinateSpace cs, ScruSet subs) A filter that matches only regions that all of the filters in the set would have matched.
static Filter	andFilterPrivate(FilterSpace cs, ImmuSet subs) assumes that the interactions between elements have already been removed
XnRegion	asSimpleRegion() Return a simple region containing all positions contained by myself.
abstract XnRegion	baseRegion() Essential.
static Filter	closedFilter(CoordinateSpace cs) An filter that does match any region.
static ImmuSet	combineIntersect(ImmuSet set, Filter filter) keep going around doing intersections until there are no more special intersects
static ImmuSet	combineIntersect(ImmuSet a, ImmuSet b)
static ImmuSet	combineUnion(ImmuSet set, Filter filter) keep going around doing unions until there are no more special unions
static ImmuSet	combineUnion(ImmuSet a, ImmuSet b)
abstract XnRegion	complement() Essential.
XnRegion	complexIntersect(XnRegion other)
XnRegion	complexUnion(XnRegion other)
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.
static ImmuSet	distributeIntersect(CoordinateSpace cs, ImmuSet set, Filter filter) distribute the intersection of a filter with the union of a set of filters
static ImmuSet	distributeIntersect(CoordinateSpace cs, ImmuSet a, ImmuSet b) distribute the intersection of two unions of sets of filters
static ImmuSet	distributeUnion(CoordinateSpace cs, ImmuSet set, Filter filter) distribute the union of a filter with the intersection of a set of filters
static ImmuSet	distributeUnion(CoordinateSpace cs, ImmuSet anded, ImmuSet ored) distribute the union of an intersection and a union of sets of filters
boolean	doesPass(Joint joint) Whether there might be anything in the tree beneath the Joint that would pass the filter.
Pair	fetchCanonicalIntersect(Filter other) return NULL, or the pair of canonical filters (left == new1 | self, right == new2 | other)
Pair	fetchCanonicalUnion(Filter other) return NULL, or the pair of canonical filters (left == new1 | self, right == new2 | other)
XnRegion	fetchIntersect(XnRegion other)
Pair	fetchPairIntersect(Filter other) return the pair of canonical filters (left == new1 | self, right == new2 | other)
Pair	fetchPairUnion(Filter other) return the pair of canonical filters (left == new1 | self, right == new2 | other)
XnRegion	fetchSpecialIntersect(XnRegion other)
abstract XnRegion	fetchSpecialSubset(XnRegion other) return self or other if one is clearly a subset of the other, else NULL
XnRegion	fetchSpecialUnion(XnRegion other)
XnRegion	fetchUnion(XnRegion other)
FilterSpace	filterSpace()
Pair	getPairIntersect(Filter other) return the pair of canonical filters (left == new1 | self, right == new2 | other)
Pair	getPairUnion(Filter other) return the pair of canonical filters (left == new1 | self, right == new2 | other)
boolean	hasMember(Position pos) Do I contain this position? More than anything else, the behavior of this message is the defining characteristic of an XuRegion.
static void	info() {XnRegion CLIENT} baseRegion {Stepper CLIENT of: Filter} intersectedFilters {BooleanVar CLIENT} isAllFilter {BooleanVar CLIENT} isAnyFilter {BooleanVar CLIENT} match: region {XnRegion} {Stepper CLIENT of: Filter} unionedFilters
XnRegion	intersect(XnRegion other) Essential.
abstract Stepper	intersectedFilters() Essential.
static Filter	intersectionFilter(CoordinateSpace cs, XnRegion region) A filter that matches any region that intersects the given region.
abstract boolean	isAllFilter() Essential.
abstract boolean	isAnyFilter() Essential.
abstract boolean	isEmpty() Every coordinate space has exactly one empty region.
boolean	isEnumerable(OrderSpec order) See comment in XuRegion::stepper.
abstract boolean	isEqual(Heaper other) Two regions are equal iff they contain exactly the same set of positions
boolean	isFinite() Essential.
abstract 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.
boolean	isSwitchedBy(RegionDelta delta) Whether the change causes a change in the state of the filter.
boolean	isSwitchedOffBy(RegionDelta delta) Whether the change switches the state of the filter from on to off.
boolean	isSwitchedOnBy(RegionDelta delta) Whether the change switches the state of the filter from off to on.
abstract boolean	match(XnRegion region) Whether a region is inside this filter.
static Filter	notSubsetFilter(CoordinateSpace cs, XnRegion region) A filter matching any regions that is not a subset of the given region.
static Filter	notSupersetFilter(CoordinateSpace cs, XnRegion region) A filter that matches any region that is not a superset of the given region.
static Filter	openFilter(CoordinateSpace cs) A filter that matches any region.
static Filter	orFilter(CoordinateSpace cs, ScruSet subs) A filter that matches any region that any of the filters in the set would have matched.
static Filter	orFilterPrivate(FilterSpace cs, ImmuSet subs) assumes that the interactions between elements have already been removed
abstract Filter	pass(Joint parent) The simplest filter for looking at the tree beneath the node.
abstract XnRegion	relevantRegion() The region which is relevant to this filter, i.e.
void	sendSelfTo(Xmtr xmtr)
Stepper	simpleRegions(OrderSpec order) Break myself up into a finite set of non-empty simple regions which, when unionWith'ed together will yield me.
XnRegion	simpleUnion(XnRegion other) The result must contain all positions contained by either of the two original regions, and the result must be simple.
static Filter	subsetFilter(CoordinateSpace cs, XnRegion region) A filter that matches any region that is a subset of the given region.
static Filter	supersetFilter(CoordinateSpace cs, XnRegion region) A region that matches any region that is a superset of the given region.
abstract Stepper	unionedFilters() Essential.
XnRegion	unionWith(XnRegion other) The result has as members exactly those positions which are members of either of the original two regions.

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

chooseMany, chooseMany, chooseOne, chooseOne, delta, disjointSimpleRegions, disjointSimpleRegions, immuSet, intersects, isDistinction, isEnumerable, minus, simpleRegions, stepper, stepper, theOne, with, without

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

destroy, destruct, equals, hashForEqual, printContentsOn, printOn, toString

Methods inherited from class java.lang.Object

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

Field Detail

myCS

protected FilterSpace myCS

Constructor Detail

Filter

public Filter(FilterSpace cs)

Filter

public Filter(Rcvr receiver)

Method Detail

complement

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

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

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

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

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

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

isAllFilter

public abstract boolean isAllFilter()

Essential. Whether this is an 'all' Filter, i.e. it only matches Regions which contain everything in the baseRegion

isAnyFilter

public abstract boolean isAnyFilter()

Essential. Whether this is an 'any' Filter, i.e. it matches Regions which contain anything in the baseRegion

isEmpty

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

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

isEqual

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

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

intersectedFilters

public abstract Stepper intersectedFilters()

Essential. Break this up into a bunch of Filters which when intersected (anded) together give this one. If there is only one sub Filter it will be the receiver; otherwise, the sub Filters will be simple enough that either they or their complements will return true from at least one of isAndFilter or isOrFilter. If this is full (i.e. an open filter) then the stepper will have no elements.

unionedFilters

public abstract Stepper unionedFilters()

Essential. Break this up into a bunch of Filters which when unioned (ored) together give this one. If there is only one sub Filter it will be the receiver; otherwise, the sub Filters will be simple enough that either they or their complements will return true from at least one of isAndFilter or isOrFilter. The sub Filters might not be disjoint Regions. If this is empty (i.e. a closed filter) then the stepper will have no elements.

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

baseRegion

public abstract XnRegion baseRegion()

Essential. A region in the base space identifying what kind of filter this is. Succeeds only if this isAnyFilter or isAllFilter.

coordinateSpace

public CoordinateSpace coordinateSpace()

Description copied from class: XnRegion

Essential. The coordinate space in which this is a region

Specified by:

coordinateSpace in class XnRegion

relevantRegion

public abstract XnRegion relevantRegion()

The region which is relevant to this filter, i.e. whose presence or absence in a region can change whether it passes the filter

doesPass

public boolean doesPass(Joint joint)

Whether there might be anything in the tree beneath the Joint that would pass the filter.

isSwitchedBy

public boolean isSwitchedBy(RegionDelta delta)

Whether the change causes a change in the state of the filter. (I.E. Whether the old region was in and the new out, or vice versa.)

isSwitchedOffBy

public boolean isSwitchedOffBy(RegionDelta delta)

Whether the change switches the state of the filter from on to off. (I.E. Whether the old region was inside the filter and the new region outside.)

isSwitchedOnBy

public boolean isSwitchedOnBy(RegionDelta delta)

Whether the change switches the state of the filter from off to on. (I.E. Whether the old region was outside the filter and the new region inside.)

match

public abstract boolean match(XnRegion region)

Whether a region is inside this filter.

pass

public abstract Filter pass(Joint parent)

The simplest filter for looking at the tree beneath the node. The Joint keeps the intersection and union of all the nodes beneath it, so the result of this message can be used to prune a search. If the result is full, then everything beneath the node is in the filter (e.g. if this filter contained all subsets of S and the union was a superset of S). If the result is empty, then nothing beneath the node is in the filter (e.g. if this filter contained all subsets of S and the intersection was not a subset of S). In less extreme cases, this operation may at least simplify the filter by throwing out irrelevant search criteria.

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

simpleRegions

public Stepper simpleRegions(OrderSpec order)

Description copied from class: XnRegion

Break myself up into a finite set of non-empty simple regions which, when unionWith'ed together will yield me. May be sent to any region. If I am isEmpty, I will respond with the empty stepper. Otherwise, if I am simple I will respond with a stepper producing just myself. Please only use NULL for the 'order' argument for now unless the documentation for a particular region or coordinate space says that it will deal with the 'order' argument meaningfully. When no order is specified then I may return the simple regions in any order. When the ordering functionality is implemented, then I am constrained to produce the simple regions in an order consistent with the argument's ordering of my positions. When the simple regions don't overlap, and don't surround each other in the ordering, then the meaning is clear. Otherwise, there are several plausible options for how we should specify this message.

Specified by:

simpleRegions in class XnRegion

complexIntersect

public XnRegion complexIntersect(XnRegion other)

complexUnion

public XnRegion complexUnion(XnRegion other)

fetchCanonicalIntersect

public Pair fetchCanonicalIntersect(Filter other)

return NULL, or the pair of canonical filters (left == new1 | self, right == new2 | other)

fetchCanonicalUnion

public Pair fetchCanonicalUnion(Filter other)

return NULL, or the pair of canonical filters (left == new1 | self, right == new2 | other)

fetchIntersect

public XnRegion fetchIntersect(XnRegion other)

fetchPairIntersect

public Pair fetchPairIntersect(Filter other)

return the pair of canonical filters (left == new1 | self, right == new2 | other)

fetchPairUnion

public Pair fetchPairUnion(Filter other)

return the pair of canonical filters (left == new1 | self, right == new2 | other)

fetchSpecialIntersect

public XnRegion fetchSpecialIntersect(XnRegion other)

fetchSpecialSubset

public abstract XnRegion fetchSpecialSubset(XnRegion other)

return self or other if one is clearly a subset of the other, else NULL

fetchSpecialUnion

public XnRegion fetchSpecialUnion(XnRegion other)

fetchUnion

public XnRegion fetchUnion(XnRegion other)

getPairIntersect

public Pair getPairIntersect(Filter other)

return the pair of canonical filters (left == new1 | self, right == new2 | other)

getPairUnion

public Pair getPairUnion(Filter other)

return the pair of canonical filters (left == new1 | self, right == new2 | other)

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

filterSpace

public FilterSpace filterSpace()

sendSelfTo

public void sendSelfTo(Xmtr xmtr)

Overrides:

sendSelfTo in class Heaper

andFilter

public static Filter andFilter(CoordinateSpace cs,
                               ScruSet subs)

A filter that matches only regions that all of the filters in the set would have matched.

closedFilter

public static Filter closedFilter(CoordinateSpace cs)

An filter that does match any region.

intersectionFilter

public static Filter intersectionFilter(CoordinateSpace cs,
                                        XnRegion region)

A filter that matches any region that intersects the given region.

notSubsetFilter

public static Filter notSubsetFilter(CoordinateSpace cs,
                                     XnRegion region)

A filter matching any regions that is not a subset of the given region.

notSupersetFilter

public static Filter notSupersetFilter(CoordinateSpace cs,
                                       XnRegion region)

A filter that matches any region that is not a superset of the given region.

openFilter

public static Filter openFilter(CoordinateSpace cs)

A filter that matches any region.

orFilter

public static Filter orFilter(CoordinateSpace cs,
                              ScruSet subs)

A filter that matches any region that any of the filters in the set would have matched.

subsetFilter

public static Filter subsetFilter(CoordinateSpace cs,
                                  XnRegion region)

A filter that matches any region that is a subset of the given region.

supersetFilter

public static Filter supersetFilter(CoordinateSpace cs,
                                    XnRegion region)

A region that matches any region that is a superset of the given region.

andFilterPrivate

public static Filter andFilterPrivate(FilterSpace cs,
                                      ImmuSet subs)

assumes that the interactions between elements have already been removed

combineIntersect

public static ImmuSet combineIntersect(ImmuSet set,
                                       Filter filter)

keep going around doing intersections until there are no more special intersects

combineIntersect

public static ImmuSet combineIntersect(ImmuSet a,
                                       ImmuSet b)

combineUnion

public static ImmuSet combineUnion(ImmuSet set,
                                   Filter filter)

keep going around doing unions until there are no more special unions

combineUnion

public static ImmuSet combineUnion(ImmuSet a,
                                   ImmuSet b)

distributeIntersect

public static ImmuSet distributeIntersect(CoordinateSpace cs,
                                          ImmuSet set,
                                          Filter filter)

distribute the intersection of a filter with the union of a set of filters

distributeIntersect

public static ImmuSet distributeIntersect(CoordinateSpace cs,
                                          ImmuSet a,
                                          ImmuSet b)

distribute the intersection of two unions of sets of filters

distributeUnion

public static ImmuSet distributeUnion(CoordinateSpace cs,
                                      ImmuSet set,
                                      Filter filter)

distribute the union of a filter with the intersection of a set of filters

distributeUnion

public static ImmuSet distributeUnion(CoordinateSpace cs,
                                      ImmuSet anded,
                                      ImmuSet ored)

distribute the union of an intersection and a union of sets of filters

orFilterPrivate

public static Filter orFilterPrivate(FilterSpace cs,
                                     ImmuSet subs)

assumes that the interactions between elements have already been removed

info

public static void info()

{XnRegion CLIENT} baseRegion {Stepper CLIENT of: Filter} intersectedFilters {BooleanVar CLIENT} isAllFilter {BooleanVar CLIENT} isAnyFilter {BooleanVar CLIENT} match: region {XnRegion} {Stepper CLIENT of: Filter} unionedFilters