Iteration

digraph InheritanceGraph { graph [bgcolor=transparent, color=lightsteelblue2, fontname=Arial, fontsize=10, outputorder=edgesfirst, overlap=prism, penwidth=2, rankdir=LR, splines=spline, style="dashed, rounded", truecolor=true]; node [colorscheme=pastel19, fontname=Arial, fontsize=10, height=0, penwidth=2, shape=box, style="filled, rounded", width=0]; edge [color=lightslategrey, penwidth=1]; subgraph "cluster_abjad.core" { graph [label="abjad.core"]; node [color=1]; "abjad.core.Iteration.Iteration" [URL="../api/abjad/core/Iteration.html#abjad.core.Iteration.Iteration", color=black, fontcolor=white, label=Iteration, target=_top]; } subgraph "cluster_abjad.system" { graph [label="abjad.system"]; node [color=2]; "abjad.system.AbjadObject.AbjadObject" [URL="../api/abjad/core/../system/AbjadObject.html#abjad.system.AbjadObject.AbjadObject", label="Abjad\nObject", target=_top]; } subgraph cluster_builtins { graph [label=builtins]; node [color=3]; "builtins.object" [URL="https://docs.python.org/3.6/library/functions.html#object", label=object, target=_top]; } "abjad.system.AbjadObject.AbjadObject" -> "abjad.core.Iteration.Iteration"; "builtins.object" -> "abjad.system.AbjadObject.AbjadObject"; }

class abjad.core.Iteration.Iteration(client=None)

Iteration.

Iterates leaves:

>>> staff = abjad.Staff("c'4 e'4 d'4 f'4")
>>> abjad.show(staff) 
>>> for leaf in abjad.iterate(staff).leaves():
...     leaf
... 
Note("c'4")
Note("e'4")
Note("d'4")
Note("f'4")

Attributes Summary

client Gets client.
components Iterates components.
leaf_pairs Iterates leaf pairs.
leaves Iterates leaves.
logical_ties Iterates logical ties.
out_of_range Iterates out-of-range notes and chords.
pitch_pairs Iterates pitch pairs.
pitches Iterates pitches.
spanners Iterates spanners.
timeline Iterates timeline.
vertical_moments Iterates vertical moments.

Special methods

(AbjadObject).__format__(format_specification='')

Formats Abjad object.

Set format_specification to '' or 'storage'. Interprets '' equal to 'storage'.

Returns string.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.


Methods

components(prototype=None, grace_notes=None, reverse=False)

Iterates components.

Iterates notes:

>>> staff = abjad.Staff()
>>> staff.append(abjad.Measure((2, 8), "c'8 d'8"))
>>> staff.append(abjad.Measure((2, 8), "e'8 f'8"))
>>> staff.append(abjad.Measure((2, 8), "g'8 a'8"))
>>> abjad.show(staff) 
>>> agent = abjad.iterate(staff)
>>> for note in agent.components(prototype=abjad.Note):
...     note
... 
Note("c'8")
Note("d'8")
Note("e'8")
Note("f'8")
Note("g'8")
Note("a'8")

Iterates grace notes and nongrace notes:

>>> voice = abjad.Voice("c'8 [ d'8 e'8 f'8 ]")
>>> container = abjad.GraceContainer("cf''16 bf'16")
>>> abjad.attach(container, voice[1])
>>> container = abjad.AfterGraceContainer("af'16 gf'16")
>>> abjad.attach(container, voice[1])
>>> abjad.show(voice) 
>>> for component in abjad.iterate(voice).components():
...     component
... 
Voice("c'8 d'8 e'8 f'8")
Note("c'8")
Note("cf''16")
Note("bf'16")
Note("d'8")
Note("af'16")
Note("gf'16")
Note("e'8")
Note("f'8")

Iterates components in reverse:

>>> voice = abjad.Voice("c'8 [ d'8 e'8 f'8 ]")
>>> container = abjad.GraceContainer("cf''16 bf'16")
>>> abjad.attach(container, voice[1])
>>> container = abjad.AfterGraceContainer("af'16 gf'16")
>>> abjad.attach(container, voice[1])
>>> abjad.show(voice) 
>>> for component in abjad.iterate(voice).components(
...     reverse=True,
...     ):
...     component
... 
Voice("c'8 d'8 e'8 f'8")
Note("f'8")
Note("e'8")
Note("gf'16")
Note("af'16")
Note("d'8")
Note("bf'16")
Note("cf''16")
Note("c'8")

Returns generator.

