TimespanInventory

class timespantools.TimespanInventory(items=None, item_class=None, keep_sorted=False)

A timespan inventory.

Example 1. Contiguous timespan inventory:

>>> timespan_inventory_1 = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> print(format(timespan_inventory_1))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )
>>> show(timespan_inventory_1, scale=0.5) 

Example 2: Overlapping timespan inventory:

>>> timespan_inventory_2 = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 16),
...     timespantools.Timespan(5, 12),
...     timespantools.Timespan(-2, 8),
...     timespantools.Timespan(15, 20),
...     timespantools.Timespan(24, 30),
...     ])
>>> print(format(timespan_inventory_2))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(16, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(12, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(-2, 1),
            stop_offset=durationtools.Offset(8, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(15, 1),
            stop_offset=durationtools.Offset(20, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(24, 1),
            stop_offset=durationtools.Offset(30, 1),
            ),
        ]
    )
>>> show(timespan_inventory_2, scale=0.5) 

Example 3. Empty timespan inventory:

>>> timespan_inventory_3 = timespantools.TimespanInventory()
>>> print(format(timespan_inventory_3))
timespantools.TimespanInventory(
    []
    )

Operations on timespan currently work in place.

Lineage

digraph InheritanceGraph { graph [background=transparent, bgcolor=transparent, color=lightslategrey, fontname=Arial, outputorder=edgesfirst, overlap=prism, penwidth=2, rankdir=LR, root="__builtin__.object", splines=spline, style="dotted, rounded", truecolor=true]; node [colorscheme=pastel19, fontname=Arial, fontsize=12, penwidth=2, style="filled, rounded"]; edge [color=lightsteelblue2, penwidth=2]; subgraph cluster_abctools { graph [label=abctools]; "abjad.tools.abctools.AbjadObject.AbjadObject" [color=1, group=0, label=AbjadObject, shape=box]; "abjad.tools.abctools.AbjadObject.AbstractBase" [color=1, group=0, label=AbstractBase, shape=box]; "abjad.tools.abctools.AbjadObject.AbstractBase" -> "abjad.tools.abctools.AbjadObject.AbjadObject"; } subgraph cluster_datastructuretools { graph [label=datastructuretools]; "abjad.tools.datastructuretools.TypedCollection.TypedCollection" [color=3, group=2, label=TypedCollection, shape=oval, style=bold]; "abjad.tools.datastructuretools.TypedList.TypedList" [color=3, group=2, label=TypedList, shape=box]; "abjad.tools.datastructuretools.TypedCollection.TypedCollection" -> "abjad.tools.datastructuretools.TypedList.TypedList"; } subgraph cluster_timespantools { graph [label=timespantools]; "abjad.tools.timespantools.TimespanInventory.TimespanInventory" [color=black, fontcolor=white, group=3, label=<<B>TimespanInventory</B>>, shape=box, style="filled, rounded"]; } subgraph cluster_builtins { graph [label=builtins]; "builtins.object" [color=2, group=1, label=object, shape=box]; } "abjad.tools.abctools.AbjadObject.AbjadObject" -> "abjad.tools.datastructuretools.TypedCollection.TypedCollection"; "abjad.tools.datastructuretools.TypedList.TypedList" -> "abjad.tools.timespantools.TimespanInventory.TimespanInventory"; "builtins.object" -> "abjad.tools.abctools.AbjadObject.AbstractBase"; }

Attribute summary

all_are_contiguous Is true when all timespans are time-contiguous:
all_are_nonoverlapping Is true when all timespans are non-overlapping:
all_are_well_formed Is true when all timespans are well-formed:
append(item) Changes item to item and appends.
axis Arithmetic mean of start- and stop-offsets.
clip_timespan_durations([minimum, maximum, ...]) Clip durations of timespans.
compute_logical_and() Compute logical AND of timespans.
compute_logical_or() Compute logical OR of timespans.
compute_logical_xor() Compute logical XOR of timespans.
compute_overlap_factor([timespan]) Compute overlap factor of timespans:
compute_overlap_factor_mapping() Compute overlap factor for each consecutive offset pair in
count(item) Changes item to item and returns count.
count_offsets() Count offsets in inventory:
duration Time from start offset to stop offset:
explode([inventory_count]) Explode timespans into inventories, avoiding overlap, and distributing density as evenly as possible.
extend(items) Changes items to items and extends.
get_timespan_that_satisfies_time_relation(...) Get timespan that satisifies time_relation:
get_timespans_that_satisfy_time_relation(...) Get timespans that satisfy time_relation:
has_timespan_that_satisfies_time_relation(...) Is true when timespan inventory has timespan that
index(item) Changes item to item and returns index.
insert(i, item) Changes item to item and inserts.
is_sorted Is true when timespans are in time order:
item_class Item class to coerce items into.
items Gets collection items.
keep_sorted Sorts collection on mutation if true.
partition([include_tangent_timespans]) Partition timespans into inventories:
pop([i]) Aliases list.pop().
reflect([axis]) Reflect timespans.
remove(item) Changes item to item and removes.
remove_degenerate_timespans() Remove degenerate timespans:
repeat_to_stop_offset(stop_offset) Repeat timespans to stop_offset:
reverse() Aliases list.reverse().
rotate(count) Rotate by count contiguous timespans.
round_offsets(multiplier[, anchor, ...]) Round offsets of timespans in inventory to multiples of
scale(multiplier[, anchor]) Scale timespan by multiplier relative to anchor.
sort([cmp, key, reverse]) Aliases list.sort().
split_at_offset(offset) Split timespans at offset:
split_at_offsets(offsets) Split timespans at offsets:
start_offset Earliest start offset of any timespan:
stop_offset Latest stop offset of any timespan:
stretch(multiplier[, anchor]) Stretch timespans by multiplier relative to anchor.
timespan Timespan inventory timespan:
translate([translation]) Translate timespans by translation.
translate_offsets([...]) Translate timespans by start_offset_translation and stop_offset_translation.
__and__(timespan) Keep material that intersects timespan:
__contains__(item) Is true when typed collection container item.
__delitem__(i) Aliases list.__delitem__().
__eq__(expr) Is true when expr is a typed collection with items that compare equal to those of this typed collection.
__format__([format_specification]) Formats Abjad object.
__getitem__(i) Aliases list.__getitem__().
__hash__() Hashes typed collection.
__iadd__(expr) Changes items in expr to items and extends.
__illustrate__([key, range_, sortkey, scale]) Illustrates timespan inventory.
__iter__() Iterates typed collection.
__len__() Length of typed collection.
__ne__(expr) Is true when expr is not a typed collection with items equal to this typed collection.
__repr__() Gets interpreter representation of Abjad object.
__reversed__() Aliases list.__reversed__().
__setitem__(i, expr) Changes items in expr to items and sets.
__sub__(timespan) Delete material that intersects timespan:

Read-only properties

TimespanInventory.all_are_contiguous

Is true when all timespans are time-contiguous:

>>> timespan_inventory_1.all_are_contiguous
True

False when timespans not time-contiguous:

>>> timespan_inventory_2.all_are_contiguous
False

Is true when empty:

>>> timespan_inventory_3.all_are_contiguous
True

Returns true or false.

TimespanInventory.all_are_nonoverlapping

Is true when all timespans are non-overlapping:

>>> timespan_inventory_1.all_are_nonoverlapping
True

False when timespans are overlapping:

>>> timespan_inventory_2.all_are_nonoverlapping
False

Is true when empty:

>>> timespan_inventory_3.all_are_nonoverlapping
True

Returns true or false.

TimespanInventory.all_are_well_formed

Is true when all timespans are well-formed:

>>> timespan_inventory_1.all_are_well_formed
True
>>> timespan_inventory_2.all_are_well_formed
True

Also true when empty:

>>> timespan_inventory_3.all_are_well_formed
True

Otherwise false.

Returns true or false.

TimespanInventory.axis

Arithmetic mean of start- and stop-offsets.

>>> timespan_inventory_1.axis
Offset(5, 1)
>>> timespan_inventory_2.axis
Offset(14, 1)

None when empty:

>>> timespan_inventory_3.axis is None
True

Returns offset or none.

TimespanInventory.duration

Time from start offset to stop offset:

>>> timespan_inventory_1.duration
Duration(10, 1)
>>> timespan_inventory_2.duration
Duration(32, 1)

Zero when empty:

>>> timespan_inventory_3.duration
Duration(0, 1)

Returns duration.

TimespanInventory.is_sorted

Is true when timespans are in time order:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> timespan_inventory.is_sorted
True

Otherwise false:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(6, 10),
...     timespantools.Timespan(3, 6),
...     ])
>>> timespan_inventory.is_sorted
False

