underfull_duration

auxjad.get.underfull_duration(selection: abjad.select.Selection) → abjad.duration.Duration

Returns an abjad.Duration representing the duration missing in the last measure of an input abjad.Selection which is not fully filled in.

Basic usage:

Returns the missing duration of the last measure of an abjad.Selection. If no time signature is encountered, it uses LilyPond’s fallback time signature of 4/4.

>>> container1 = abjad.Container(r"c'4 d'4 e'4 f'4")
>>> container2 = abjad.Container(r"c'4 d'4 e'4")
>>> container3 = abjad.Container(r"c'4 d'4 e'4 f'4 | c'4")
>>> container4 = abjad.Container(r"c'4 d'4 e'4 f'4 | c'4 d'4 e'4 f'4")
>>> auxjad.get.underfull_duration(container1[:])
0
>>> auxjad.get.underfull_duration(container2[:])
1/4
>>> auxjad.get.underfull_duration(container3[:])
3/4
>>> auxjad.get.underfull_duration(container4[:])
0

Note

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

>>> container = abjad.Container(r"c'4 d'4 e'4")
>>> auxjad.get.underfull_duration(container[:])
1/4
>>> abjad.get.underfull_duration(container[:])
1/4

Time signature changes:

Handles any time signatures as well as changes of time signature.

>>> container1 = abjad.Container(r"\time 4/4 c'4 d'4 e'4 f'4")
>>> container2 = abjad.Container(r"\time 3/4 a2. \time 2/4 r2")
>>> container3 = abjad.Container(r"\time 5/4 g1 ~ g4 \time 4/4 af'2")
>>> container4 = abjad.Container(r"\time 6/8 c'2 ~ c'8")
>>> auxjad.get.underfull_duration(container1[:])
0
>>> auxjad.get.underfull_duration(container2[:])
0
>>> auxjad.get.underfull_duration(container3[:])
1/2
>>> auxjad.get.underfull_duration(container4[:])
1/8

Partial time signatures:

Correctly handles partial time signatures.

>>> container = abjad.Container(r"c'4 d'4 e'4 f'4")
>>> time_signature = abjad.TimeSignature((3, 4), partial=(1, 4))
>>> abjad.attach(time_signature, container[0])
>>> auxjad.get.underfull_duration(container[:])
0

Multi-measure rests:

It also handles multi-measure rests.

>>> container1 = abjad.Container(r"R1")
>>> container2 = abjad.Container(r"\time 3/4 R1 * 3/4 \time 2/4 r2")
>>> container3 = abjad.Container(r"\time 5/4 R1 * 5/4 \time 4/4 g''4")
>>> container4 = abjad.Container(r"\time 6/8 R1 * 1/2")
>>> auxjad.get.underfull_duration(container1[:])
0
>>> auxjad.get.underfull_duration(container2[:])
0
>>> auxjad.get.underfull_duration(container3[:])
3/4
>>> auxjad.get.underfull_duration(container4[:])
1/4

Error

If a selection is malformed, i.e. it has an underfilled measure before a time signature change, the function raises a ValueError exception. This is also the case when a selection starts in the middle of a measure.

>>> container = abjad.Container(r"\time 5/4 g''1 \time 4/4 f'1")
>>> auxjad.get.underfull_duration(container[:])
ValueError: 'selection' is malformed, with an underfull measure
preceding a time signature change

Warning

The input container must be a contiguous logical voice. When dealing with a container with multiple subcontainers (e.g. a score containing multiple staves), the best approach is to cycle through these subcontainers, applying this function to them individually.