API Reference

In addition to the methods explicitly documented here, intspan attempts to implement the complete list of set methods.

class intspan.intspan(initial=None)

A set of integers, expressed as an ordered sequence of spans. Because intspan('1-3,14,29,92-97') is better than [1, 2, 3, 14, 29, 92, 93, 94, 95, 96, 97].

add(items)

Add items.

Parameters:items (iterable|str) – Items to add. May be an intspan-style string.
complement(low=None, high=None)

Return the complement of the given intspan–that is, all of the ‘missing’ elements between its minimum and missing values. Optionally allows the universe set to be manually specified.

Parameters:
  • low (int) – Low bound of universe to complement against.
  • high (int) – High bound of universe to complement against.
Returns:

the complement set
Return type:

intspan
Raises:

ValueError – if the set is empty (thus the compelement is infinite)
copy()

Return a new set with the same members.

difference(items)

Return the difference of two or more sets as a new set.

(i.e. all elements that are in this set but not the others.)

difference_update(items)

Remove all elements of another set from this set.

discard(items)

Discard items.

Parameters:items (iterable|str) – Items to remove. May be an intspan-style string.
classmethod from_range(low, high)

Construct an intspan from the low value to the high value, inclusive. I.e., closed range, not the more typical Python half-open range.

Parameters:
  • low (int) – Low bound of set to construct.
  • high (int) – High bound of set to construct.
Returns:

New intspan low-high.
Return type:

intspan
classmethod from_ranges(ranges)

Construct an intspan from a sequence of (low, high) value sequences (lists or tuples, say). Note that these values are inclusive, closed ranges, not the more typical Python half-open ranges.

Parameters:ranges (list) – List of closed/inclusive ranges, each a tuple.
Returns:intspan combining the ranges
Return type:intspan
intersection(items)

Return the intersection of two or more sets as a new set.

(i.e. elements that are common to all of the sets.)

intersection_update(items)

Update a set with the intersection of itself and another.

issubset(items)

Report whether another set contains this set.

issuperset(items)

Report whether this set contains another set.

pop()

Remove and return an arbitrary element; raises KeyError if empty.

Returns:Arbitrary member of the set (which is removed)
Return type:int
Raises:KeyError – If the set is empty.
ranges()

Return a list of the set’s contiguous (inclusive) ranges.

Returns:List of all contained ranges.
Return type:list
remove(items)

Remove an element from a set; it must be a member.

If the element is not a member, raise a KeyError.

symmetric_difference(items)

Return the symmetric difference of two sets as a new set.

(i.e. all elements that are in exactly one of the sets.)

symmetric_difference_update(items)

Update a set with the symmetric difference of itself and another.

union(items)

Return the union of sets as a new set.

(i.e. all elements that are in either set.)

universe(low=None, high=None)

Return the “universe” or “covering set” of the given intspan–that is, all of the integers between its minimum and missing values. Optionally allows the bounds of the universe set to be manually specified.

Parameters:
  • low (int) – Low bound of universe.
  • high (int) – High bound of universe.
Returns:

the universe or covering set
Return type:

intspan
update(items)

Add multiple items.

Parameters:items (iterable|str) – Items to add. May be an intspan-style string.
class intspan.intspanlist(initial=None, universe=None)

An ordered version of intspan. Is to list what intspan is to set, except that it is somewhat set-like, in that items are not intended to be repeated. Works fine as an immutable data structure. Still some issues if one mutates an instance. Not terrible problems, but the set-like nature where there is only one entry for each included integer may be broken.

append(item)

Add to the end of the intspanlist

Parameters:item (int) – Item to add
complement(low=None, high=None)

Return the complement of the given intspanlist–that is, all of the ‘missing’ elements between its minimum and missing values. Optionally allows the universe set to be manually specified.

Parameters:
  • low (int) – Low bound of universe to complement against.
  • high (int) – High bound of universe to complement against.
Returns:

the complement set
Return type:

intspanlist
Raises:

ValueError – if the set is empty (thus the compelement is infinite)
copy()

Return a copy of the intspanlist.

extend(items)

Add a collection to the end of the intspanlist

Parameters:items (iterable) – integers to add
classmethod from_range(low, high)

Construct an intspanlist from the low value to the high value, inclusive. I.e., closed range, not the more typical Python half-open range.

Parameters:
  • low (int) – Low bound.
  • high (int) – High bound.
Returns:

New intspanlist low-high.
Return type:

intspanlist
classmethod from_ranges(ranges)

Construct an intspanlist from a sequence of (low, high) value sequences (lists or tuples, say). Note that these values are inclusive, closed ranges, not the more typical Python half-open ranges.

Parameters:ranges (list) – List of closed/inclusive ranges, each a tuple.
Returns:intspanlist combining the ranges
Return type:intspanlist
ranges()

Return a list of the set’s contiguous (inclusive) ranges.

therest_update(universe, inplace=True)

If the receiving intspanlist contains a TheRest marker, replace it with the contents of the universe. Generally done in situ, but if value of inplace kwarg false, returns an edited copy.

intspan.spanlist(spec=None)

Given a string specification like the ones given to intspan, return a list of the included items, in the same item given. Thus, spanlist("3,1-4") yields [3, 1, 2, 4]. Experimental partial implementation of ability to have ordered intspans.