Returns true or false.

(TypedCollection).item_class

Item class to coerce items into.

(TypedCollection).items

Gets collection items.

TimespanInventory.start_offset

Earliest start offset of any timespan:

>>> timespan_inventory_1.start_offset
Offset(0, 1)
>>> timespan_inventory_2.start_offset
Offset(-2, 1)

Negative infinity when empty:

>>> timespan_inventory_3.start_offset
NegativeInfinity

Returns offset or none.

TimespanInventory.stop_offset

Latest stop offset of any timespan:

>>> timespan_inventory_1.stop_offset
Offset(10, 1)
>>> timespan_inventory_2.stop_offset
Offset(30, 1)

Infinity when empty:

>>> timespan_inventory_3.stop_offset
Infinity

Returns offset or none.

TimespanInventory.timespan

Timespan inventory timespan:

>>> timespan_inventory_1.timespan
Timespan(start_offset=Offset(0, 1), stop_offset=Offset(10, 1))
>>> timespan_inventory_2.timespan
Timespan(start_offset=Offset(-2, 1), stop_offset=Offset(30, 1))
>>> timespan_inventory_3.timespan
Timespan(start_offset=NegativeInfinity, stop_offset=Infinity)

Returns timespan.

Read/write properties

(TypedList).keep_sorted

