Module interval :: Class Interval

[show private | hide private]

Class Interval

Represents a continuous range of values

An Interval is composed of the lower bound, a closed lower bound flag, an upper bound, and a closed upper bound flag. The attributes are called lower_bound, lower_closed, upper_bound, and upper_closed, respectively. For an infinite interval, the bound is set to inf or -inf. IntervalSets are composed of zero to many Intervals.

Method Summary
	`__init__(self, lower_bound, upper_bound, **kwargs)` Initializes an interval
	`__and__(self, other)` Returns the intersection of two intervals
	`__cmp__(self, other)` Compares two intervals for ordering purposes
	`__contains__(self, obj)` Returns True if obj lies wholly within the Interval.
	`__eq__(self, other)` Test if an interval is equivalent to the object
	`__hash__(self)` Returns a hashed value of the object
	`__nonzero__(self)` Tells whether the interval is empty
	`__repr__(self)` Returns an evaluable expression that can reproduce the object
	`__str__(self)` Returns a string representation of the object
	`adjacent_to(self, other)` Tells whether an Interval is adjacent to the object without overlap
	`all(cls)` Returns an interval encompassing all values (Class method)
	`between(cls, a, b, closed)` Returns an interval between two values (Class method)
	`comes_before(self, other)` Tells whether an interval lies before the object
	`equal_to(cls, a)` Returns an point interval (Class method)
	`greater_than(cls, a)` Returns interval of all values greater than the given value (Class method)
	`greater_than_or_equal_to(cls, a)` Returns interval of all values greater than or equal to the given value (Class method)
	`join(self, other)` Combines two continous Intervals
	`less_than(cls, a)` Returns interval of all values less than the given value (Class method)
	`less_than_or_equal_to(cls, a)` Returns an interval containing the given values and everything less (Class method)
	`none(cls)` Returns an empty interval (Class method)
	`overlaps(self, other)` Tells whether the given interval overlaps the object

Instance Method Details

init(self, lower_bound=-Inf, upper_bound=Inf, **kwargs)
(Constructor)

Initializes an interval

Parameters

lower_bound: The lower bound of an interval (default -Inf)
upper_bound: The upper bound of an interval (default Inf)
closed: Boolean telling whether both ends of the interval are closed (default True). Setting this sets both lower_closed and upper_closed
lower_closed: Boolean telling whether the lower end of the interval is closed (default True)
upper_closed: Boolean telling whether the upper end of the interval is closed (default True)

An Interval can represent an infinite set.

>>> r = Interval(-Inf, Inf) # All values

An Interval can represent sets unbounded on an end.

>>> r = Interval(upper_bound=62, closed=False)
>>> r = Interval(upper_bound=37)
>>> r = Interval(lower_bound=246)
>>> r = Interval(lower_bound=2468, closed=False)

An Interval can represent a set of values up to, but not including a value.

>>> r = Interval(25, 28, closed=False)

An Interval can represent a set of values that have an inclusive boundary.

>>> r = Interval(29, 216)

An Interval can represent a single value

>>> r = Interval(82, 82)

Intervals that are not normalized, i.e. that have a lower bound exceeding an upper bound, are silently normalized.

>>> print Interval(5, 2, lower_closed=False)
[2..5)

Intervals can represent an empty set.

>>> r = Interval(5, 5, closed=False)

Intervals can only contain hashable (immutable) objects.

>>> r = Interval([], 12)
Traceback (most recent call last):

...

TypeError: lower_bound is not hashable.

>>> r = Interval(12, [])
Traceback (most recent call last):

...

TypeError: upper_bound is not hashable.

and(self, other)
(And operator)

Returns the intersection of two intervals

>>> print Interval.greater_than(3) & Interval.greater_than(5)
(5...)

>>> print Interval.greater_than(3) & Interval.equal_to(3)
<Empty>

>>> print Interval.greater_than_or_equal_to(3) & Interval.equal_to(3)
3

>>> print Interval.all() & Interval.all()
(...)

>>> print Interval.greater_than(3) & Interval.less_than(10)
(3..10)

cmp(self, other)
(Comparison operator)

Compares two intervals for ordering purposes

>>> Interval.equal_to(-1) < Interval.equal_to(2)
True

>>> Interval.equal_to(-1) == Interval.equal_to(2)
False

>>> Interval.equal_to(-1) > Interval.equal_to(2)
False

>>> Interval.between(2, 5) > Interval.between(2, 4)
True

>>> Interval.between(2, 5) == Interval.between(2, 4)
False

>>> Interval.between(2, 5) == Interval.between(2, 5)
True

>>> Interval.between(2, 5) >= Interval.between(2, 5)
True

contains(self, obj)
(In operator)

Returns True if obj lies wholly within the Interval.

