extend_notes

auxjad.mutate.extend_notes(container: abjad.score.Container, max_note_duration: abjad.duration.Duration, *, gap: abjad.duration.Duration = Duration(0, 1), gap_before_end: bool = False, use_multimeasure_rests: bool = True, rewrite_meter: bool = True) → None

Mutates an input abjad.Container (or child class) in place and has no return value; this function extends all logical ties (notes and chords) up to a given maximum note duration.

Basic usage:

This function will extend the duration of each logical tie up until the allowed maximum duration.

>>> staff = abjad.Staff(r"c'16 r2... d'8 r2.. e'8. r16 r2. f'4 r2.")
>>> abjad.show(staff)

>>> auxjad.mutate.extend_notes(staff, abjad.Duration((1, 4)))
>>> abjad.show(staff)

Note

Auxjad automatically adds this function as an extension function to abjad.mutate. It can thus be used from either auxjad.mutate or abjad.mutate namespaces. Therefore, the two lines below are equivalent:

>>> auxjad.mutate.extend_notes(staff)
>>> abjad.mutate.extend_notes(staff)

Longer notes:

This function will not alter the length of logical ties that are already equal to or larger than the maximum extension duration.

>>> staff = abjad.Staff(r"c'16 r2... d'2 r2 e'2. r4 f'1")
>>> abjad.show(staff)

>>> auxjad.mutate.extend_notes(staff, abjad.Duration((1, 4)))
>>> abjad.show(staff)

Chords:

This function works with chords:

>>> staff = abjad.Staff(
...     r"\time 3/4 c'8 r8 r2 r4 <d' e' f'>4 r4 r8 g'16 r16 r2"
... )
>>> abjad.show(staff)

>>> auxjad.mutate.extend_notes(staff, abjad.Duration((2, 4)))
>>> abjad.show(staff)

Second positional argument:

The second positional argument must be an abjad.Duration or objects that can instantiate an abjad.Duration, such as str, tuple, int, and float. The notes will be extended up to that duration, or until the next note if the full duration is not possible:

>>> staff = abjad.Staff(
...     r"c'16 r4.. d'16 r4.. e'16 r2... f'16 r4.. g'16 r4.."
... )
>>> abjad.show(staff)

>>> auxjad.mutate.extend_notes(staff, abjad.Duration((3, 4)))
>>> abjad.show(staff)

Dynamics:

Dynamics are preserved:

>>> staff = abjad.Staff(
...     r"c'16\ppp r2... d'16\ff r2... e'16\f r2... f'16\mp r2..."
... )
>>> abjad.show(staff)

>>> auxjad.mutate.extend_notes(staff, abjad.Duration((1, 4)))
>>> abjad.show(staff)

Time signatures changes:

This function handles time signature changes:

>>> staff = abjad.Staff(
...     r"\time 3/4 c'16 r8. r2 "
...     r"\time 2/4 d'8 r8 e'8 r8 "
...     r"\time 3/4 r2 f'16 r8."
... )
>>> abjad.show(staff)

>>> auxjad.mutate.extend_notes(staff, abjad.Duration((3, 4)))
>>> abjad.show(staff)

gap:

Use the argument gap to ensure that there a minimum gap is left between leaves when extending them:

>>> staff = abjad.Staff(r"c'4 r4 d'4 r4 e'4 r2.")
>>> abjad.show(staff)

>>> auxjad.mutate.extend_notes(staff,
...                            abjad.Duration((2, 4)),
...                            gap=abjad.Duration((1, 16)),
...                            )
>>> abjad.show(staff)

Note that this function will not shorten leaves, so previous leaves that had no gaps will still have no gaps between them. gap will only affect leaves that are extended by the function.

>>> staff = abjad.Staff(r"c'2 d'4 r4 e'4 r4 f'2 ~ f'2 r2")
>>> abjad.show(staff)

>>> auxjad.mutate.extend_notes(staff,
...                            abjad.Duration((2, 4)),
...                            gap=abjad.Duration((1, 16)),
...                            )
>>> abjad.show(staff)

gap_before_end:

By default, a when gap is present it is not applied to the last pitched at the end of the container.

>>> staff = abjad.Staff(r"c'16 r8. d'16 r8. e'16 r8. f'16 r8.")
>>> auxjad.mutate.extend_notes(staff,
...                            abjad.Duration((1, 4)),
...                            gap=abjad.Duration((1, 16)),
...                            )
>>> abjad.show(staff)

Set gap_before_end to True to ensure that there is also a minimum gap at the end of the container.

>>> staff = abjad.Staff(r"c'16 r8. d'16 r8. e'16 r8. f'16 r8.")
>>> auxjad.mutate.extend_notes(staff,
...                            abjad.Duration((1, 4)),
...                            gap=abjad.Duration((1, 16)),
...                            gap_before_end=True,
...                            )
>>> abjad.show(staff)

use_multimeasure_rests:

By default, this function uses multi-measure rests

>>> staff = abjad.Staff(r"\time 3/4 r8 c'8 r4 c'4 r2. r8 c'8 r2 r2.")
>>> auxjad.mutate.extend_notes(staff, abjad.Duration((2, 4)))
>>> abjad.show(staff)

Set the keyword argument use_multimeasure_rests to False to disable this behaviour.

>>> staff = abjad.Staff(r"\time 3/4 r8 c'8 r4 c'4 r2. r8 c'8 r2 r2.")
>>> auxjad.mutate.extend_notes(staff,
...                            abjad.Duration((2, 4)),
...                            use_multimeasure_rests=False,
...                            )
>>> abjad.show(staff)

rewrite_meter

By default, this function applies auxjad.mutate.auto_rewrite_meter() at the end of its process.

>>> staff = abjad.Staff(r"c'16 r4.. d'16 r4..")
>>> abjad.show(staff)

>>> auxjad.mutate.extend_notes(staff, abjad.Duration((1, 4)))
>>> abjad.show(staff)

Set rewrite_meter to False to disable this. The main reason for doing this is performance: when multiple mutations are being applied, it is faster to rewrite the meter just once at the end.

>>> staff = abjad.Staff(r"c'16 r4.. d'16 r4..")
>>> auxjad.mutate.extend_notes(staff,
...                            abjad.Duration((1, 4)),
...                            rewrite_meter=False,
...                            )
>>> abjad.show(staff)

Warning

This function does not support tuplets. Using a container with one or more tuplets will result in a ValueError exception being raised:

>>> staff = abjad.Staff(r"c'4 r4 \times 2/3 {r4 d'4 r4} e'4 r2.")
>>> auxjad.mutate.extend_notes(staff, abjad.Duration((1, 4)))
ValueError: first positional argument contains one ore more tuplets,
which are not currently supported