leaf_pairs()

Iterates leaf pairs.

Iterates leaf pairs:

>>> score = abjad.Score()
>>> score.append(abjad.Staff("c'8 d'8 e'8 f'8 g'4"))
>>> score.append(abjad.Staff("c4 a,4 g,4"))
>>> abjad.attach(abjad.Clef('bass'), score[1][0])
>>> abjad.show(score) 
>>> for leaf_pair in abjad.iterate(score).leaf_pairs():
...     leaf_pair
... 
Selection([Note("c'8"), Note('c4')])
Selection([Note("c'8"), Note("d'8")])
Selection([Note('c4'), Note("d'8")])
Selection([Note("d'8"), Note("e'8")])
Selection([Note("d'8"), Note('a,4')])
Selection([Note('c4'), Note("e'8")])
Selection([Note('c4'), Note('a,4')])
Selection([Note("e'8"), Note('a,4')])
Selection([Note("e'8"), Note("f'8")])
Selection([Note('a,4'), Note("f'8")])
Selection([Note("f'8"), Note("g'4")])
Selection([Note("f'8"), Note('g,4')])
Selection([Note('a,4'), Note("g'4")])
Selection([Note('a,4'), Note('g,4')])
Selection([Note("g'4"), Note('g,4')])

Iterates leaf pairs left-to-right and top-to-bottom.

Returns generator.

leaves(prototype=None, grace_notes=None, pitched=None, reverse=False)

Iterates leaves.

Iterates leaves:

>>> staff = abjad.Staff()
>>> staff.append(abjad.Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(abjad.Measure((2, 8), "af'8 r8"))
>>> staff.append(abjad.Measure((2, 8), "r8 gf'8"))
>>> abjad.show(staff) 
>>> for leaf in abjad.iterate(staff).leaves():
...     leaf
... 
Chord("<c' bf'>8")
Chord("<g' a'>8")
Note("af'8")
Rest('r8')
Rest('r8')
Note("gf'8")

Iterates grace notes and nongrace notes:

>>> voice = abjad.Voice("c'8 [ d'8 e'8 f'8 ]")
>>> container = abjad.GraceContainer("cf''16 bf'16")
>>> abjad.attach(container, voice[1])
>>> container = abjad.AfterGraceContainer("af'16 gf'16")
>>> abjad.attach(container, voice[1])
>>> abjad.show(voice) 
>>> for leaf in abjad.iterate(voice).leaves():
...     leaf
... 
Note("c'8")
Note("cf''16")
Note("bf'16")
Note("d'8")
Note("af'16")
Note("gf'16")
Note("e'8")
Note("f'8")

Iterates grace notes only:

>>> voice = abjad.Voice("c'8 [ d'8 e'8 f'8 ]")
>>> container = abjad.GraceContainer("cf''16 bf'16")
>>> abjad.attach(container, voice[1])
>>> container = abjad.AfterGraceContainer("af'16 gf'16")
>>> abjad.attach(container, voice[1])
>>> abjad.show(voice) 
>>> for leaf in abjad.iterate(voice).leaves(grace_notes=True):
...     leaf
... 
Note("cf''16")
Note("bf'16")
Note("af'16")
Note("gf'16")

Iterates nongrace notes only:

>>> voice = abjad.Voice("c'8 [ d'8 e'8 f'8 ]")
>>> container = abjad.GraceContainer("cf''16 bf'16")
>>> abjad.attach(container, voice[1])
>>> container = abjad.AfterGraceContainer("af'16 gf'16")
>>> abjad.attach(container, voice[1])
>>> abjad.show(voice) 
>>> for leaf in abjad.iterate(voice).leaves(grace_notes=False):
...     leaf
... 
Note("c'8")
Note("d'8")
Note("e'8")
Note("f'8")

Iterates pitched leaves only:

>>> staff = abjad.Staff()
>>> staff.append(abjad.Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(abjad.Measure((2, 8), "af'8 r8"))
>>> staff.append(abjad.Measure((2, 8), "r8 gf'8"))
>>> abjad.show(staff) 
>>> for leaf in abjad.iterate(staff).leaves(pitched=True):
...     leaf
... 
Chord("<c' bf'>8")
Chord("<g' a'>8")
Note("af'8")
Note("gf'8")

Iterates nonpitched leaves only:

>>> staff = abjad.Staff()
>>> staff.append(abjad.Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(abjad.Measure((2, 8), "af'8 r8"))
>>> staff.append(abjad.Measure((2, 8), "r8 gf'8"))
>>> abjad.show(staff) 
>>> for leaf in abjad.iterate(staff).leaves(pitched=False):
...     leaf
... 
Rest('r8')
Rest('r8')

Iterates leaves in reverse:

>>> staff = abjad.Staff()
>>> staff.append(abjad.Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(abjad.Measure((2, 8), "af'8 r8"))
>>> staff.append(abjad.Measure((2, 8), "r8 gf'8"))
>>> abjad.show(staff) 
>>> for leaf in abjad.iterate(staff).leaves(reverse=True):
...     leaf
... 
Note("gf'8")
Rest('r8')
Rest('r8')
Note("af'8")
Chord("<g' a'>8")
Chord("<c' bf'>8")

Returns generator.

logical_ties(grace_notes=None, nontrivial=None, pitched=None, reverse=False)

Iterates logical ties.

Iterates logical ties:

>>> string = r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16"
>>> staff = abjad.Staff(string)
>>> abjad.show(staff) 
>>> for logical_tie in abjad.iterate(staff).logical_ties():
...     logical_tie
... 
LogicalTie([Note("c'4"), Note("c'16")])
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'4"), Note("f'16")])

Iterates pitched logical ties:

>>> string = r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16"
>>> staff = abjad.Staff(string)
>>> abjad.show(staff) 
>>> for logical_tie in abjad.iterate(staff).logical_ties(
...     pitched=True,
...     ):
...     logical_tie
... 
LogicalTie([Note("c'4"), Note("c'16")])
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'4"), Note("f'16")])

Iterates nontrivial logical ties:

>>> string = r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16"
>>> staff = abjad.Staff(string)
>>> abjad.show(staff) 
>>> for logical_tie in abjad.iterate(staff).logical_ties(
...     nontrivial=True,
...     ):
...     logical_tie
... 
LogicalTie([Note("c'4"), Note("c'16")])
LogicalTie([Note("f'4"), Note("f'16")])

Iterates trivial logical ties:

>>> string = r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16"
>>> staff = abjad.Staff(string)
>>> abjad.show(staff) 
>>> for logical_tie in abjad.iterate(staff).logical_ties(
...     nontrivial=False,
...     ):
...     logical_tie
... 
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8")])

Iterates logical ties together with grace notes and after grace notes:

>>> voice = abjad.Voice("c'8 [ d'8 e'8 f'8 ]")
>>> container = abjad.GraceContainer("cf''16 bf'16")
>>> abjad.attach(container, voice[1])
>>> container = abjad.AfterGraceContainer("af'16 gf'16")
>>> abjad.attach(container, voice[1])
>>> abjad.show(voice) 
>>> for item in abjad.iterate(voice).logical_ties():
...     item
... 
LogicalTie([Note("c'8")])
LogicalTie([Note("cf''16")])
LogicalTie([Note("bf'16")])
LogicalTie([Note("d'8")])
LogicalTie([Note("af'16")])
LogicalTie([Note("gf'16")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'8")])

Iterates logical ties in reverse:

>>> string = r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16"
>>> staff = abjad.Staff(string)
>>> abjad.show(staff) 
>>> for logical_tie in abjad.iterate(staff).logical_ties(
...     reverse=True,
...     ):
...     logical_tie
... 
LogicalTie([Note("f'4"), Note("f'16")])
LogicalTie([Note("e'8")])
LogicalTie([Note("d'8")])
LogicalTie([Note("c'4"), Note("c'16")])

REGRESSION: yields logical tie even when leaves are missing in input:

>>> voice = abjad.Voice("c'8 [ ~ c' ~ c' d' ]")
>>> abjad.show(voice) 
>>> selection = voice[:2]
>>> for logical_tie in abjad.iterate(selection).logical_ties():
...     logical_tie
... 
LogicalTie([Note("c'8"), Note("c'8"), Note("c'8")])

Returns generator.

out_of_range()

Iterates out-of-range notes and chords.

>>> staff = abjad.Staff("c'8 r8 <d fs>8 r8")
>>> violin = abjad.Violin()
>>> abjad.attach(violin, staff[0])
>>> abjad.show(staff) 
>>> for leaf in abjad.iterate(staff).out_of_range():
...     leaf
... 
Chord('<d fs>8')

Returns generator.

pitch_pairs()

Iterates pitch pairs.

Iterates note pitch pairs:

>>> score = abjad.Score()
>>> score.append(abjad.Staff("c'8 d' e' f' g'4"))
>>> score.append(abjad.Staff("c4 a, g,"))
>>> abjad.attach(abjad.Clef('bass'), score[1][0])
>>> abjad.show(score) 
>>> for pair in abjad.iterate(score).pitch_pairs():
...     pair
... 
PitchSegment("c' c")
PitchSegment("c' d'")
PitchSegment("c d'")
PitchSegment("d' e'")
PitchSegment("d' a,")
PitchSegment("c e'")
PitchSegment("c a,")
PitchSegment("e' a,")
PitchSegment("e' f'")
PitchSegment("a, f'")
PitchSegment("f' g'")
PitchSegment("f' g,")
PitchSegment("a, g'")
PitchSegment("a, g,")
PitchSegment("g' g,")

Iterates chord pitch pairs:

>>> staff = abjad.Staff("<c' d' e'>4 <f'' g''>4")
>>> for pair in abjad.iterate(staff).pitch_pairs():
...     pair
... 
PitchSegment("c' d'")
PitchSegment("c' e'")
PitchSegment("d' e'")
PitchSegment("c' f''")
PitchSegment("c' g''")
PitchSegment("d' f''")
PitchSegment("d' g''")
PitchSegment("e' f''")
PitchSegment("e' g''")
PitchSegment("f'' g''")

Returns generator.

pitches()

Iterates pitches.

Iterates pitches in container:

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> beam = abjad.Beam()
>>> abjad.attach(beam, staff[:])
>>> abjad.show(staff) 
>>> for pitch in abjad.iterate(staff).pitches():
...     pitch
... 
NamedPitch("c'")
NamedPitch("d'")
NamedPitch("e'")
NamedPitch("f'")

Iterates pitches in spanner:

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> beam = abjad.Beam()
>>> abjad.attach(beam, staff[:])
>>> abjad.show(staff) 
>>> for pitch in abjad.iterate(beam).pitches():
...     pitch
... 
NamedPitch("c'")
NamedPitch("d'")
NamedPitch("e'")
NamedPitch("f'")

Iterates pitches in pitch set:

>>> pitch_set = abjad.PitchSet([0, 2, 4, 5])
>>> for pitch in abjad.iterate(pitch_set).pitches():
...     pitch
... 
NumberedPitch(0)
NumberedPitch(2)
NumberedPitch(4)
NumberedPitch(5)

Iterates different types of object in tuple:

>>> pitches = (
...     abjad.NamedPitch("c'"),
...     abjad.Note("d'4"),
...     abjad.Chord("<e' fs' g>4"),
...     )
>>> for pitch in abjad.iterate(pitches).pitches():
...     pitch
... 
NamedPitch("c'")
NamedPitch("d'")
NamedPitch('g')
NamedPitch("e'")
NamedPitch("fs'")

Returns generator.

spanners(prototype=None, reverse=False)

Iterates spanners.

Iterates spanners:

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8 g'8 a'8 f'8 b'8 c''8")
>>> abjad.attach(abjad.Slur(), staff[:4])
>>> abjad.attach(abjad.Slur(), staff[4:])
>>> abjad.attach(abjad.Beam(), staff[:])
>>> abjad.show(staff) 
>>> for spanner in abjad.iterate(staff).spanners():
...     spanner
... 
Beam("c'8, d'8, ... [5] ..., b'8, c''8", durations=(), span_beam_count=1)
Slur("c'8, d'8, e'8, f'8")
Slur("g'8, a'8, f'8, b'8, c''8")

Iterates spanners in reverse:

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8 g'8 a'8 f'8 b'8 c''8")
>>> abjad.attach(abjad.Slur(), staff[:4])
>>> abjad.attach(abjad.Slur(), staff[4:])
>>> abjad.attach(abjad.Beam(), staff[:])
>>> abjad.show(staff) 
>>> for spanner in abjad.iterate(staff).spanners(reverse=True):
...     spanner
... 
Beam("c'8, d'8, ... [5] ..., b'8, c''8", durations=(), span_beam_count=1)
Slur("g'8, a'8, f'8, b'8, c''8")
Slur("c'8, d'8, e'8, f'8")

Returns generator.

timeline(prototype=None, reverse=False)

Iterates timeline.

Timeline-iterates leaves:

>>> score = abjad.Score()
>>> score.append(abjad.Staff("c'4 d'4 e'4 f'4"))
>>> score.append(abjad.Staff("g'8 a'8 b'8 c''8"))
>>> abjad.show(score) 
>>> for leaf in abjad.iterate(score).timeline():
...     leaf
... 
Note("c'4")
Note("g'8")
Note("a'8")
Note("d'4")
Note("b'8")
Note("c''8")
Note("e'4")
Note("f'4")

Timeline-iterates leaves in reverse:

>>> score = abjad.Score()
>>> score.append(abjad.Staff("c'4 d'4 e'4 f'4"))
>>> score.append(abjad.Staff("g'8 a'8 b'8 c''8"))
>>> abjad.show(score) 
>>> for leaf in abjad.iterate(score).timeline(reverse=True):
...     leaf
... 
Note("f'4")
Note("e'4")
Note("d'4")
Note("c''8")
Note("b'8")
Note("c'4")
Note("a'8")
Note("g'8")

Timeline-iterates leaves together grace notes:

>>> voice = abjad.Voice("c'8 [ d'8 e'8 f'8 ]")
>>> container = abjad.GraceContainer("cf''16 bf'16")
>>> abjad.attach(container, voice[1])
>>> abjad.show(voice) 
>>> for component in abjad.iterate(voice).timeline():
...     component
... 
Note("c'8")
Note("d'8")
Note("e'8")
Note("f'8")

Todo

Incorrect because grace notes are not included.

Iterates leaves when prototype is none.

vertical_moments(reverse=False)

Iterates vertical moments.

Iterates vertical moments:

>>> score = abjad.Score([])
>>> staff = abjad.Staff(r"\times 4/3 { d''8 c''8 b'8 }")
>>> score.append(staff)
>>> staff_group = abjad.StaffGroup([])
>>> staff_group.lilypond_type = 'PianoStaff'
>>> staff_group.append(abjad.Staff("a'4 g'4"))
>>> staff_group.append(abjad.Staff(r"""\clef "bass" f'8 e'8 d'8 c'8"""))
>>> score.append(staff_group)
>>> abjad.show(score) 
>>> for vertical_moment in abjad.iterate(score).vertical_moments():
...     vertical_moment.leaves
... 
Selection([Note("d''8"), Note("a'4"), Note("f'8")])
Selection([Note("d''8"), Note("a'4"), Note("e'8")])
Selection([Note("c''8"), Note("a'4"), Note("e'8")])
Selection([Note("c''8"), Note("g'4"), Note("d'8")])
Selection([Note("b'8"), Note("g'4"), Note("d'8")])
Selection([Note("b'8"), Note("g'4"), Note("c'8")])
>>> for vertical_moment in abjad.iterate(staff_group).vertical_moments():
...     vertical_moment.leaves
... 
Selection([Note("a'4"), Note("f'8")])
Selection([Note("a'4"), Note("e'8")])
Selection([Note("g'4"), Note("d'8")])
Selection([Note("g'4"), Note("c'8")])

Iterates vertical moments in reverse:

>>> score = abjad.Score([])
>>> staff = abjad.Staff(r"\times 4/3 { d''8 c''8 b'8 }")
>>> score.append(staff)
>>> staff_group = abjad.StaffGroup([])
>>> staff_group.lilypond_type = 'PianoStaff'
>>> staff_group.append(abjad.Staff("a'4 g'4"))
>>> staff_group.append(abjad.Staff(r"""\clef "bass" f'8 e'8 d'8 c'8"""))
>>> score.append(staff_group)
>>> abjad.show(score) 
>>> agent = abjad.iterate(score)
>>> for vertical_moment in agent.vertical_moments(
...     reverse=True,
...     ):
...     vertical_moment.leaves
... 
Selection([Note("b'8"), Note("g'4"), Note("c'8")])
Selection([Note("b'8"), Note("g'4"), Note("d'8")])
Selection([Note("c''8"), Note("g'4"), Note("d'8")])
Selection([Note("c''8"), Note("a'4"), Note("e'8")])
Selection([Note("d''8"), Note("a'4"), Note("e'8")])
Selection([Note("d''8"), Note("a'4"), Note("f'8")])
>>> agent = abjad.iterate(staff_group)
>>> for vertical_moment in agent.vertical_moments(
...     reverse=True,
...     ):
...     vertical_moment.leaves
... 
Selection([Note("g'4"), Note("c'8")])
Selection([Note("g'4"), Note("d'8")])
Selection([Note("a'4"), Note("e'8")])
Selection([Note("a'4"), Note("f'8")])

Returns generator.


Read-only properties

client

Gets client.

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> abjad.iterate(staff[:2]).client
Selection([Note("c'4"), Note("d'4")])

Returns component or selection.