>>> all    = Interval.all()
>>> lt     = Interval.less_than(10)
>>> le     = Interval.less_than_or_equal_to(10)
>>> some   = Interval(10, 20, lower_closed=False)
>>> single = Interval.equal_to(10)
>>> ge     = Interval.greater_than_or_equal_to(10)
>>> gt     = Interval.greater_than(10)
>>> ne     = Interval.equal_to(17)
>>> 10 in all
True

>>> 10 in lt
False

>>> 10 in le
True

>>> 10 in some
False

>>> 10 in single
True

>>> 10 in ge
True

>>> 10 in gt
False

>>> 10 in ne
False

>>> all in some
False

>>> lt in all
True

>>> lt in some
False

>>> single in ge
True

>>> ne in some
True

eq(self, other)
(Equality operator)

Test if an interval is equivalent to the object

>>> Interval.all() == Interval.none()
False

>>> Interval.equal_to(4) == Interval(4, 4)
True

>>> Interval(2, 2, closed=False) == Interval(0, 0, closed=False)
True

hash(self)
(Hashing function)

Returns a hashed value of the object

Intervals are to be considered immutable. Thus, a 32-bit hash can be generated for them.

>>> h = hash(Interval.less_than(5))

nonzero(self)
(Boolean test operator)

Tells whether the interval is empty

>>> if Interval(12, 12, closed=False):
...   print "Non-empty"
>>> if Interval(12, 12, upper_closed=False):
...   print "Non-empty"
>>> if Interval(12, 12):
...   print "Non-empty"
Non-empty

repr(self)
(Representation operator)

Returns an evaluable expression that can reproduce the object

>>> Interval(3, 6)
Interval(3, 6, lower_closed=True, upper_closed=True)

>>> Interval(3, 6, closed=False)
Interval(3, 6, lower_closed=False, upper_closed=False)

>>> Interval(3, 6, lower_closed=False)
Interval(3, 6, lower_closed=False, upper_closed=True)

>>> Interval()
Interval(-Inf, Inf, lower_closed=False, upper_closed=False)

str(self)
(Informal representation operator)

Returns a string representation of the object

This function yields a graphical representation of an Interval. It is included in the __str__ of an IntervalSet. Non-inclusive boundaries are bordered by a ( or ). Inclusive boundaries are bordered by [ or ]. Unbound values are shown as .... Intervals consisting of only a single value are shown as that value. Empty intervals are shown as the string <Empty>

>>> print Interval.all()
(...)

>>> print Interval.less_than(100)
(...100)

>>> print Interval.less_than_or_equal_to(2593)
(...2593]

>>> print Interval.greater_than(2378)
(2378...)

>>> print Interval.between(26, 8234, False)
(26..8234)

>>> print Interval(237, 2348, lower_closed=False)
(237..2348]

>>> print Interval.greater_than_or_equal_to(347)
[347...)

>>> print Interval(237, 278, upper_closed=False)
[237..278)

>>> print Interval.between(723, 2378)
[723..2378]

>>> print Interval.equal_to(5)
5

>>> print Interval.none()
<Empty>

adjacent_to(self, other)

Tells whether an Interval is adjacent to the object without overlap

Returns True if self is adjacent to other, meaning that if they were joined, there would be no discontinuity. They cannot overlap.

>>> r1  = Interval.less_than(-100)
>>> r2  = Interval.less_than_or_equal_to(-100)
>>> r3  = Interval.less_than(100)
>>> r4  = Interval.less_than_or_equal_to(100)
>>> r5  = Interval.all()
>>> r6  = Interval.between(-100, 100, False)
>>> r7  = Interval(-100, 100, lower_closed=False)
>>> r8  = Interval.greater_than(-100)
>>> r9  = Interval.equal_to(-100)
>>> r10 = Interval(-100, 100, upper_closed=False)
>>> r11 = Interval.between(-100, 100)
>>> r12 = Interval.greater_than_or_equal_to(-100)
>>> r13 = Interval.greater_than(100)
>>> r14 = Interval.equal_to(100)
>>> r15 = Interval.greater_than_or_equal_to(100)
>>> r1.adjacent_to(r6)
False

>>> r6.adjacent_to(r11)
False

>>> r7.adjacent_to(r9)
True

>>> r3.adjacent_to(r10)
False

>>> r5.adjacent_to(r14)
False

>>> r6.adjacent_to(r15)
True

>>> r1.adjacent_to(r8)
False

>>> r12.adjacent_to(r14)
False

>>> r6.adjacent_to(r13)
False

>>> r2.adjacent_to(r15)
False

>>> r1.adjacent_to(r4)
False

comes_before(self, other)

Tells whether an interval lies before the object

self comes before other when sorted if its lower bound is less than other's smallest value. If the smallest value is the same, then the Interval with the smallest upper bound comes first. Otherwise, they are equal.