Sorts collection on mutation if true.

Methods

(TypedList).append(item)

Changes item to item and appends.

>>> integer_collection = datastructuretools.TypedList(
...     item_class=int)
>>> integer_collection[:]
[]
>>> integer_collection.append('1')
>>> integer_collection.append(2)
>>> integer_collection.append(3.4)
>>> integer_collection[:]
[1, 2, 3]

Returns none.

TimespanInventory.clip_timespan_durations(minimum=None, maximum=None, anchor=Left)

Clip durations of timespans.

Example 1:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 1),
...     timespantools.Timespan(0, 10),
...     ])
>>> result = timespan_inventory.clip_timespan_durations(
...     minimum=5,
...     )
>>> print(format(result))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(5, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 2:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 1),
...     timespantools.Timespan(0, 10),
...     ])
>>> result = timespan_inventory.clip_timespan_durations(
...     maximum=5,
...     )
>>> print(format(result))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(1, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(5, 1),
            ),
        ]
    )

Example 3:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 1),
...     timespantools.Timespan(0, 10),
...     ])
>>> result = timespan_inventory.clip_timespan_durations(
...     minimum=3,
...     maximum=7,
...     )
>>> print(format(result))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(7, 1),
            ),
        ]
    )

Example 4:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 1),
...     timespantools.Timespan(0, 10),
...     ])
>>> result = timespan_inventory.clip_timespan_durations(
...     minimum=3,
...     maximum=7,
...     anchor=Right,
...     )
>>> print(format(result))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(-2, 1),
            stop_offset=durationtools.Offset(1, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Emit new inventory.

TimespanInventory.compute_logical_and()

Compute logical AND of timespans.

Example 1:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     ])
>>> result = timespan_inventory.compute_logical_and()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 2:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     timespantools.Timespan(5, 12),
...     ])
>>> result = timespan_inventory.compute_logical_and()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 3:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     timespantools.Timespan(5, 12),
...     timespantools.Timespan(-2, 8),
...     ])
>>> result = timespan_inventory.compute_logical_and()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(8, 1),
            ),
        ]
    )

Same as setwise intersection.

Operates in place and returns timespan inventory.

TimespanInventory.compute_logical_or()

Compute logical OR of timespans.

Example 1:

>>> timespan_inventory = timespantools.TimespanInventory()
>>> result = timespan_inventory.compute_logical_or()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    []
    )

Example 2:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     ])
>>> result = timespan_inventory.compute_logical_or()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 3:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     timespantools.Timespan(5, 12),
...     ])
>>> result = timespan_inventory.compute_logical_or()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(12, 1),
            ),
        ]
    )

Example 4:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     timespantools.Timespan(5, 12),
...     timespantools.Timespan(-2, 2),
...     ])
>>> result = timespan_inventory.compute_logical_or()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(-2, 1),
            stop_offset=durationtools.Offset(12, 1),
            ),
        ]
    )

Example 5:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(-2, 2),
...     timespantools.Timespan(10, 20),
...     ])
>>> result = timespan_inventory.compute_logical_or()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(-2, 1),
            stop_offset=durationtools.Offset(2, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(10, 1),
            stop_offset=durationtools.Offset(20, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.

TimespanInventory.compute_logical_xor()

Compute logical XOR of timespans.

Example 1:

>>> timespan_inventory = timespantools.TimespanInventory()
>>> result = timespan_inventory.compute_logical_xor()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    []
    )

Example 2:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     ])
>>> result = timespan_inventory.compute_logical_xor()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 3:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     timespantools.Timespan(5, 12),
...     ])
>>> result = timespan_inventory.compute_logical_xor()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(5, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(10, 1),
            stop_offset=durationtools.Offset(12, 1),
            ),
        ]
    )

Example 4:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     timespantools.Timespan(5, 12),
...     timespantools.Timespan(-2, 2),
...     ])
>>> result = timespan_inventory.compute_logical_xor()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(-2, 1),
            stop_offset=durationtools.Offset(0, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(2, 1),
            stop_offset=durationtools.Offset(5, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(10, 1),
            stop_offset=durationtools.Offset(12, 1),
            ),
        ]
    )

