intervals

Python tools for handling intervals (ranges of comparable objects).

Interval initialization

>>> from intervals import IntInterval

>>> # All integers between 1 and 4
>>> interval = IntInterval([1, 4])
>>> interval.lower
1
>>> interval.upper
4
>>> interval.lower_inc
True
>>> interval.upper_inc
True

Open, half-open and closed intervals

Intervals can be either open, half-open or closed. Properties lower_inc and upper_inc denote whether or not given endpoint is included (open) or not.

An open interval is an interval where both endpoints are open.

>>> interval = IntInterval((1, 4))
>>> interval.open
True
>>> interval.lower_inc
False
>>> interval.upper_inc
False

Half-open interval has one of the endpoints as open

>>> interval = Interval('[1, 4)')
>>> interval.open
False
>>> interval.lower_inc
True
>>> interval.upper_inc
False

Closed interval includes both endpoints

>>> interval = Interval([1, 4])
>>> interval.closed
True
>>> interval.lower_inc
True
>>> interval.upper_inc
True

Interval types

Each interval encapsulates a type. Interval is not actually a class. Its a convenient factory that generates AbstractInterval subclasses. Whenever you call Interval() the IntervalFactory tries to guess to best matching interval for given bounds.

>>> from datetime import date
>>> from infinity import inf

>>> interval = Interval([1, 4])
>>> interval
IntInterval('[1, 4]')
>>> interval.type.__name__
'int'

>>> interval = Interval(['a', 'd'])
>>> interval
CharacterInterval('[a, d]')
>>> interval.type.__name__
'str'

>>> interval = Interval([1.5, 4])
>>> interval
FloatInterval('[1.5, 4.0]')
>>> interval.type
<type 'float'>

>>> interval = Interval([date(2000, 1, 1), inf])
>>> interval
DateInterval('[2000-01-01,]')
>>> interval.type.__name__
'date'

You can also create interval subtypes directly (this is also faster than using Interval).

>>> from intervals import FloatInterval, IntInterval
>>> IntInterval([1, 4])
IntInterval('[1, 4]')
>>> FloatInterval((1.4, 2.7))
FloatInterval('(1.4, 2.7)')

Currently provided subtypes are:

IntInterval
CharacterInterval
FloatInterval
DecimalInterval
DateInterval
DateTimeInterval

Properties

radius gives the half-length of an interval
```
>>> IntInterval([1, 4]).radius
1.5
```
length gives the length of an interval.
```
>>> IntInterval([1, 4]).length
3
```
centre gives the centre (midpoint) of an interval
```
>>> IntInterval([-1, 1]).centre
0.0
```

Interval [a, b] is degenerate if a = b

>>> IntInterval([1, 1]).degenerate
True
>>> IntInterval([1, 2]).degenerate
False

Emptiness

An interval is empty if it contains no points:

>>> IntInterval('(1, 1]').empty
True

Data type coercion

Interval evaluates as True if its non-empty

>>> bool(IntInterval([1, 6]))
True
>>> bool(IntInterval([0, 0]))
True
>>> bool(IntInterval('(1, 1]'))
False

Integer intervals can be coerced to integer if they contain only one point, otherwise passing them to int() throws a TypeError

>>> int(IntInterval([1, 6]))
Traceback (most recent call last):
    ...
TypeError: Only intervals containing single point can be coerced to integers

>>> int(IntInterval('[1, 1]'))
1

Operators

Operator coercion rules

All the operators and arithmetic functions use special coercion rules. These rules are made for convenience.

So for example when you type:

IntInterval([1, 5]) > IntInterval([3, 3])

Its actually the same as typing:

IntInterval([1, 5]) > [3, 3]

Which is also the same as typing:

IntInterval([1, 5]) > 3

Comparison operators

>>> IntInterval([1, 5]) > IntInterval([0, 3])
True
>>> IntInterval([1, 5]) == IntInterval([1, 5])
True
>>> IntInterval([2, 3]) in IntInterval([2, 6])
True
>>> IntInterval([2, 3]) in IntInterval([2, 3])
True
>>> IntInterval([2, 3]) in IntInterval((2, 3))
False

Intervals are hashable

Intervals are hashed on the same attributes that affect comparison: the values of the upper and lower bounds, lower_inc and upper_inc, and the type of the interval. This enables the use of intervals as keys in dict() objects.

>>> IntInterval([3, 7]) in {IntInterval([3, 7]): 'zero to ten'}
True
>>> IntInterval([3, 7]) in set([IntInterval([3, 7])])
True
>>> IntInterval((3, 7)) in set([IntInterval([3, 7])])
False
>>> IntInterval([3, 7]) in set([FloatInterval([3, 7])])
False

Discrete intervals

>>> IntInterval([2, 4]) == IntInterval((1, 5))
True

Using interval steps

You can assign given interval to use optional step argument. By default IntInterval uses step=1. When the interval encounters a value that is not a multiplier of the step argument it tries to round it to the nearest multiplier of the step.

>>> from intervals import IntInterval

>>> interval = IntInterval([0, 5], step=2)
>>> interval.lower
0
>>> interval.upper
6

You can also use steps for FloatInterval and DecimalInterval classes. Same rounding rules apply here.

>>> from intervals import FloatInterval

>>> interval = FloatInterval([0.2, 0.8], step=0.5)
>>> interval.lower
0.0
>>> interval.upper
1.0

Arithmetics

Arithmetic operators

>>> Interval([1, 5]) + Interval([1, 8])
IntInterval('[2, 13]')

>>> Interval([1, 4]) - 1
IntInterval('[0, 3]')

Intersection:

>>> Interval([2, 6]) & Interval([3, 8])
IntInterval('[3, 6]')

Union:

>>> Interval([2, 6]) | Interval([3, 8])
IntInterval('[2, 8]')

Arithmetic functions

>>> interval = IntInterval([1, 3])

>>> # greatest lower bound
>>> interval.glb(IntInterval([1, 2]))
IntInterval('[1, 2]')

>>> # least upper bound
>>> interval.lub(IntInterval([1, 2]))
IntInterval('[1, 3]')

>>> # infimum
>>> interval.inf(IntInterval([1, 2]))
IntInterval('[1, 2]')

>>> # supremum
>>> interval.sup(IntInterval([1, 2]))
IntInterval('[1, 3]')

Name		Name	Last commit message	Last commit date
Latest commit History 131 Commits
intervals		intervals
tests		tests
.gitignore		.gitignore
.travis.yml		.travis.yml
CHANGES.rst		CHANGES.rst
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.rst		README.rst
setup.py		setup.py
tox.ini		tox.ini

License

bmcorser/intervals

Folders and files

Latest commit

History

Repository files navigation