>>> Interval.equal_to(1).comes_before(Interval.equal_to(4))
True

>>> Interval.less_than_or_equal_to(1).comes_before(Interval.equal_to(4))
True

>>> Interval.less_than_or_equal_to(5).comes_before(
...   Interval.less_than(5))
False

>>> Interval.less_than(5).comes_before(
...   Interval.less_than_or_equal_to(5))
True

>>> Interval.all().comes_before(Interval.all())
False

join(self, other)

Combines two continous Intervals

Combines two continuous Intervals into one Interval. If the two Intervals are disjoint, then an exception is raised.

>>> r1  = Interval.less_than(-100)
>>> r2  = Interval.less_than_or_equal_to(-100)
>>> r3  = Interval.less_than(100)
>>> r4  = Interval.less_than_or_equal_to(100)
>>> r5  = Interval.all()
>>> r6  = Interval.between(-100, 100, False)
>>> r7  = Interval(-100, 100, lower_closed=False)
>>> r8  = Interval.greater_than(-100)
>>> r9  = Interval.equal_to(-100)
>>> r10 = Interval(-100, 100, upper_closed=False)
>>> r11 = Interval.between(-100, 100)
>>> r12 = Interval.greater_than_or_equal_to(-100)
>>> r13 = Interval.greater_than(100)
>>> r14 = Interval.equal_to(100)
>>> r15 = Interval.greater_than_or_equal_to(100)
>>> print r13.join(r15)
[100...)

>>> print r7.join(r6)
(-100..100]

>>> print r11.join(r2)
(...100]

>>> print r4.join(r15)
(...)

>>> print r8.join(r8)
(-100...)

>>> print r3.join(r7)
(...100]

>>> print r5.join(r10)
(...)

>>> print r9.join(r1)
(...-100]

>>> print r12.join(r5)
(...)

>>> print r13.join(r1)
Traceback (most recent call last):

...

ArithmeticError: The Intervals are disjoint.

>>> print r14.join(r2)
Traceback (most recent call last):

...

ArithmeticError: The Intervals are disjoint.

overlaps(self, other)

Tells whether the given interval overlaps the object

Returns True if the one Interval overlaps another. If they are immediately adjacent, then this returns False. Use the adjacent_to function for testing for adjacent Intervals.

>>> r1  = Interval.less_than(-100)
>>> r2  = Interval.less_than_or_equal_to(-100)
>>> r3  = Interval.less_than(100)
>>> r4  = Interval.less_than_or_equal_to(100)
>>> r5  = Interval.all()
>>> r6  = Interval.between(-100, 100, False)
>>> r7  = Interval(-100, 100, lower_closed=False)
>>> r8  = Interval.greater_than(-100)
>>> r9  = Interval.equal_to(-100)
>>> r10 = Interval(-100, 100, upper_closed=False)
>>> r11 = Interval.between(-100, 100)
>>> r12 = Interval.greater_than_or_equal_to(-100)
>>> r13 = Interval.greater_than(100)
>>> r14 = Interval.equal_to(100)
>>> r15 = Interval.greater_than_or_equal_to(100)
>>> r8.overlaps(r9)
False

>>> r12.overlaps(r6)
True

>>> r7.overlaps(r8)
True

>>> r8.overlaps(r4)
True

>>> r14.overlaps(r11)
True

>>> r10.overlaps(r13)
False

>>> r5.overlaps(r1)
True

>>> r5.overlaps(r2)
True

>>> r15.overlaps(r6)
False

>>> r3.overlaps(r1)
True

Class Method Details

all(cls)

Returns an interval encompassing all values

>>> print Interval.all()
(...)

between(cls, a, b, closed=True)

Returns an interval between two values

Returns an interval between values a and b. If closed is True, then the endpoints are included. Otherwise, the endpoints are excluded.

>>> print Interval.between(2, 4)
[2..4]

>>> print Interval.between(2, 4, False)
(2..4)

equal_to(cls, a)

Returns an point interval

Returns an interval containing only a.

>>> print Interval.equal_to(32)
32

greater_than(cls, a)

Returns interval of all values greater than the given value

>>> print Interval.greater_than(32)
(32...)

greater_than_or_equal_to(cls, a)

Returns interval of all values greater than or equal to the given value

>>> print Interval.greater_than_or_equal_to(32)
[32...)

less_than(cls, a)

Returns interval of all values less than the given value

Returns an interval containing all values less than a. If closed is True, then all values less than or equal to a are returned.

>>> print Interval.less_than(32)
(...32)

less_than_or_equal_to(cls, a)

Returns an interval containing the given values and everything less

>>> print Interval.less_than_or_equal_to(32)
(...32]

none(cls)

Returns an empty interval

>>> print Interval.none()
<Empty>

Generated by Epydoc 2.1 on Wed Nov 9 22:22:38 2005

http://epydoc.sf.net