Example 5:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(-2, 2),
...     timespantools.Timespan(10, 20),
...     ])
>>> result = timespan_inventory.compute_logical_xor()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(-2, 1),
            stop_offset=durationtools.Offset(2, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(10, 1),
            stop_offset=durationtools.Offset(20, 1),
            ),
        ]
    )

Example 6:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     timespantools.Timespan(4, 8),
...     timespantools.Timespan(2, 6),
...     ])
>>> result = timespan_inventory.compute_logical_xor()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(2, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(8, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 7:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     timespantools.Timespan(0, 10),
...     ])
>>> result = timespan_inventory.compute_logical_xor()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    []
    )

Operates in place and returns timespan inventory.

TimespanInventory.compute_overlap_factor(timespan=None)

Compute overlap factor of timespans:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     timespantools.Timespan(5, 15),
...     timespantools.Timespan(20, 25),
...     timespantools.Timespan(20, 30),
...     ])

Example 1. Compute overlap factor across the entire inventory:

>>> timespan_inventory.compute_overlap_factor()
Multiplier(7, 6)

Example 2a. Compute overlap factor within a specific timespan:

>>> timespan_inventory.compute_overlap_factor(
...     timespan=timespantools.Timespan(-15, 0))
Multiplier(0, 1)

Example 2b:

>>> timespan_inventory.compute_overlap_factor(
...     timespan=timespantools.Timespan(-10, 5))
Multiplier(1, 3)

Example 2c:

>>> timespan_inventory.compute_overlap_factor(
...     timespan=timespantools.Timespan(-5, 10))
Multiplier(1, 1)

Example 2d:

>>> timespan_inventory.compute_overlap_factor(
...     timespan=timespantools.Timespan(0, 15))
Multiplier(4, 3)

Example 2e:

>>> timespan_inventory.compute_overlap_factor(
...     timespan=timespantools.Timespan(5, 20))
Multiplier(1, 1)

Example 2f:

>>> timespan_inventory.compute_overlap_factor(
...     timespan=timespantools.Timespan(10, 25))
Multiplier(1, 1)

Example 2g:

>>> timespan_inventory.compute_overlap_factor(
...     timespan=timespantools.Timespan(15, 30))
Multiplier(1, 1)

Returns multiplier.

TimespanInventory.compute_overlap_factor_mapping()

Compute overlap factor for each consecutive offset pair in timespans:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 10),
...     timespantools.Timespan(5, 15),
...     timespantools.Timespan(20, 25),
...     timespantools.Timespan(20, 30),
...     ])
>>> mapping = timespan_inventory.compute_overlap_factor_mapping()
>>> for timespan, overlap_factor in mapping.items():
...     timespan.start_offset, timespan.stop_offset, overlap_factor
...
(Offset(0, 1), Offset(5, 1), Multiplier(1, 1))
(Offset(5, 1), Offset(10, 1), Multiplier(2, 1))
(Offset(10, 1), Offset(15, 1), Multiplier(1, 1))
(Offset(15, 1), Offset(20, 1), Multiplier(0, 1))
(Offset(20, 1), Offset(25, 1), Multiplier(2, 1))
(Offset(25, 1), Offset(30, 1), Multiplier(1, 1))

Returns mapping.

(TypedList).count(item)

Changes item to item and returns count.

>>> integer_collection = datastructuretools.TypedList(
...     items=[0, 0., '0', 99],
...     item_class=int)
>>> integer_collection[:]
[0, 0, 0, 99]
>>> integer_collection.count(0)
3

Returns count.

TimespanInventory.count_offsets()

Count offsets in inventory:

Example 1:

>>> print(format(timespan_inventory_1))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )
>>> for offset, count in sorted(
...     timespan_inventory_1.count_offsets().items()):
...     offset, count
...
(Offset(0, 1), 1)
(Offset(3, 1), 2)
(Offset(6, 1), 2)
(Offset(10, 1), 1)

Example 2:

>>> print(format(timespan_inventory_2))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(16, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(12, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(-2, 1),
            stop_offset=durationtools.Offset(8, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(15, 1),
            stop_offset=durationtools.Offset(20, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(24, 1),
            stop_offset=durationtools.Offset(30, 1),
            ),
        ]
    )
>>> for offset, count in sorted(
...     timespan_inventory_2.count_offsets().items()):
...     offset, count
...
(Offset(-2, 1), 1)
(Offset(0, 1), 1)
(Offset(5, 1), 1)
(Offset(8, 1), 1)
(Offset(12, 1), 1)
(Offset(15, 1), 1)
(Offset(16, 1), 1)
(Offset(20, 1), 1)
(Offset(24, 1), 1)
(Offset(30, 1), 1)

Example 3:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(0, 6),
...     timespantools.Timespan(0, 9),
...     ])
>>> for offset, count in sorted(
...     timespan_inventory.count_offsets().items()):
...     offset, count
...
(Offset(0, 1), 3)
(Offset(3, 1), 1)
(Offset(6, 1), 1)
(Offset(9, 1), 1)

Returns counter.

TimespanInventory.explode(inventory_count=None)

Explode timespans into inventories, avoiding overlap, and distributing density as evenly as possible.

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(5, 13),
...     timespantools.Timespan(6, 10),
...     timespantools.Timespan(8, 9),
...     timespantools.Timespan(15, 23),
...     timespantools.Timespan(16, 21),
...     timespantools.Timespan(17, 19),
...     timespantools.Timespan(19, 20),
...     timespantools.Timespan(25, 30),
...     timespantools.Timespan(26, 29),
...     timespantools.Timespan(32, 34),
...     timespantools.Timespan(34, 37),
...     ])

Example 1. Explode timespans into the optimal number of non-overlapping inventories:

>>> for exploded_inventory in timespan_inventory.explode():
...     print(format(exploded_inventory))
...
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(13, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(17, 1),
            stop_offset=durationtools.Offset(19, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(19, 1),
            stop_offset=durationtools.Offset(20, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(34, 1),
            stop_offset=durationtools.Offset(37, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(16, 1),
            stop_offset=durationtools.Offset(21, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(25, 1),
            stop_offset=durationtools.Offset(30, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(8, 1),
            stop_offset=durationtools.Offset(9, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(15, 1),
            stop_offset=durationtools.Offset(23, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(26, 1),
            stop_offset=durationtools.Offset(29, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(32, 1),
            stop_offset=durationtools.Offset(34, 1),
            ),
        ]
    )

Example 2. Explode timespans into a less-than-optimal number of overlapping inventories:

>>> for exploded_inventory in timespan_inventory.explode(
...     inventory_count=2):
...     print(format(exploded_inventory))
...
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(13, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(15, 1),
            stop_offset=durationtools.Offset(23, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(25, 1),
            stop_offset=durationtools.Offset(30, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(34, 1),
            stop_offset=durationtools.Offset(37, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(8, 1),
            stop_offset=durationtools.Offset(9, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(16, 1),
            stop_offset=durationtools.Offset(21, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(17, 1),
            stop_offset=durationtools.Offset(19, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(19, 1),
            stop_offset=durationtools.Offset(20, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(26, 1),
            stop_offset=durationtools.Offset(29, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(32, 1),
            stop_offset=durationtools.Offset(34, 1),
            ),
        ]
    )

Example 3. Explode timespans into a greater-than-optimal number of non-overlapping inventories:

>>> for exploded_inventory in timespan_inventory.explode(
...     inventory_count=6):
...     print(format(exploded_inventory))
...
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(16, 1),
            stop_offset=durationtools.Offset(21, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(34, 1),
            stop_offset=durationtools.Offset(37, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(15, 1),
            stop_offset=durationtools.Offset(23, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(8, 1),
            stop_offset=durationtools.Offset(9, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(17, 1),
            stop_offset=durationtools.Offset(19, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(19, 1),
            stop_offset=durationtools.Offset(20, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(26, 1),
            stop_offset=durationtools.Offset(29, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(32, 1),
            stop_offset=durationtools.Offset(34, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(13, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(25, 1),
            stop_offset=durationtools.Offset(30, 1),
            ),
        ]
    )

Returns inventories.

(TypedList).extend(items)

Changes items to items and extends.

>>> integer_collection = datastructuretools.TypedList(
...     item_class=int)
>>> integer_collection.extend(('0', 1.0, 2, 3.14159))
>>> integer_collection[:]
[0, 1, 2, 3]

Returns none.

TimespanInventory.get_timespan_that_satisfies_time_relation(time_relation)

Get timespan that satisifies time_relation:

>>> timespan_1 = timespantools.Timespan(2, 5)
>>> time_relation = \
...     timespantools.timespan_2_starts_during_timespan_1(
...     timespan_1=timespan_1)
>>> timespan_inventory_1.get_timespan_that_satisfies_time_relation(
...     time_relation)
Timespan(start_offset=Offset(3, 1), stop_offset=Offset(6, 1))

Returns timespan when timespan inventory contains exactly one timespan that satisfies time_relation.

Raises exception when timespan inventory contains no timespan that satisfies time_relation.

Raises exception when timespan inventory contains more than one timespan that satisfies time_relation.

TimespanInventory.get_timespans_that_satisfy_time_relation(time_relation)

Get timespans that satisfy time_relation:

>>> timespan_1 = timespantools.Timespan(2, 8)
>>> time_relation = \
...     timespantools.timespan_2_starts_during_timespan_1(
...     timespan_1=timespan_1)
>>> result = \
...     timespan_inventory_1.get_timespans_that_satisfy_time_relation(
...     time_relation)
>>> print(format(result))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Returns new timespan inventory.

TimespanInventory.has_timespan_that_satisfies_time_relation(time_relation)

Is true when timespan inventory has timespan that satisfies time_relation:

>>> timespan_1 = timespantools.Timespan(2, 8)
>>> time_relation = \
...     timespantools.timespan_2_starts_during_timespan_1(
...     timespan_1=timespan_1)
>>> timespan_inventory_1.has_timespan_that_satisfies_time_relation(
...     time_relation)
True

Otherwise false:

>>> timespan_1 = timespantools.Timespan(10, 20)
>>> time_relation = \
...     timespantools.timespan_2_starts_during_timespan_1(
...     timespan_1=timespan_1)
>>> timespan_inventory_1.has_timespan_that_satisfies_time_relation(
...     time_relation)
False

Returns true or false.

(TypedList).index(item)

Changes item to item and returns index.

>>> pitch_collection = datastructuretools.TypedList(
...     items=('cqf', "as'", 'b,', 'dss'),
...     item_class=NamedPitch)
>>> pitch_collection.index("as'")
1

Returns index.

(TypedList).insert(i, item)

Changes item to item and inserts.

>>> integer_collection = datastructuretools.TypedList(
...     item_class=int)
>>> integer_collection.extend(('1', 2, 4.3))
>>> integer_collection[:]
[1, 2, 4]
>>> integer_collection.insert(0, '0')
>>> integer_collection[:]
[0, 1, 2, 4]
>>> integer_collection.insert(1, '9')
>>> integer_collection[:]
[0, 9, 1, 2, 4]

Returns none.

TimespanInventory.partition(include_tangent_timespans=False)

Partition timespans into inventories:

Example 1:

>>> print(format(timespan_inventory_1))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )
>>> for inventory in timespan_inventory_1.partition():
...     print(format(inventory))
...
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 2:

>>> print(format(timespan_inventory_2))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(16, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(12, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(-2, 1),
            stop_offset=durationtools.Offset(8, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(15, 1),
            stop_offset=durationtools.Offset(20, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(24, 1),
            stop_offset=durationtools.Offset(30, 1),
            ),
        ]
    )
>>> for inventory in timespan_inventory_2.partition():
...     print(format(inventory))
...
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(-2, 1),
            stop_offset=durationtools.Offset(8, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(16, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(12, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(15, 1),
            stop_offset=durationtools.Offset(20, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(24, 1),
            stop_offset=durationtools.Offset(30, 1),
            ),
        ]
    )

Example 3. Treat tangent timespans as part of the same group with include_tangent_timespans:

>>> for inventory in timespan_inventory_1.partition(
...     include_tangent_timespans=True):
...     print(format(inventory))
...
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Returns 0 or more inventories.

(TypedList).pop(i=-1)

Aliases list.pop().

TimespanInventory.reflect(axis=None)

Reflect timespans.

Example 1. Reflect timespans about timespan inventory axis:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> result = timespan_inventory.reflect()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(4, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(4, 1),
            stop_offset=durationtools.Offset(7, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(7, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 2. Reflect timespans about arbitrary axis:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> result = timespan_inventory.reflect(axis=Offset(15))
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(20, 1),
            stop_offset=durationtools.Offset(24, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(24, 1),
            stop_offset=durationtools.Offset(27, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(27, 1),
            stop_offset=durationtools.Offset(30, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.

(TypedList).remove(item)

Changes item to item and removes.

>>> integer_collection = datastructuretools.TypedList(
...     item_class=int)
>>> integer_collection.extend(('0', 1.0, 2, 3.14159))
>>> integer_collection[:]
[0, 1, 2, 3]
>>> integer_collection.remove('1')
>>> integer_collection[:]
[0, 2, 3]

Returns none.

TimespanInventory.remove_degenerate_timespans()

Remove degenerate timespans:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(5, 5),
...     timespantools.Timespan(5, 10),
...     timespantools.Timespan(5, 25),
...     ])
>>> result = timespan_inventory.remove_degenerate_timespans()
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(25, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.

TimespanInventory.repeat_to_stop_offset(stop_offset)

Repeat timespans to stop_offset:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> result = timespan_inventory.repeat_to_stop_offset(15)
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(10, 1),
            stop_offset=durationtools.Offset(13, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(13, 1),
            stop_offset=durationtools.Offset(15, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.

(TypedList).reverse()

Aliases list.reverse().

TimespanInventory.rotate(count)

Rotate by count contiguous timespans.

Example 1. Rotate by one timespan to the left:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 4),
...     timespantools.Timespan(4, 10),
...     ])
>>> result = timespan_inventory.rotate(-1)
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(1, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(1, 1),
            stop_offset=durationtools.Offset(7, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(7, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 2. Rotate by one timespan to the right:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 4),
...     timespantools.Timespan(4, 10),
...     ])
>>> result = timespan_inventory.rotate(1)
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(9, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(9, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.

TimespanInventory.round_offsets(multiplier, anchor=Left, must_be_well_formed=True)

Round offsets of timespans in inventory to multiples of multiplier:

Example 1:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 2),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> rounded_inventory = timespan_inventory.round_offsets(3)
>>> print(format(rounded_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(9, 1),
            ),
        ]
    )

Example 2:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 2),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> rounded_inventory = timespan_inventory.round_offsets(5)
>>> print(format(rounded_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(5, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 3:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 2),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> rounded_inventory = timespan_inventory.round_offsets(
...     5,
...     anchor=Right,
...     )
>>> print(format(rounded_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(-5, 1),
            stop_offset=durationtools.Offset(0, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(5, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 4:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 2),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> rounded_inventory = timespan_inventory.round_offsets(
...     5,
...     anchor=Right,
...     must_be_well_formed=False,
...     )
>>> print(format(rounded_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(0, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(5, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.

TimespanInventory.scale(multiplier, anchor=Left)

Scale timespan by multiplier relative to anchor.

Example 1. Scale timespans relative to timespan inventory start offset:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> result = timespan_inventory.scale(2)
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(9, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(14, 1),
            ),
        ]
    )

Example 2. Scale timespans relative to timespan inventory stop offset:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> result = timespan_inventory.scale(2, anchor=Right)
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(-3, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(2, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.

(TypedList).sort(cmp=None, key=None, reverse=False)

Aliases list.sort().

TimespanInventory.split_at_offset(offset)

Split timespans at offset:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])

Example 1:

>>> left, right = timespan_inventory.split_at_offset(4)
>>> print(format(left))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(4, 1),
            ),
        ]
    )
>>> print(format(right))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(4, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 2:

>>> left, right = timespan_inventory.split_at_offset(6)
>>> print(format(left))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        ]
    )
>>> print(format(right))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Example 3:

>>> left, right = timespan_inventory.split_at_offset(-1)
>>> print(format(left))
timespantools.TimespanInventory(
    []
    )
>>> print(format(right))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Returns inventories.

TimespanInventory.split_at_offsets(offsets)

Split timespans at offsets:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(4, 10),
...     timespantools.Timespan(15, 20),
...     ])
>>> offsets = [-1, 3, 6, 12, 13]

Example 1:

>>> for inventory in timespan_inventory.split_at_offsets(offsets):
...     print(format(inventory))
...
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(3, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(4, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(15, 1),
            stop_offset=durationtools.Offset(20, 1),
            ),
        ]
    )

Example 2:

>>> timespan_inventory = timespantools.TimespanInventory([])
>>> timespan_inventory.split_at_offsets(offsets)
[TimespanInventory([])]

Returns 1 or more inventories.

TimespanInventory.stretch(multiplier, anchor=None)

Stretch timespans by multiplier relative to anchor.

Example 1: Stretch timespans relative to timespan inventory start offset:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> result = timespan_inventory.stretch(2)
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(6, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(12, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(12, 1),
            stop_offset=durationtools.Offset(20, 1),
            ),
        ]
    )

Example 2: Stretch timespans relative to arbitrary anchor:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> result = timespan_inventory.stretch(2, anchor=Offset(8))
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(-8, 1),
            stop_offset=durationtools.Offset(-2, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(-2, 1),
            stop_offset=durationtools.Offset(4, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(4, 1),
            stop_offset=durationtools.Offset(12, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.

TimespanInventory.translate(translation=None)

Translate timespans by translation.

Example 1. Translate timespan by offset 50:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> result = timespan_inventory.translate(50)
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(50, 1),
            stop_offset=durationtools.Offset(53, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(53, 1),
            stop_offset=durationtools.Offset(56, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(56, 1),
            stop_offset=durationtools.Offset(60, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.

TimespanInventory.translate_offsets(start_offset_translation=None, stop_offset_translation=None)

Translate timespans by start_offset_translation and stop_offset_translation.

Example 1. Translate timespan start- and stop-offsets equally:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> result = timespan_inventory.translate_offsets(50, 50)
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(50, 1),
            stop_offset=durationtools.Offset(53, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(53, 1),
            stop_offset=durationtools.Offset(56, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(56, 1),
            stop_offset=durationtools.Offset(60, 1),
            ),
        ]
    )

Example 2. Translate timespan stop-offsets only:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 3),
...     timespantools.Timespan(3, 6),
...     timespantools.Timespan(6, 10),
...     ])
>>> result = timespan_inventory.translate_offsets(
...     stop_offset_translation=20)
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(23, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(3, 1),
            stop_offset=durationtools.Offset(26, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(6, 1),
            stop_offset=durationtools.Offset(30, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.

Special methods

TimespanInventory.__and__(timespan)

Keep material that intersects timespan:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 16),
...     timespantools.Timespan(5, 12),
...     timespantools.Timespan(-2, 8),
...     ])
>>> timespan = timespantools.Timespan(5, 10)
>>> result = timespan_inventory & timespan
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(8, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(5, 1),
            stop_offset=durationtools.Offset(10, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.

(TypedCollection).__contains__(item)

Is true when typed collection container item. Otherwise false.

Returns true or false.

(TypedList).__delitem__(i)

Aliases list.__delitem__().

Returns none.

(TypedCollection).__eq__(expr)

Is true when expr is a typed collection with items that compare equal to those of this typed collection. Otherwise false.

Returns true or false.

(AbjadObject).__format__(format_specification='')

Formats Abjad object.

Set format_specification to ‘’ or ‘storage’. Interprets ‘’ equal to ‘storage’.

Returns string.

(TypedList).__getitem__(i)

Aliases list.__getitem__().

Returns item.

(TypedCollection).__hash__()

Hashes typed collection.

Required to be explicitly redefined on Python 3 if __eq__ changes.

Returns integer.

(TypedList).__iadd__(expr)

Changes items in expr to items and extends.

>>> dynamic_collection = datastructuretools.TypedList(
...     item_class=Dynamic)
>>> dynamic_collection.append('ppp')
>>> dynamic_collection += ['p', 'mp', 'mf', 'fff']
>>> print(format(dynamic_collection))
datastructuretools.TypedList(
    [
        indicatortools.Dynamic(
            name='ppp',
            ),
        indicatortools.Dynamic(
            name='p',
            ),
        indicatortools.Dynamic(
            name='mp',
            ),
        indicatortools.Dynamic(
            name='mf',
            ),
        indicatortools.Dynamic(
            name='fff',
            ),
        ],
    item_class=indicatortools.Dynamic,
    )

Returns collection.

TimespanInventory.__illustrate__(key=None, range_=None, sortkey=None, scale=None)

Illustrates timespan inventory.

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 16),
...     timespantools.Timespan(5, 12),
...     timespantools.Timespan(-2, 8),
...     ])
>>> timespan_operand = timespantools.Timespan(6, 10)
>>> timespan_inventory = timespan_inventory - timespan_operand
>>> show(timespan_inventory, scale=0.5) 

Returns LilyPond file.

(TypedCollection).__iter__()

Iterates typed collection.

Returns generator.

(TypedCollection).__len__()

Length of typed collection.

Returns nonnegative integer.

(TypedCollection).__ne__(expr)

Is true when expr is not a typed collection with items equal to this typed collection. Otherwise false.

Returns true or false.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.

(TypedList).__reversed__()

Aliases list.__reversed__().

Returns generator.

(TypedList).__setitem__(i, expr)

Changes items in expr to items and sets.

>>> pitch_collection[-1] = 'gqs,'
>>> print(format(pitch_collection))
datastructuretools.TypedList(
    [
        pitchtools.NamedPitch('cqf'),
        pitchtools.NamedPitch("as'"),
        pitchtools.NamedPitch('b,'),
        pitchtools.NamedPitch('gqs,'),
        ],
    item_class=pitchtools.NamedPitch,
    )
>>> pitch_collection[-1:] = ["f'", "g'", "a'", "b'", "c''"]
>>> print(format(pitch_collection))
datastructuretools.TypedList(
    [
        pitchtools.NamedPitch('cqf'),
        pitchtools.NamedPitch("as'"),
        pitchtools.NamedPitch('b,'),
        pitchtools.NamedPitch("f'"),
        pitchtools.NamedPitch("g'"),
        pitchtools.NamedPitch("a'"),
        pitchtools.NamedPitch("b'"),
        pitchtools.NamedPitch("c''"),
        ],
    item_class=pitchtools.NamedPitch,
    )

Returns none.

TimespanInventory.__sub__(timespan)

Delete material that intersects timespan:

>>> timespan_inventory = timespantools.TimespanInventory([
...     timespantools.Timespan(0, 16),
...     timespantools.Timespan(5, 12),
...     timespantools.Timespan(-2, 8),
...     ])
>>> timespan = timespantools.Timespan(5, 10)
>>> result = timespan_inventory - timespan
>>> print(format(timespan_inventory))
timespantools.TimespanInventory(
    [
        timespantools.Timespan(
            start_offset=durationtools.Offset(-2, 1),
            stop_offset=durationtools.Offset(5, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(0, 1),
            stop_offset=durationtools.Offset(5, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(10, 1),
            stop_offset=durationtools.Offset(12, 1),
            ),
        timespantools.Timespan(
            start_offset=durationtools.Offset(10, 1),
            stop_offset=durationtools.Offset(16, 1),
            ),
        ]
    )

Operates in place and returns timespan inventory.