music21/

stream.rs

//! Music on a timeline: music21's `stream.Stream` and the subclasses it
//! nests inside one another.
//!
//! A [`Stream`] is a list of things at quarter-length offsets, and one of
//! those things may be another stream: a score holds parts, a part holds
//! measures, a measure holds voices and notes. [`Stream::flatten`] dissolves
//! that nesting into one timeline the way music21's does, adding each
//! stream's own offset to its contents'.
//!
//! **What is deliberately not here is music21's *sites*.** There an object
//! can sit in several streams at once and carry a different offset in each,
//! which is why it needs a back-reference to every stream holding it and why
//! `getContextByClass` has a graph to walk. A stream here *owns* what it
//! holds, so the nesting is a tree; asking what key or metre is in force at
//! an offset is then a backwards look through the flattened timeline rather
//! than a search through a graph. That is the same answer for music that is
//! written once, which is all a stream built here can be.
//!
//! Where an element sits is asked for, not stored: [`Stream::placed`]
//! answers each element with its offset, its measure offset and the key,
//! metre and tempo in force, as one [`Placed`](crate::stream::Placed) value. music21's author
//! names keeping objects and sites apart this way as what he would do
//! again.

mod analyze;
pub(crate) mod chordify;
mod classes;
mod consecutive;
mod editing;
mod ends;
pub(crate) mod exact;
mod filling;
mod lookups;
mod lyrics;
mod opus;
mod placed;
mod queries;
mod repeats;
mod seconds;
mod selection;
mod slicing;
mod sounding;
mod span;
mod splitting;
mod template;
mod ties;
mod voices;

pub use analyze::Analysis;
pub use chordify::ChordifyOptions;
pub use consecutive::{ConsecutiveOptions, MelodicInterval};
pub use editing::Anchor;
pub use lyrics::{LyricsOptions, SungAt, SungLyric, SungPlace};
pub use placed::Placed;
pub use queries::OffsetMapEntry;
pub use repeats::Expander;
pub use seconds::TempoSpan;
pub use span::OffsetSpan;
pub use splitting::InForce;
pub use template::{TemplateOptions, removed_by_default};
pub use voices::VoiceAllocation;

use crate::{
    bar::{Barline, Ending},
    chord::Chord,
    chordsymbol::ChordSymbol,
    clef::Clef,
    defaults::{FloatType, IntegerType},
    duration::Duration,
    dynamics::Dynamic,
    error::Result,
    expressions::{RehearsalMark, TextExpression},
    instrument::Instrument,
    interval::Interval,
    key::{Key, KeySignature},
    metadata::Metadata,
    meter::TimeSignature,
    note::Note,
    percussion::{PercussionChord, Unpitched},
    pitch::Pitch,
    repeat::RepeatExpression,
    rest::Rest,
    spanner::{PedalObject, Spanner},
    tempo::{MetricModulation, MetronomeMark, TempoText},
};

/// Which of music21's `Stream` subclasses a stream stands for.
///
/// music21 makes each of these a class of its own; they carry no behaviour
/// that a tag does not, and a tag is what the filters here need.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
pub enum StreamKind {
    /// A stream with no particular role: music21's `Stream`.
    #[default]
    Stream,
    /// One independent line inside a measure.
    Voice,
    /// One bar.
    Measure,
    /// One instrument's line through the piece.
    Part,
    /// One staff of a part written on several.
    PartStaff,
    /// One line of a page's staves: music21's `System`, which only its
    /// optical recognition and Capella reader build.
    System,
    /// A whole piece, holding parts.
    Score,
    /// A collection of scores.
    Opus,
}

impl StreamKind {
    /// Every kind, in music21's order of containment.
    pub const ALL: [StreamKind; 8] = [
        StreamKind::Stream,
        StreamKind::Voice,
        StreamKind::Measure,
        StreamKind::Part,
        StreamKind::PartStaff,
        StreamKind::System,
        StreamKind::Score,
        StreamKind::Opus,
    ];

    /// music21's class name for this kind.
    pub fn as_str(self) -> &'static str {
        match self {
            StreamKind::Stream => "Stream",
            StreamKind::Voice => "Voice",
            StreamKind::Measure => "Measure",
            StreamKind::Part => "Part",
            StreamKind::PartStaff => "PartStaff",
            StreamKind::System => "System",
            StreamKind::Score => "Score",
            StreamKind::Opus => "Opus",
        }
    }
}

impl std::fmt::Display for StreamKind {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// A musical object that can live on a timeline.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
pub enum StreamElement {
    /// A single pitched note.
    Note(Note),
    /// A chord containing one or more notes.
    Chord(Chord),
    /// A silent rest.
    Rest(Rest),
    /// A stream nested inside this one: a part in a score, a measure in a
    /// part. Boxed, since a stream holds these by value.
    Stream(Box<Stream>),
    /// The clef in force from here on.
    Clef(Clef),
    /// The instrument playing from here on. Boxed: an instrument is large.
    Instrument(Box<Instrument>),
    /// The key signature in force from here on.
    KeySignature(KeySignature),
    /// The key in force from here on: a key signature that also says its
    /// tonic and mode, as music21's `Key` is a `KeySignature`.
    Key(Key),
    /// The metre in force from here on.
    TimeSignature(TimeSignature),
    /// The tempo in force from here on.
    MetronomeMark(MetronomeMark),
    /// A tempo said in words, `Grave` or `Allegro`.
    TempoText(TempoText),
    /// Words written over or under the staff.
    TextExpression(TextExpression),
    /// A sign or words saying where to go next, *Fine* or *D.C.*
    RepeatExpression(RepeatExpression),
    /// The dynamic in force from here on.
    Dynamic(Dynamic),
    /// A chord named over the music. It holds for the time it has been
    /// given and takes none until then.
    ChordSymbol(ChordSymbol),
    /// A stroke with no pitch.
    Unpitched(Unpitched),
    /// Several strokes at once.
    PercussionChord(PercussionChord),
    /// A barline standing inside a measure rather than at either end of it,
    /// where a measure's own barlines are kept.
    Barline(Barline),
    /// A bounce or a gap in the line of a held pedal, joined by the pedal
    /// mark it belongs to.
    PedalObject(PedalObject),
    /// A letter or number marking a place to rehearse from.
    RehearsalMark(RehearsalMark),
    /// A change of tempo written as one note value becoming another. Boxed:
    /// it holds two tempo marks.
    MetricModulation(Box<MetricModulation>),
    /// Where a manuscript's line, page or column breaks.
    Break(crate::volpiano::Break),
    /// How the page, a system or a staff is laid out from here on.
    Layout(crate::layout::Layout),
    /// Text standing anywhere on a page. Boxed: it carries its style.
    TextBox(Box<crate::text::TextBox>),
    /// Another reading of the passage starting here, which takes no time
    /// itself. Boxed: it holds a stream.
    Variant(Box<crate::variant::Variant>),
    /// A `!!` line of a Humdrum file, kept where it was written.
    GlobalComment(crate::humdrum::GlobalComment),
    /// A `*` instruction of a Humdrum spine with no object of its own,
    /// kept where it was written.
    MiscTandem(crate::humdrum::MiscTandem),
    /// A `!` comment in one Humdrum spine: music21's `SpineComment`.
    SpineComment(crate::humdrum::SpineComment),
    /// Where a braille segment divides; nothing is written for it.
    BrailleSegmentDivision(crate::braille::SegmentDivision),
}

impl StreamElement {
    /// Returns the assigned duration, if present.
    ///
    /// The marks that only say what is in force from a point — a key, a
    /// metre, a tempo, a dynamic — have none, as they take no time in
    /// music21 either. A chord symbol has one, of no length until it is
    /// given the time it holds.
    pub fn duration(&self) -> Option<&Duration> {
        match self {
            Self::Note(note) => note.duration(),
            Self::Chord(chord) => chord.duration(),
            Self::Unpitched(stroke) => stroke.duration(),
            Self::PercussionChord(chord) => chord.duration(),
            Self::Rest(rest) => Some(rest.duration()),
            Self::ChordSymbol(symbol) => Some(symbol.duration()),
            Self::Stream(_)
            | Self::Clef(_)
            | Self::Instrument(_)
            | Self::KeySignature(_)
            | Self::Key(_)
            | Self::TimeSignature(_)
            | Self::MetronomeMark(_)
            | Self::TempoText(_)
            | Self::TextExpression(_)
            | Self::RepeatExpression(_)
            | Self::Dynamic(_)
            | Self::Barline(_)
            | Self::PedalObject(_)
            | Self::RehearsalMark(_)
            | Self::MetricModulation(_)
            | Self::Break(_)
            | Self::Layout(_)
            | Self::TextBox(_)
            | Self::Variant(_)
            | Self::GlobalComment(_)
            | Self::MiscTandem(_)
            | Self::SpineComment(_)
            | Self::BrailleSegmentDivision(_) => None,
        }
    }

    /// Returns the duration in quarter lengths.
    ///
    /// A nested stream is as long as its own contents; a mark takes no time;
    /// anything else with no duration of its own defaults to a quarter, as
    /// music21's does.
    pub fn quarter_length(&self) -> FloatType {
        match self {
            Self::Stream(stream) => stream.end_offset(),
            Self::Clef(_)
            | Self::Instrument(_)
            | Self::KeySignature(_)
            | Self::Key(_)
            | Self::TimeSignature(_)
            | Self::MetronomeMark(_)
            | Self::TempoText(_)
            | Self::TextExpression(_)
            | Self::RepeatExpression(_)
            | Self::Dynamic(_)
            | Self::Barline(_)
            | Self::PedalObject(_)
            | Self::RehearsalMark(_)
            | Self::MetricModulation(_)
            | Self::Break(_)
            | Self::Layout(_)
            | Self::TextBox(_)
            | Self::Variant(_)
            | Self::GlobalComment(_)
            | Self::MiscTandem(_)
            | Self::SpineComment(_)
            | Self::BrailleSegmentDivision(_) => 0.0,
            _ => self
                .duration()
                .map(Duration::quarter_length)
                .unwrap_or_else(|| Duration::default().quarter_length()),
        }
    }

    /// Returns all pitches contained by this element, a nested stream's
    /// included.
    pub fn pitches(&self) -> Vec<Pitch> {
        match self {
            Self::Note(note) => vec![note.pitch().clone()],
            Self::Chord(chord) => chord.pitches(),
            Self::Stream(stream) => stream.pitches(),
            Self::PercussionChord(chord) => chord.pitches(),
            Self::Unpitched(_)
            | Self::Rest(_)
            | Self::Clef(_)
            | Self::Instrument(_)
            | Self::KeySignature(_)
            | Self::Key(_)
            | Self::TimeSignature(_)
            | Self::MetronomeMark(_)
            | Self::TempoText(_)
            | Self::TextExpression(_)
            | Self::RepeatExpression(_)
            | Self::Dynamic(_)
            | Self::ChordSymbol(_)
            | Self::Barline(_)
            | Self::PedalObject(_)
            | Self::RehearsalMark(_)
            | Self::MetricModulation(_)
            | Self::Break(_)
            | Self::Layout(_)
            | Self::TextBox(_)
            | Self::Variant(_)
            | Self::GlobalComment(_)
            | Self::MiscTandem(_)
            | Self::SpineComment(_)
            | Self::BrailleSegmentDivision(_) => Vec::new(),
        }
    }

    /// The stream this element is, when it is one.
    pub fn as_stream(&self) -> Option<&Stream> {
        match self {
            Self::Stream(stream) => Some(stream),
            _ => None,
        }
    }

    /// music21's `classSortOrder`: what comes first among the things standing
    /// at one offset.
    pub(crate) fn class_sort_order(&self) -> i32 {
        match self {
            // music21's `BrailleTranscriptionHelper`.
            Self::BrailleSegmentDivision(_) => -100,
            Self::TextBox(_) => -31,
            Self::TextExpression(_) | Self::RehearsalMark(_) => -30,
            Self::Instrument(_) => -25,
            Self::Layout(_) => -10,
            Self::Stream(stream) if stream.kind() == StreamKind::Voice => 5,
            Self::Stream(_) => -20,
            Self::Variant(_) => -22,
            Self::Barline(_) => -5,
            Self::Clef(_) => 0,
            Self::MetronomeMark(_) | Self::TempoText(_) | Self::MetricModulation(_) => 1,
            Self::KeySignature(_) | Self::Key(_) => 2,
            Self::TimeSignature(_) => 4,
            Self::Dynamic(_) => 10,
            // music21's `RomanNumeral` is a `Harmony`, which sorts before
            // the notes standing at the same offset as a chord symbol
            // does; a chord carrying a numeral is one of those.
            Self::ChordSymbol(_) => 19,
            Self::Chord(chord) if chord.numeral().is_some() => 19,
            _ => 20,
        }
    }

    /// Whether this element sounds — music21's `.notes`, which is notes and
    /// chords but not rests.
    pub fn is_note_or_chord(&self) -> bool {
        matches!(self, Self::Note(_) | Self::Chord(_))
    }

    /// Returns a transposed copy.
    ///
    /// A key signature moves with the music, as music21's does; a metre and
    /// a tempo do not depend on pitch and are left alone.
    pub fn transpose(&self, interval: &Interval) -> Result<Self> {
        match self {
            Self::Note(note) => {
                let mut out = note.clone();
                out.set_pitch(interval.transpose_pitch(note.pitch())?);
                Ok(Self::Note(out))
            }
            Self::Chord(chord) => Ok(Self::Chord(chord.transpose(interval)?)),
            Self::Rest(rest) => Ok(Self::Rest(rest.clone())),
            // A stroke has no pitch to move, and a percussion part is not
            // transposed with the music.
            Self::Unpitched(stroke) => Ok(Self::Unpitched(stroke.clone())),
            Self::PercussionChord(chord) => Ok(Self::PercussionChord(chord.clone())),
            Self::Stream(stream) => Ok(Self::Stream(Box::new(stream.transpose(interval)?))),
            Self::Clef(clef) => Ok(Self::Clef(clef.clone())),
            Self::Instrument(instrument) => Ok(Self::Instrument(instrument.clone())),
            Self::KeySignature(key) => Ok(Self::KeySignature(key.transpose(interval)?)),
            Self::Key(key) => Ok(Self::Key(key.transpose(interval)?)),
            Self::TimeSignature(meter) => Ok(Self::TimeSignature(meter.clone())),
            Self::MetronomeMark(mark) => Ok(Self::MetronomeMark(mark.clone())),
            Self::TempoText(text) => Ok(Self::TempoText(text.clone())),
            Self::TextExpression(text) => Ok(Self::TextExpression(text.clone())),
            Self::RepeatExpression(mark) => Ok(Self::RepeatExpression(mark.clone())),
            Self::Dynamic(dynamic) => Ok(Self::Dynamic(dynamic.clone())),
            Self::ChordSymbol(symbol) => Ok(Self::ChordSymbol(symbol.transpose(interval)?)),
            Self::Barline(barline) => Ok(Self::Barline(barline.clone())),
            Self::PedalObject(object) => Ok(Self::PedalObject(object.clone())),
            Self::RehearsalMark(mark) => Ok(Self::RehearsalMark(mark.clone())),
            Self::MetricModulation(modulation) => Ok(Self::MetricModulation(modulation.clone())),
            Self::Break(kind) => Ok(Self::Break(*kind)),
            Self::Layout(layout) => Ok(Self::Layout(layout.clone())),
            Self::TextBox(text) => Ok(Self::TextBox(text.clone())),
            Self::Variant(variant) => Ok(Self::Variant(Box::new(variant.transpose(interval)?))),
            Self::GlobalComment(said) => Ok(Self::GlobalComment(said.clone())),
            Self::MiscTandem(tandem) => Ok(Self::MiscTandem(tandem.clone())),
            Self::SpineComment(said) => Ok(Self::SpineComment(said.clone())),
            Self::BrailleSegmentDivision(division) => Ok(Self::BrailleSegmentDivision(*division)),
        }
    }
}

impl From<Barline> for StreamElement {
    fn from(value: Barline) -> Self {
        Self::Barline(value)
    }
}

impl From<PedalObject> for StreamElement {
    fn from(value: PedalObject) -> Self {
        Self::PedalObject(value)
    }
}

impl From<crate::humdrum::GlobalComment> for StreamElement {
    fn from(value: crate::humdrum::GlobalComment) -> Self {
        Self::GlobalComment(value)
    }
}

impl From<crate::humdrum::SpineComment> for StreamElement {
    fn from(value: crate::humdrum::SpineComment) -> Self {
        Self::SpineComment(value)
    }
}

impl From<crate::humdrum::MiscTandem> for StreamElement {
    fn from(value: crate::humdrum::MiscTandem) -> Self {
        Self::MiscTandem(value)
    }
}

impl From<crate::braille::SegmentDivision> for StreamElement {
    fn from(value: crate::braille::SegmentDivision) -> Self {
        Self::BrailleSegmentDivision(value)
    }
}

impl From<RehearsalMark> for StreamElement {
    fn from(value: RehearsalMark) -> Self {
        Self::RehearsalMark(value)
    }
}

impl From<MetricModulation> for StreamElement {
    fn from(value: MetricModulation) -> Self {
        Self::MetricModulation(Box::new(value))
    }
}

impl From<Note> for StreamElement {
    fn from(value: Note) -> Self {
        Self::Note(value)
    }
}

impl From<Chord> for StreamElement {
    fn from(value: Chord) -> Self {
        Self::Chord(value)
    }
}

impl From<Rest> for StreamElement {
    fn from(value: Rest) -> Self {
        Self::Rest(value)
    }
}

impl From<Stream> for StreamElement {
    fn from(value: Stream) -> Self {
        Self::Stream(Box::new(value))
    }
}

impl From<Clef> for StreamElement {
    fn from(value: Clef) -> Self {
        Self::Clef(value)
    }
}

impl From<Instrument> for StreamElement {
    fn from(value: Instrument) -> Self {
        Self::Instrument(Box::new(value))
    }
}

impl From<Key> for StreamElement {
    fn from(value: Key) -> Self {
        Self::Key(value)
    }
}

impl From<KeySignature> for StreamElement {
    fn from(value: KeySignature) -> Self {
        Self::KeySignature(value)
    }
}

impl From<TimeSignature> for StreamElement {
    fn from(value: TimeSignature) -> Self {
        Self::TimeSignature(value)
    }
}

impl From<Dynamic> for StreamElement {
    fn from(value: Dynamic) -> Self {
        Self::Dynamic(value)
    }
}

impl From<ChordSymbol> for StreamElement {
    fn from(value: ChordSymbol) -> Self {
        Self::ChordSymbol(value)
    }
}

impl From<TextExpression> for StreamElement {
    fn from(value: TextExpression) -> Self {
        Self::TextExpression(value)
    }
}

impl From<Unpitched> for StreamElement {
    fn from(value: Unpitched) -> Self {
        Self::Unpitched(value)
    }
}

impl From<PercussionChord> for StreamElement {
    fn from(value: PercussionChord) -> Self {
        Self::PercussionChord(value)
    }
}

impl From<RepeatExpression> for StreamElement {
    fn from(value: RepeatExpression) -> Self {
        Self::RepeatExpression(value)
    }
}

impl From<TempoText> for StreamElement {
    fn from(value: TempoText) -> Self {
        Self::TempoText(value)
    }
}

impl From<MetronomeMark> for StreamElement {
    fn from(value: MetronomeMark) -> Self {
        Self::MetronomeMark(value)
    }
}

/// A timestamped stream item.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct StreamEvent {
    offset: FloatType,
    element: StreamElement,
    /// music21's `priority`, which sorts what stands at one offset ahead
    /// of its class: nought but where a reader says, as Humdrum's says the
    /// line each thing was written on.
    #[cfg_attr(feature = "serde", serde(default))]
    priority: i32,
}

impl StreamEvent {
    /// Creates an event at an offset measured in quarter lengths.
    pub fn new(offset: FloatType, element: impl Into<StreamElement>) -> Self {
        Self {
            offset,
            element: element.into(),
            priority: 0,
        }
    }

    /// The same event, sorted by `priority` among what shares its offset.
    pub fn with_priority(mut self, priority: i32) -> Self {
        self.priority = priority;
        self
    }

    /// music21's `priority` for the element, nought unless a reader gave
    /// one.
    pub fn priority(&self) -> i32 {
        self.priority
    }

    /// Returns the offset in quarter lengths.
    pub fn offset(&self) -> FloatType {
        self.offset
    }

    /// Returns the stream element.
    pub fn element_mut(&mut self) -> &mut StreamElement {
        &mut self.element
    }

    /// The element itself.
    pub fn element(&self) -> &StreamElement {
        &self.element
    }

    /// The offset just past this element.
    pub fn end_offset(&self) -> FloatType {
        self.offset + self.element.quarter_length()
    }
}

/// An ordered stream of music, which may hold other streams.
#[derive(Clone, Debug, Default)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[must_use]
pub struct Stream {
    #[cfg_attr(feature = "serde", serde(default))]
    kind: StreamKind,
    events: Vec<StreamEvent>,
    #[cfg_attr(feature = "serde", serde(default))]
    labels: Labels,
}

/// How a staff group's barlines are drawn: music21's `barTogether`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum BarTogether {
    /// Barlines run through every staff of the group.
    Yes,
    /// Each staff is barred on its own.
    No,
    /// Barlines run between the staves but not through them.
    Mensurstrich,
}

impl BarTogether {
    /// The group barline MusicXML writes for it.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Yes => "yes",
            Self::No => "no",
            Self::Mensurstrich => "Mensurstrich",
        }
    }
}

/// Parts of a score bracketed together: music21's `layout.StaffGroup`,
/// which holds the parts it spans.
///
/// The parts are named by where they stand among the score's parts, first
/// to last, in the order the group was given them.
#[derive(Clone, Debug, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct StaffGroup {
    parts: Vec<usize>,
    name: Option<String>,
    abbreviation: Option<String>,
    symbol: Option<String>,
    bar_together: Option<BarTogether>,
    name_hidden: bool,
    /// Where the symbol is drawn and in what colour: music21's `style`.
    #[cfg_attr(feature = "serde", serde(default))]
    pub style: crate::style::TextStyle,
}

impl StaffGroup {
    /// A group of the parts at these positions, barred together and drawn
    /// with no symbol, as music21's starts out.
    pub fn new(parts: Vec<usize>) -> Self {
        Self {
            parts,
            name: None,
            abbreviation: None,
            symbol: None,
            bar_together: Some(BarTogether::Yes),
            name_hidden: false,
            style: crate::style::TextStyle::default(),
        }
    }

    /// The positions of the parts the group spans.
    pub fn parts(&self) -> &[usize] {
        &self.parts
    }

    /// The group's name.
    pub fn name(&self) -> Option<&str> {
        self.name.as_deref()
    }

    /// Names the group, or clears the name.
    pub fn set_name(&mut self, name: Option<String>) {
        self.name = name;
    }

    /// The group's short name.
    pub fn abbreviation(&self) -> Option<&str> {
        self.abbreviation.as_deref()
    }

    /// Sets the short name, or clears it.
    pub fn set_abbreviation(&mut self, abbreviation: Option<String>) {
        self.abbreviation = abbreviation;
    }

    /// What the group is drawn with: `bracket`, `brace`, `line` or `square`.
    pub fn symbol(&self) -> Option<&str> {
        self.symbol.as_deref()
    }

    /// Sets what the group is drawn with. As in music21, `none` in any case
    /// clears it, and anything but the four symbols is refused.
    pub fn set_symbol(&mut self, symbol: Option<&str>) -> Result<()> {
        self.symbol = match symbol.map(str::to_lowercase) {
            None => None,
            Some(symbol) if symbol == "none" => None,
            Some(symbol) if ["brace", "line", "bracket", "square"].contains(&symbol.as_str()) => {
                Some(symbol)
            }
            Some(symbol) => {
                return Err(crate::error::Error::Value(format!(
                    "the symbol value {symbol} is not acceptable"
                )));
            }
        };
        Ok(())
    }

    /// How the group's barlines are drawn, where that has been said.
    pub fn bar_together(&self) -> Option<BarTogether> {
        self.bar_together
    }

    /// Says how the group's barlines are drawn.
    pub fn set_bar_together(&mut self, bar_together: Option<BarTogether>) {
        self.bar_together = bar_together;
    }

    /// Whether the name is left unprinted: music21's `hideObjectOnPrint`.
    pub fn name_hidden(&self) -> bool {
        self.name_hidden
    }

    /// Says whether the name is left unprinted.
    pub fn set_name_hidden(&mut self, hidden: bool) {
        self.name_hidden = hidden;
    }
}

/// What a stream is called and numbered, as distinct from what it holds.
///
/// music21 spreads these over its subclasses: a measure has a number, a part
/// a name. They are kept together here, and a stream of a kind that has no
/// use for one simply leaves it unset.
#[derive(Clone, Debug, Default, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
struct Labels {
    number: IntegerType,
    number_suffix: Option<String>,
    number_hidden: bool,
    id: Option<String>,
    name: Option<String>,
    abbreviation: Option<String>,
    name_hidden: bool,
    abbreviation_hidden: bool,
    /// Boxed: most streams carry none.
    metadata: Option<Box<Metadata>>,
    staff_groups: Vec<StaffGroup>,
    left_barline: Option<Barline>,
    right_barline: Option<Barline>,
    spanners: Vec<Spanner>,
    ending: Option<Ending>,
    #[cfg_attr(feature = "serde", serde(default))]
    padding_left: FloatType,
    #[cfg_attr(feature = "serde", serde(default))]
    padding_right: FloatType,
    /// How wide a measure is drawn: music21's `layoutWidth`.
    #[cfg_attr(feature = "serde", serde(default))]
    layout_width: Option<crate::style::StyleValue>,
    /// music21's `atSoundingPitch`, `None` for its `'unknown'`.
    #[cfg_attr(feature = "serde", serde(default))]
    at_sounding_pitch: Option<bool>,
    #[cfg_attr(feature = "serde", serde(default))]
    measure_numbering: Option<String>,
}

impl Stream {
    /// Creates an empty stream.
    ///
    /// ```
    /// use music21::{Note, Stream};
    ///
    /// let mut stream = Stream::new();
    /// stream.push(Note::from_name("C4")?);
    /// stream.push(Note::from_name("E4")?);
    /// assert_eq!(stream.len(), 2);
    /// assert_eq!(stream.end_offset(), 2.0);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn new() -> Self {
        Self::default()
    }

    /// Creates an empty stream standing for one of music21's subclasses.
    ///
    /// ```
    /// use music21::{Stream, StreamKind};
    ///
    /// let part = Stream::with_kind(StreamKind::Part);
    /// assert_eq!(part.kind(), StreamKind::Part);
    /// assert!(part.is_empty());
    /// ```
    pub fn with_kind(kind: StreamKind) -> Self {
        Self {
            kind,
            ..Self::default()
        }
    }

    /// A measure's number: music21's `Measure.number`, which is nought until
    /// something numbers it.
    pub fn number(&self) -> IntegerType {
        self.labels.number
    }

    /// Numbers the measure.
    pub fn set_number(&mut self, number: IntegerType) {
        self.labels.number = number;
    }

    /// What follows the number, as the `a` of a measure numbered `12a`:
    /// music21's `numberSuffix`.
    pub fn number_suffix(&self) -> Option<&str> {
        self.labels.number_suffix.as_deref()
    }

    /// Sets what follows the number, or clears it.
    pub fn set_number_suffix(&mut self, suffix: Option<String>) {
        self.labels.number_suffix = suffix;
    }

    /// The number with its suffix, `12a`: music21's
    /// `measureNumberWithSuffix`.
    pub fn number_with_suffix(&self) -> String {
        format!(
            "{}{}",
            self.labels.number,
            self.labels.number_suffix.as_deref().unwrap_or("")
        )
    }

    /// Whether the measure's number is left unshown, as a pickup bar's is:
    /// music21's `showNumber` set to `NEVER`.
    pub fn number_hidden(&self) -> bool {
        self.labels.number_hidden
    }

    /// Says whether the measure's number is left unshown.
    pub fn set_number_hidden(&mut self, hidden: bool) {
        self.labels.number_hidden = hidden;
    }

    /// How wide the measure is drawn, in tenths, where the score says:
    /// music21's `layoutWidth`.
    pub fn layout_width(&self) -> Option<&crate::style::StyleValue> {
        self.labels.layout_width.as_ref()
    }

    /// Says how wide the measure is drawn.
    pub fn set_layout_width(&mut self, width: Option<crate::style::StyleValue>) {
        self.labels.layout_width = width;
    }

    /// Which measures' numbers are shown from this measure on, as MusicXML's
    /// `<measure-numbering>` says it -- `none`, `measure` or `system`:
    /// music21's `style.measureNumbering`. How the numbers are drawn is not
    /// kept.
    pub fn measure_numbering(&self) -> Option<&str> {
        self.labels.measure_numbering.as_deref()
    }

    /// Says which measures' numbers are shown from this measure on.
    pub fn set_measure_numbering(&mut self, numbering: Option<String>) {
        self.labels.measure_numbering = numbering;
    }

    /// The name the stream is known by, as a part's `P1`: music21's `id`
    /// where one was given rather than taken from a memory address.
    pub fn id(&self) -> Option<&str> {
        self.labels.id.as_deref()
    }

    /// Sets the stream's id, or clears it.
    pub fn set_id(&mut self, id: Option<String>) {
        self.labels.id = id;
    }

    /// A part's name, as printed beside its first system: music21's
    /// `partName`.
    pub fn name(&self) -> Option<&str> {
        self.labels.name.as_deref()
    }

    /// Names the part, or clears the name.
    pub fn set_name(&mut self, name: Option<String>) {
        self.labels.name = name;
    }

    /// A part's short name, as printed beside the systems after the first:
    /// music21's `partAbbreviation`.
    pub fn abbreviation(&self) -> Option<&str> {
        self.labels.abbreviation.as_deref()
    }

    /// Sets the part's short name, or clears it.
    pub fn set_abbreviation(&mut self, abbreviation: Option<String>) {
        self.labels.abbreviation = abbreviation;
    }

    /// Whether the part's name is left unprinted: music21's
    /// `style.printPartName` set to false.
    pub fn name_hidden(&self) -> bool {
        self.labels.name_hidden
    }

    /// Says whether the part's name is left unprinted.
    pub fn set_name_hidden(&mut self, hidden: bool) {
        self.labels.name_hidden = hidden;
    }

    /// Whether the part's short name is left unprinted: music21's
    /// `style.printPartAbbreviation` set to false.
    pub fn abbreviation_hidden(&self) -> bool {
        self.labels.abbreviation_hidden
    }

    /// Says whether the part's short name is left unprinted.
    pub fn set_abbreviation_hidden(&mut self, hidden: bool) {
        self.labels.abbreviation_hidden = hidden;
    }

    /// The title, composer and the rest a score carries: music21's
    /// `metadata`.
    pub fn metadata(&self) -> Option<&Metadata> {
        self.labels.metadata.as_deref()
    }

    /// Sets the metadata, or clears it.
    pub fn set_metadata(&mut self, metadata: Option<Metadata>) {
        self.labels.metadata = metadata.map(Box::new);
    }

    /// The groups a score brackets its parts in, in the order they were
    /// added.
    pub fn staff_groups(&self) -> &[StaffGroup] {
        &self.labels.staff_groups
    }

    /// Brackets some of the score's parts together.
    pub fn add_staff_group(&mut self, group: StaffGroup) {
        self.labels.staff_groups.push(group);
    }

    /// The barline a measure starts with, where it is not an ordinary one:
    /// music21's `leftBarline`.
    pub fn left_barline(&self) -> Option<&Barline> {
        self.labels.left_barline.as_ref()
    }

    /// Sets the barline a measure starts with, or clears it.
    pub fn set_left_barline(&mut self, barline: Option<Barline>) {
        self.labels.left_barline = barline;
    }

    /// The barline a measure ends with, where it is not an ordinary one:
    /// music21's `rightBarline`.
    pub fn right_barline(&self) -> Option<&Barline> {
        self.labels.right_barline.as_ref()
    }

    /// Sets the barline a measure ends with, or clears it.
    pub fn set_right_barline(&mut self, barline: Option<Barline>) {
        self.labels.right_barline = barline;
    }

    /// How much of a measure's bar goes unfilled before its first note, as
    /// a pickup leaves the start of its bar: music21's `paddingLeft`.
    pub fn padding_left(&self) -> FloatType {
        self.labels.padding_left
    }

    /// Says how much of the bar goes unfilled before the first note.
    pub fn set_padding_left(&mut self, padding: FloatType) {
        self.labels.padding_left = padding;
    }

    /// How much of a measure's bar goes unfilled after its last note, as a
    /// measure cut short leaves its end: music21's `paddingRight`.
    pub fn padding_right(&self) -> FloatType {
        self.labels.padding_right
    }

    /// Says how much of the bar goes unfilled after the last note.
    pub fn set_padding_right(&mut self, padding: FloatType) {
        self.labels.padding_right = padding;
    }

    /// The alternative ending a measure is part of, where it is in one.
    pub fn ending(&self) -> Option<&Ending> {
        self.labels.ending.as_ref()
    }

    /// Puts the measure in an alternative ending, or takes it out.
    pub fn set_ending(&mut self, ending: Option<Ending>) {
        self.labels.ending = ending;
    }

    /// The slurs and other spanners this stream holds, each naming what it
    /// joins by position in this stream's [`Stream::leaves`].
    pub fn spanners(&self) -> &[Spanner] {
        &self.labels.spanners
    }

    /// Adds a spanner, naming what it joins by position in this stream's
    /// [`Stream::leaves`].
    ///
    /// ```
    /// use music21::{Note, Spanner, Stream};
    ///
    /// let mut stream = Stream::new();
    /// stream.push(Note::from_name("C4")?);
    /// stream.push(Note::from_name("D4")?);
    /// stream.add_spanner(Spanner::slur(vec![0, 1]));
    /// assert_eq!(stream.spanners().len(), 1);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn add_spanner(&mut self, spanner: Spanner) {
        self.labels.spanners.push(spanner);
    }

    /// Takes every spanner off this stream.
    pub(crate) fn clear_spanners(&mut self) {
        self.labels.spanners.clear();
    }

    /// Which of music21's `Stream` subclasses this stands for.
    pub fn kind(&self) -> StreamKind {
        self.kind
    }

    /// Sets which subclass this stands for.
    pub fn set_kind(&mut self, kind: StreamKind) {
        self.kind = kind;
    }

    /// This stream holding other events, in the order given: its kind, name
    /// and numbers kept, its spanners dropped, since the places they name
    /// are gone.
    pub(crate) fn with_events(&self, events: Vec<StreamEvent>) -> Self {
        let mut labels = self.labels.clone();
        labels.spanners.clear();
        Self {
            kind: self.kind,
            events,
            labels,
        }
    }

    /// Creates a stream from events, sorted by offset, those at one offset
    /// kept in the order given: a caller that knows music21's order, its
    /// priorities among it, hands it in here, where [`Stream::insert`]
    /// sorts them by class.
    pub fn from_events(events: impl IntoIterator<Item = StreamEvent>) -> Self {
        let mut stream = Self {
            events: events.into_iter().collect(),
            ..Self::default()
        };
        stream.sort_events();
        stream
    }

    /// Inserts an element at a quarter-length offset.
    ///
    /// ```
    /// use music21::{Note, Stream};
    ///
    /// let mut stream = Stream::new();
    /// stream.insert(2.0, Note::from_name("G4")?);
    /// stream.insert(0.0, Note::from_name("C4")?);
    /// let offsets: Vec<f64> = stream.events().iter().map(|event| event.offset()).collect();
    /// assert_eq!(offsets, [0.0, 2.0]);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn insert(&mut self, offset: FloatType, element: impl Into<StreamElement>) {
        self.insert_sorted(vec![StreamEvent::new(offset, element)]);
    }

    /// Appends an element after the current end of the stream.
    ///
    /// ```
    /// use music21::{Duration, Note, Rest, Stream};
    ///
    /// let mut stream = Stream::new();
    /// stream.push(Note::from_name("C4")?.with_duration(Duration::half()));
    /// stream.push(Rest::new(Duration::new(1.0)?));
    /// stream.push(Note::from_name("D4")?);
    /// assert_eq!(stream.events()[2].offset(), 3.0);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn push(&mut self, element: impl Into<StreamElement>) {
        let event = StreamEvent::new(self.end_offset(), element);
        // What takes no time can sort before the last element at the end,
        // as a clef does before a dynamic; music21 sorts again then.
        let sorts_before_last = self
            .events
            .last()
            .is_some_and(|last| crate::makenotation::event_order(&event, last).is_lt());
        if sorts_before_last {
            self.insert_sorted(vec![event]);
            return;
        }

        self.events.push(event);
    }

    /// The events in the stream's order, to change each element in place;
    /// where an event stands is fixed, as no offset is set through it.
    pub fn events_mut(&mut self) -> &mut [StreamEvent] {
        &mut self.events
    }

    /// The events in offset order.
    ///
    /// ```
    /// use music21::{Note, Rest, Stream, StreamElement};
    ///
    /// let mut stream = Stream::new();
    /// stream.push(Note::from_name("C4")?);
    /// stream.push(Rest::default());
    /// stream.push(Note::from_name("G4")?);
    /// let names: Vec<String> = stream
    ///     .events()
    ///     .iter()
    ///     .filter_map(|event| match event.element() {
    ///         StreamElement::Note(note) => Some(note.pitch().name_with_octave()),
    ///         _ => None,
    ///     })
    ///     .collect();
    /// assert_eq!(names, ["C4", "G4"]);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn events(&self) -> &[StreamEvent] {
        &self.events
    }

    /// Iterates over events in offset order.
    pub fn iter(&self) -> impl Iterator<Item = &StreamEvent> {
        self.events.iter()
    }

    /// How many events this stream holds directly, not counting what any
    /// nested stream holds.
    pub fn len(&self) -> usize {
        self.events.len()
    }

    /// Whether this stream holds nothing at all.
    pub fn is_empty(&self) -> bool {
        self.events.is_empty()
    }

    /// The first event in the stream's order, or `None` where it holds
    /// nothing: music21's `first`.
    ///
    /// ```
    /// use music21::{Note, Stream, StreamElement};
    ///
    /// let mut stream = Stream::new();
    /// assert!(stream.first().is_none());
    /// stream.push(Note::from_name("C4")?);
    /// stream.push(Note::from_name("D4")?);
    /// let StreamElement::Note(note) = stream.first().unwrap().element() else {
    ///     unreachable!()
    /// };
    /// assert_eq!(note.pitch().name_with_octave(), "C4");
    /// assert_eq!(stream.last().unwrap().offset(), 1.0);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn first(&self) -> Option<&StreamEvent> {
        self.events.first()
    }

    /// The last event in the stream's order, or `None` where it holds
    /// nothing: music21's `last`.
    pub fn last(&self) -> Option<&StreamEvent> {
        self.events.last()
    }

    /// Takes out everything the stream holds, keeping what it says of
    /// itself, its kind, number and names: music21's `clear`. Its spanners,
    /// staff groups, metadata and a measure's barlines go too, being among
    /// music21's elements.
    ///
    /// ```
    /// use music21::{Note, Stream, StreamKind};
    ///
    /// let mut measure = Stream::with_kind(StreamKind::Measure);
    /// measure.set_number(3);
    /// measure.push(Note::from_name("C4")?);
    /// measure.clear();
    /// assert!(measure.is_empty());
    /// assert_eq!(measure.number(), 3);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn clear(&mut self) {
        self.events.clear();
        self.labels.spanners.clear();
        self.labels.staff_groups.clear();
        self.labels.metadata = None;
        self.labels.left_barline = None;
        self.labels.right_barline = None;
    }

    /// The clef the stream opens with: the first it holds itself at
    /// nought, music21's `clef`. A clef in a nested stream is not read; the
    /// clef in force anywhere is [`Stream::in_force_before`]'s to find.
    ///
    /// ```
    /// use music21::{Clef, Note, Stream, StreamKind};
    ///
    /// let mut measure = Stream::with_kind(StreamKind::Measure);
    /// measure.push(Note::from_name("D3")?);
    /// assert!(measure.clef().is_none());
    /// measure.insert(0.0, Clef::bass());
    /// assert_eq!(measure.clef().unwrap().sign(), Some("F"));
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn clef(&self) -> Option<&Clef> {
        self.events.iter().find_map(|event| match &event.element {
            StreamElement::Clef(clef) if event.offset == 0.0 => Some(clef),
            _ => None,
        })
    }

    /// How long the stream lasts, from its start to the end of what ends
    /// last: music21's `duration`, a duration of its `highestTime`
    /// ([`Stream::end_offset`]). music21 lets a stream be given a duration
    /// of its own; a crate stream's is always read off what it holds.
    ///
    /// ```
    /// use music21::{Duration, Note, Stream};
    ///
    /// let mut stream = Stream::new();
    /// stream.insert(3.0, Note::from_name("C4")?);
    /// assert_eq!(stream.duration()?.quarter_length(), 4.0);
    /// # Ok::<(), music21::Error>(())
    /// ```
    ///
    /// # Errors
    ///
    /// A stream ending at an infinite offset, which no duration lasts.
    pub fn duration(&self) -> Result<Duration> {
        Duration::new(self.end_offset())
    }

    /// The first event this stream holds itself whose id is `id`, matched
    /// without regard to case, or `None`: music21's `getElementById`, which
    /// looks at this stream's own elements and not into the streams they
    /// hold. Only a stream and a note carry an id here.
    ///
    /// ```
    /// use music21::{Stream, StreamKind};
    ///
    /// let mut score = Stream::with_kind(StreamKind::Score);
    /// for id in ["Soprano", "Alto"] {
    ///     let mut part = Stream::with_kind(StreamKind::Part);
    ///     part.set_id(Some(id.to_string()));
    ///     score.insert(0.0, part);
    /// }
    /// let alto = score.element_by_id("alto").unwrap();
    /// assert_eq!(alto.element().as_stream().unwrap().id(), Some("Alto"));
    /// assert!(score.element_by_id("Tenor").is_none());
    /// ```
    pub fn element_by_id(&self, id: &str) -> Option<&StreamEvent> {
        let wanted = id.to_lowercase();
        self.events.iter().find(|event| {
            let held = match &event.element {
                StreamElement::Note(note) => note.id(),
                StreamElement::Stream(stream) => stream.id(),
                _ => None,
            };
            held.is_some_and(|held| held == id || held.to_lowercase() == wanted)
        })
    }

    /// One timeline with the nesting dissolved: music21's `flatten`.
    ///
    /// Each nested stream's offset is added to its contents', and the
    /// streams themselves are gone; everything else comes through in
    /// music21's order: by offset, then at one offset by class -- a clef
    /// before a key before a dynamic before a chord symbol before a note --
    /// with grace notes first among their class, and otherwise as the
    /// nesting held them, part by part.
    ///
    /// ```
    /// use music21::{Duration, Note, Stream, StreamKind};
    ///
    /// let mut part = Stream::with_kind(StreamKind::Part);
    /// for name in ["C4", "D4"] {
    ///     let mut measure = Stream::with_kind(StreamKind::Measure);
    ///     measure.push(Note::from_name(name)?.with_duration(Duration::whole()));
    ///     part.push(measure);
    /// }
    /// let flat = part.flatten();
    /// assert_eq!(flat.len(), 2);
    /// assert_eq!(flat.events()[1].offset(), 4.0);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn flatten(&self) -> Self {
        let mut flattened = Self::with_kind(self.kind);
        self.flatten_into(0.0, &mut flattened.events);
        // music21 sorts what stands at one offset by its class order --
        // a dynamic before a chord symbol before a note -- and a grace note
        // before the rest of its class, and otherwise keeps the order the
        // walk met them in.
        flattened.events.sort_by(|left, right| {
            left.offset
                .partial_cmp(&right.offset)
                .unwrap_or(std::cmp::Ordering::Equal)
                .then_with(|| {
                    left.element
                        .class_sort_order()
                        .cmp(&right.element.class_sort_order())
                })
                .then_with(|| is_grace(&right.element).cmp(&is_grace(&left.element)))
        });
        flattened
    }

    fn flatten_into(&self, base: FloatType, out: &mut Vec<StreamEvent>) {
        for event in &self.events {
            // Summed as music21 sums them, snapped by `opFrac`, so three
            // triplets end on the beat however deep they sit.
            let offset = crate::makenotation::op_frac(base + event.offset);
            match &event.element {
                StreamElement::Stream(stream) => stream.flatten_into(offset, out),
                element => out.push(StreamEvent::new(offset, element.clone())),
            }
        }
    }

    /// Every element at its offset from this stream's start, nested streams
    /// themselves included: music21's `recurse`.
    ///
    /// ```
    /// use music21::{Duration, Note, Stream, StreamKind};
    ///
    /// let mut part = Stream::with_kind(StreamKind::Part);
    /// for name in ["C4", "D4"] {
    ///     let mut measure = Stream::with_kind(StreamKind::Measure);
    ///     measure.push(Note::from_name(name)?.with_duration(Duration::whole()));
    ///     part.push(measure);
    /// }
    /// // Two measures and the note in each.
    /// let offsets: Vec<f64> = part.recurse().iter().map(|(offset, _)| *offset).collect();
    /// assert_eq!(offsets, [0.0, 0.0, 4.0, 4.0]);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn recurse(&self) -> Vec<(FloatType, &StreamElement)> {
        let mut out = Vec::new();
        self.recurse_into(0.0, &mut out);
        out
    }

    fn recurse_into<'a>(&'a self, base: FloatType, out: &mut Vec<(FloatType, &'a StreamElement)>) {
        for event in &self.events {
            // Summed as music21 sums them, snapped by `opFrac`, so three
            // triplets end on the beat however deep they sit.
            let offset = crate::makenotation::op_frac(base + event.offset);
            out.push((offset, &event.element));
            if let StreamElement::Stream(stream) = &event.element {
                stream.recurse_into(offset, out);
            }
        }
    }

    /// Every element that is not itself a stream, at its offset from this
    /// stream's start, in the order [`Stream::for_each_mut`] hands them over.
    ///
    /// An element's index in this list is its *position*, which is how the
    /// walks answering about particular elements say which they mean:
    /// [`crate::volume::dynamics_in_force`],
    /// [`crate::chordsymbol::chord_symbol_durations`],
    /// [`crate::voiceleading::voice_leading_quartet_positions`] and
    /// [`crate::voiceleading::verticality_positions_at`]. A caller keeping
    /// something of its own beside each element, as a binding keeps the
    /// object it was handed, finds it again by the same index.
    pub fn leaves(&self) -> Vec<(FloatType, &StreamElement)> {
        self.leaves_under_top()
            .into_iter()
            .map(|(_, offset, element)| (offset, element))
            .collect()
    }

    /// [`Stream::leaves`], each with the index of the event of this stream it
    /// came out of: itself for an element held directly, the nested stream
    /// holding it otherwise.
    pub(crate) fn leaves_under_top(&self) -> Vec<(usize, FloatType, &StreamElement)> {
        let mut out = Vec::new();
        for (top, event) in self.events.iter().enumerate() {
            match &event.element {
                StreamElement::Stream(stream) => {
                    let mut inner = Vec::new();
                    stream.leaves_into(event.offset, &mut inner);
                    out.extend(
                        inner
                            .into_iter()
                            .map(|(offset, element)| (top, offset, element)),
                    );
                }
                element => out.push((top, event.offset, element)),
            }
        }
        out
    }

    /// The positions among [`Stream::leaves`] in the order
    /// [`Stream::flatten`] puts them: by offset, then by class order, a
    /// grace note ahead of the rest of its class, and otherwise as the walk
    /// met them.
    ///
    /// The two walks are the same walk, so the *n*th leaf is the *n*th
    /// element the flattening read; this says where each of those stands
    /// once sorted, which is how a walk reading a flattened stream answers
    /// in positions a caller can look up.
    pub(crate) fn flatten_order(leaves: &[(FloatType, &StreamElement)]) -> Vec<usize> {
        let mut order: Vec<usize> = (0..leaves.len()).collect();
        order.sort_by(|left, right| {
            let (left_offset, left_element) = leaves[*left];
            let (right_offset, right_element) = leaves[*right];
            left_offset
                .total_cmp(&right_offset)
                .then(
                    left_element
                        .class_sort_order()
                        .cmp(&right_element.class_sort_order()),
                )
                .then(is_grace(right_element).cmp(&is_grace(left_element)))
        });
        order
    }

    fn leaves_into<'a>(&'a self, base: FloatType, out: &mut Vec<(FloatType, &'a StreamElement)>) {
        for event in &self.events {
            // Summed as music21 sums them, snapped by `opFrac`, so three
            // triplets end on the beat however deep they sit.
            let offset = crate::makenotation::op_frac(base + event.offset);
            match &event.element {
                StreamElement::Stream(stream) => stream.leaves_into(offset, out),
                element => out.push((offset, element)),
            }
        }
    }

    /// Takes out one of this stream's own events, and with it whatever it
    /// holds: music21's `remove`. Every spanner, here or in a nested
    /// stream, is moved to where what it names now stands, and names
    /// nothing for an element taken out. Nothing is taken out for a place
    /// past the end.
    pub fn remove_event(&mut self, index: usize) -> Option<StreamEvent> {
        if index >= self.events.len() {
            return None;
        }
        let under = self.leaves_under_top();
        let doomed: Vec<usize> = under
            .iter()
            .enumerate()
            .filter(|(_, (top, _, _))| *top == index)
            .map(|(position, _)| position)
            .collect();
        let holds_a_stream = matches!(self.events[index].element, StreamElement::Stream(_));
        if holds_a_stream {
            self.retain_leaves(&mut |position, _| !doomed.contains(&position));
            return Some(self.events.remove(index));
        }
        let removed = self.events[index].clone();
        self.retain_leaves(&mut |position, _| !doomed.contains(&position));
        Some(removed)
    }

    /// Hands every element to a closure with its offset from this stream's
    /// start, nested streams' contents included, so that it may be changed
    /// where it sits.
    ///
    /// [`Stream::flatten`] and [`Stream::recurse`] hand back copies and
    /// references; this is the walk for an edit that has to land in the
    /// score itself. Things at one offset come in the same order `flatten`
    /// gives them. A nested stream is walked into rather than handed over.
    pub fn for_each_mut(&mut self, visit: &mut impl FnMut(FloatType, &mut StreamElement)) {
        self.for_each_mut_from(0.0, visit);
    }

    fn for_each_mut_from(
        &mut self,
        base: FloatType,
        visit: &mut impl FnMut(FloatType, &mut StreamElement),
    ) {
        for event in &mut self.events {
            // Summed as music21 sums them, snapped by `opFrac`, so three
            // triplets end on the beat however deep they sit.
            let offset = crate::makenotation::op_frac(base + event.offset);
            match &mut event.element {
                StreamElement::Stream(stream) => stream.for_each_mut_from(offset, visit),
                element => visit(offset, element),
            }
        }
    }

    /// Keeps the leaves `keep` accepts, handed each with its position in
    /// [`Stream::leaves`] to change as it likes, and drops the rest. Every
    /// spanner, here or in a nested stream, is moved to where what it names
    /// now stands, and names nothing for an element dropped.
    pub fn retain_leaves(&mut self, keep: &mut impl FnMut(usize, &mut StreamElement) -> bool) {
        let mut seen = 0;
        self.retain_leaves_from(&mut seen, keep);
    }

    /// Puts `replacement` in place of the stream reached by `path`, the
    /// index of an event holding a stream at each level down from here.
    /// Every spanner of a stream on the way moves past what was replaced
    /// to where it now stands, and names nothing for an element replaced.
    pub(crate) fn replace_nested(&mut self, path: &[usize], replacement: Stream) {
        self.edit_nested(path, |target| {
            let gone = vec![None; target.leaf_total()];
            *target = replacement;
            ((), gone)
        });
    }

    /// Edits the stream reached by `path`, the index of an event holding a
    /// stream at each level down from here. `edit` answers what it answers
    /// and where each of the stream's leaves went, by old position, having
    /// moved that stream's own spanners itself; every spanner of a stream on
    /// the way is moved with them. The answer is `edit`'s, and where each of
    /// this stream's leaves went.
    pub(crate) fn edit_nested<R>(
        &mut self,
        path: &[usize],
        edit: impl FnOnce(&mut Stream) -> (R, Vec<Option<usize>>),
    ) -> (R, Vec<Option<usize>>) {
        let Some((&first, rest)) = path.split_first() else {
            return edit(self);
        };
        let total = self.leaf_total();
        let before: usize = self.events[..first]
            .iter()
            .map(|event| leaf_count(&event.element))
            .sum();
        let StreamElement::Stream(inner) = &mut self.events[first].element else {
            return edit(self);
        };
        let old = inner.leaf_total();
        let (answer, inner_moved) = inner.edit_nested(rest, edit);
        let new = inner.leaf_total();
        let moved: Vec<Option<usize>> = (0..total)
            .map(|place| {
                if place < before {
                    Some(place)
                } else if place < before + old {
                    inner_moved
                        .get(place - before)
                        .copied()
                        .flatten()
                        .map(|at| at + before)
                } else {
                    Some(place - old + new)
                }
            })
            .collect();
        for spanner in &mut self.labels.spanners {
            spanner.move_places(&moved);
        }
        (answer, moved)
    }

    /// How many leaves this stream has.
    pub(crate) fn leaf_total(&self) -> usize {
        self.events
            .iter()
            .map(|event| leaf_count(&event.element))
            .sum()
    }

    /// Puts `events` in place of this stream's own, in the order given,
    /// each with the index of the event it stood at here, if it did. Every
    /// spanner of this stream is moved to where what it names now stands,
    /// and names nothing for an element no longer here. The answer is where
    /// each leaf went, by old position.
    pub(crate) fn replace_events(
        &mut self,
        events: Vec<(StreamEvent, Option<usize>)>,
    ) -> Vec<Option<usize>> {
        let mut starts = Vec::with_capacity(self.events.len());
        let mut first = 0;
        for event in &self.events {
            starts.push(first);
            first += leaf_count(&event.element);
        }
        let mut moved: Vec<Option<usize>> = vec![None; first];
        let mut placed = 0;
        for (event, origin) in &events {
            let count = leaf_count(&event.element);
            if let Some(&start) = origin.and_then(|origin| starts.get(origin)) {
                for leaf in 0..count {
                    if let Some(slot) = moved.get_mut(start + leaf) {
                        *slot = Some(placed + leaf);
                    }
                }
            }
            placed += count;
        }
        self.events = events.into_iter().map(|(event, _)| event).collect();
        for spanner in &mut self.labels.spanners {
            spanner.move_places(&moved);
        }
        moved
    }

    /// Adds events to this stream's own and puts them all in the order
    /// music21 sorts a stream in, an added event after one already here that
    /// sorts alike. Every spanner of this stream is moved to where what it
    /// names now stands. The answer is where each leaf went, by old
    /// position.
    pub(crate) fn insert_sorted(&mut self, added: Vec<StreamEvent>) -> Vec<Option<usize>> {
        // Each event held here with where its leaves started; nothing for
        // one added.
        let mut first = 0;
        let mut held: Vec<(StreamEvent, Option<usize>)> = Vec::new();
        for event in std::mem::take(&mut self.events) {
            let count = leaf_count(&event.element);
            held.push((event, Some(first)));
            first += count;
        }
        held.extend(added.into_iter().map(|event| (event, None)));
        held.sort_by(|left, right| crate::makenotation::event_order(&left.0, &right.0));
        let mut moved: Vec<Option<usize>> = vec![None; first];
        let mut placed = 0;
        for (event, start) in &held {
            let count = leaf_count(&event.element);
            if let Some(start) = start {
                for offset in 0..count {
                    moved[start + offset] = Some(placed + offset);
                }
            }
            placed += count;
        }
        self.events = held.into_iter().map(|(event, _)| event).collect();
        for spanner in &mut self.labels.spanners {
            spanner.move_places(&moved);
        }
        moved
    }

    /// [`Stream::retain_leaves`] below the `seen` leaves already walked; the
    /// answer is where each of this stream's leaves went, by old position.
    fn retain_leaves_from(
        &mut self,
        seen: &mut usize,
        keep: &mut impl FnMut(usize, &mut StreamElement) -> bool,
    ) -> Vec<Option<usize>> {
        let mut moved: Vec<Option<usize>> = Vec::new();
        let mut kept = 0;
        self.events.retain_mut(|event| match &mut event.element {
            StreamElement::Stream(inner) => {
                let inner_moved = inner.retain_leaves_from(seen, keep);
                let count = inner_moved.iter().flatten().count();
                moved.extend(
                    inner_moved
                        .into_iter()
                        .map(|place| place.map(|place| place + kept)),
                );
                kept += count;
                true
            }
            element => {
                let position = *seen;
                *seen += 1;
                if keep(position, element) {
                    moved.push(Some(kept));
                    kept += 1;
                    true
                } else {
                    moved.push(None);
                    false
                }
            }
        });
        for spanner in &mut self.labels.spanners {
            spanner.move_places(&moved);
        }
        moved
    }

    /// Whether this stream holds parts, or streams standing in for them:
    /// music21's `hasPartLikeStreams`. A part says so; a measure or a voice,
    /// or a stream starting anywhere but the beginning, says not; any other
    /// stream holding measures or notes and rests says so, unless a later
    /// one says not.
    pub fn has_part_like_streams(&self) -> bool {
        let mut part_like = false;
        for event in &self.events {
            let Some(stream) = event.element.as_stream() else {
                continue;
            };
            match stream.kind {
                StreamKind::Part | StreamKind::PartStaff => return true,
                StreamKind::Measure | StreamKind::Voice => return false,
                _ if event.offset != 0.0 => return false,
                _ => {}
            }
            let holds_music = stream.events.iter().any(|inner| {
                inner.element.is_instance("GeneralNote")
                    || inner
                        .element
                        .as_stream()
                        .is_some_and(|nested| nested.kind == StreamKind::Measure)
            });
            if holds_music {
                part_like = true;
            }
        }
        part_like
    }

    /// The streams of one kind held directly by this one: music21's `.parts`
    /// on a score, `.measures` on a part, `.voices` on a measure.
    pub fn streams_of_kind(&self, kind: StreamKind) -> Vec<&Stream> {
        self.events
            .iter()
            .filter_map(|event| event.element.as_stream())
            .filter(|stream| stream.kind == kind)
            .collect()
    }

    /// The parts this stream holds, a staff of a part written on several
    /// included: music21's `.parts`, which a `PartStaff` is one of.
    pub fn parts(&self) -> Vec<&Stream> {
        self.events
            .iter()
            .filter_map(|event| event.element.as_stream())
            .filter(|stream| matches!(stream.kind, StreamKind::Part | StreamKind::PartStaff))
            .collect()
    }

    /// The measures this stream holds.
    ///
    /// ```
    /// use music21::{Duration, Note, Stream, StreamKind};
    ///
    /// let mut part = Stream::with_kind(StreamKind::Part);
    /// for name in ["C4", "D4"] {
    ///     let mut measure = Stream::with_kind(StreamKind::Measure);
    ///     measure.push(Note::from_name(name)?.with_duration(Duration::whole()));
    ///     part.push(measure);
    /// }
    /// assert_eq!(part.measures().len(), 2);
    /// assert_eq!(part.measures()[1].len(), 1);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn measures(&self) -> Vec<&Stream> {
        self.streams_of_kind(StreamKind::Measure)
    }

    /// The voices this stream holds.
    pub fn voices(&self) -> Vec<&Stream> {
        self.streams_of_kind(StreamKind::Voice)
    }

    /// The measure of a number, or `None`: music21's `measure`.
    ///
    /// Where every measure is numbered nought, as in a stream nobody has
    /// numbered, they are counted from one instead. A number below nought
    /// counts back from the last, `-1` being the last. The measure is this
    /// stream's own, so it carries none of the clef, key or metre in force
    /// before it, as in music21; [`Stream::measures_between`] collects them.
    /// A score is not sliced here: `measures_between(n, Some(n))` answers
    /// music21's `Score.measure`.
    ///
    /// ```
    /// use music21::{Duration, Note, Stream, StreamKind};
    ///
    /// let mut part = Stream::with_kind(StreamKind::Part);
    /// for (number, name) in [(1, "C4"), (2, "D4")] {
    ///     let mut measure = Stream::with_kind(StreamKind::Measure);
    ///     measure.set_number(number);
    ///     measure.push(Note::from_name(name)?.with_duration(Duration::whole()));
    ///     part.push(measure);
    /// }
    /// assert_eq!(part.measure(2).unwrap().number(), 2);
    /// assert_eq!(part.measure(-1).unwrap().number(), 2);
    /// assert!(part.measure(3).is_none());
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn measure(&self, number: IntegerType) -> Option<&Stream> {
        let measures = self.measures();
        if number < 0 {
            let index = isize::try_from(measures.len()).ok()? + isize::try_from(number).ok()?;
            return measures.get(usize::try_from(index).ok()?).copied();
        }

        let counted = !measures.iter().any(|measure| measure.number() != 0);
        measures
            .iter()
            .enumerate()
            .find(|(index, measure)| measure_number(*index, measure, counted) == number)
            .map(|(_, measure)| *measure)
    }

    /// The measures numbered `start` to `end`, both included, or to the last
    /// where `end` is `None`: music21's `measures`.
    ///
    /// The answer is a stream of this one's kind, its first measure at
    /// nought, opening with the clef, metre, instrument, key and tempo in
    /// force where it starts, those its first measure does not open with
    /// itself. A spanner comes along where it joins something in the
    /// measures taken, naming nothing for what it joins outside them. A
    /// score answers a score of each part's measures, without the score's
    /// own spanners. Measures are numbered as [`Stream::measure`] reads
    /// them; music21's suffixed numbers (`'4b'`) and indices are not taken.
    ///
    /// ```
    /// use music21::{Clef, Duration, Note, Stream, StreamElement, StreamKind};
    ///
    /// let mut part = Stream::with_kind(StreamKind::Part);
    /// for (number, name) in [(1, "C3"), (2, "D3"), (3, "E3")] {
    ///     let mut measure = Stream::with_kind(StreamKind::Measure);
    ///     measure.set_number(number);
    ///     if number == 1 {
    ///         measure.insert(0.0, Clef::bass());
    ///     }
    ///     measure.push(Note::from_name(name)?.with_duration(Duration::whole()));
    ///     part.push(measure);
    /// }
    /// let excerpt = part.measures_between(2, None);
    /// assert!(matches!(excerpt.events()[0].element(), StreamElement::Clef(_)));
    /// let numbers: Vec<i32> = excerpt.measures().iter().map(|m| m.number()).collect();
    /// assert_eq!(numbers, [2, 3]);
    /// assert_eq!(excerpt.events()[1].offset(), 0.0);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn measures_between(&self, start: IntegerType, end: Option<IntegerType>) -> Stream {
        if self.kind == StreamKind::Score {
            let mut out = self.clone_empty();
            out.labels.staff_groups = self.labels.staff_groups.clone();
            for part in self.parts() {
                out.events
                    .push(StreamEvent::new(0.0, part.measures_between(start, end)));
            }
            return out;
        }

        let measured: Vec<usize> = self
            .events
            .iter()
            .enumerate()
            .filter(|(_, event)| {
                event
                    .element
                    .as_stream()
                    .is_some_and(|stream| stream.kind == StreamKind::Measure)
            })
            .map(|(index, _)| index)
            .collect();
        let counted = !measured.iter().any(|&index| {
            self.events[index]
                .element
                .as_stream()
                .is_some_and(|measure| measure.number() != 0)
        });
        let matches: Vec<usize> = measured
            .iter()
            .enumerate()
            .filter(|(count, index)| {
                let Some(measure) = self.events[**index].element.as_stream() else {
                    return false;
                };
                let number = measure_number(*count, measure, counted);
                number >= start && end.is_none_or(|end| number <= end)
            })
            .map(|(_, index)| *index)
            .collect();
        let mut out = self.clone_empty();
        let Some(&first) = matches.first() else {
            return out;
        };

        let begins = self.events[first].offset;
        let mut kept = self.collected_before(first);
        kept.extend(matches.iter().map(|&index| {
            let event = &self.events[index];
            let offset = crate::makenotation::op_frac(event.offset - begins);
            (StreamEvent::new(offset, event.element.clone()), Some(index))
        }));
        out.labels.spanners = self.labels.spanners.clone();
        out.events = self.events.clone();
        out.replace_events(kept);
        out.labels
            .spanners
            .retain(|spanner| spanner.spanned().iter().any(Option::is_some));
        out
    }

    /// What music21's `measures` collects for the measure at `index`: of
    /// each class it collects, the one in force where the measure starts,
    /// unless the measure opens with one itself; in music21's order, at
    /// nought.
    fn collected_before(&self, index: usize) -> Vec<(StreamEvent, Option<usize>)> {
        const COLLECTED: [&str; 5] = [
            "Clef",
            "TimeSignature",
            "Instrument",
            "KeySignature",
            "MetronomeMark",
        ];
        let Some(measure) = self.events[index].element.as_stream() else {
            return Vec::new();
        };

        let begins = self.events[index].offset;
        let flat = self.flatten();
        let mut found: Vec<StreamEvent> = COLLECTED
            .iter()
            .filter(|class| !opens_with(measure, class))
            .filter_map(|class| {
                flat.events
                    .iter()
                    .take_while(|event| event.offset <= begins)
                    .filter(|event| event.element.is_instance(class))
                    .last()
                    .map(|event| StreamEvent::new(0.0, event.element.clone()))
            })
            .collect();
        // music21 sorts these before the measure whatever their class.
        found.sort_by(crate::makenotation::event_order);
        found.into_iter().map(|event| (event, None)).collect()
    }

    /// Every note and chord on the flattened timeline: music21's
    /// `flatten().notes`, which leaves rests out.
    ///
    /// ```
    /// use music21::{Chord, Note, Rest, Stream};
    ///
    /// let mut stream = Stream::new();
    /// stream.push(Note::from_name("C4")?);
    /// stream.push(Rest::default());
    /// stream.push(Chord::new("E4 G4")?);
    /// let offsets: Vec<f64> = stream.notes().iter().map(|(offset, _)| *offset).collect();
    /// assert_eq!(offsets, [0.0, 2.0]);
    /// # Ok::<(), music21::Error>(())
    /// ```
    pub fn notes(&self) -> Vec<(FloatType, StreamElement)> {
        self.flatten()
            .events
            .into_iter()
            .filter(|event| event.element.is_note_or_chord())
            .map(|event| (event.offset, event.element))
            .collect()
    }

    /// Returns the maximum event end offset, a nested stream's own length
    /// included, snapped to the fraction it stands for: music21's
    /// `highestTime`.
    pub fn end_offset(&self) -> FloatType {
        crate::makenotation::op_frac(
            self.events
                .iter()
                .map(StreamEvent::end_offset)
                .fold(0.0, FloatType::max),
        )
    }

    /// Returns all pitches in timeline order, from nested streams too.
    pub fn pitches(&self) -> Vec<Pitch> {
        self.flatten()
            .events
            .iter()
            .flat_map(|event| event.element.pitches())
            .collect()
    }

    /// The key signature in force at an offset: the last one written at or
    /// before it, anywhere in the nesting.
    ///
    /// This is what music21 answers with `getContextByClass(KeySignature)`,
    /// found by looking back along the flattened timeline rather than by
    /// walking the sites an object belongs to.
    pub fn key_signature_at(&self, offset: FloatType) -> Option<KeySignature> {
        self.in_force_at(offset, |element| match element {
            StreamElement::KeySignature(key) => Some(key.clone()),
            StreamElement::Key(key) => Some(key.key_signature()),
            _ => None,
        })
    }

    /// The metre in force at an offset, found the same way.
    pub fn time_signature_at(&self, offset: FloatType) -> Option<TimeSignature> {
        self.in_force_at(offset, |element| match element {
            StreamElement::TimeSignature(meter) => Some(meter.clone()),
            _ => None,
        })
    }

    /// The tempo in force at an offset, found the same way.
    pub fn metronome_mark_at(&self, offset: FloatType) -> Option<MetronomeMark> {
        self.in_force_at(offset, |element| match element {
            StreamElement::MetronomeMark(mark) => Some(mark.clone()),
            _ => None,
        })
    }

    /// The last thing of one sort written at or before an offset.
    fn in_force_at<T>(
        &self,
        offset: FloatType,
        read: impl Fn(&StreamElement) -> Option<T>,
    ) -> Option<T> {
        self.flatten()
            .events
            .iter()
            .take_while(|event| event.offset <= offset)
            .filter_map(|event| read(&event.element))
            .last()
    }

    /// Returns a transposed copy, nesting and all.
    pub fn transpose(&self, interval: &Interval) -> Result<Self> {
        let events = self
            .events
            .iter()
            .map(|event| {
                Ok(StreamEvent::new(
                    event.offset,
                    event.element.transpose(interval)?,
                ))
            })
            .collect::<Result<Vec<_>>>()?;
        let mut out = Self::with_kind(self.kind);
        out.labels = self.labels.clone();
        out.events = events;
        out.sort_events();
        Ok(out)
    }

    /// Puts the events in offset order, keeping the order they were given
    /// in at one offset: how [`Stream::from_events`] takes an order from a
    /// caller that knows more of it than the crate does, music21's
    /// priorities among them.
    fn sort_events(&mut self) {
        self.events.sort_by(|left, right| {
            left.offset
                .partial_cmp(&right.offset)
                .unwrap_or(std::cmp::Ordering::Equal)
        });
    }
}

/// A measure's number, or where every measure is numbered nought, its
/// place counted from one, as music21 reads measures by number.
fn measure_number(index: usize, measure: &Stream, counted: bool) -> IntegerType {
    if !counted {
        return measure.number();
    }

    IntegerType::try_from(index + 1).unwrap_or(IntegerType::MAX)
}

/// Whether a stream, or one nested in it, holds something of `class` at
/// its own start.
fn opens_with(stream: &Stream, class: &str) -> bool {
    stream.events.iter().any(|event| {
        (event.offset == 0.0 && event.element.is_instance(class))
            || event
                .element
                .as_stream()
                .is_some_and(|inner| opens_with(inner, class))
    })
}

/// Whether an element is a grace note or chord, which takes no time.
fn is_grace(element: &StreamElement) -> bool {
    element.duration().is_some_and(Duration::is_grace)
}

/// How many leaves an element is: those of a nested stream, or itself.
fn leaf_count(element: &StreamElement) -> usize {
    match element {
        StreamElement::Stream(inner) => inner.leaves().len(),
        _ => 1,
    }
}

impl<'a> IntoIterator for &'a Stream {
    type Item = &'a StreamEvent;
    type IntoIter = std::slice::Iter<'a, StreamEvent>;

    fn into_iter(self) -> Self::IntoIter {
        self.events.iter()
    }
}

#[cfg(test)]
mod tests {
    #[test]
    fn a_stream_has_part_like_streams_as_music21_decides() {
        use super::{Stream, StreamKind};
        use crate::note::Note;

        // music21's own examples: a part, a measure, one generic stream at
        // the start, and a second one appended after it.
        let four_notes = |kind: StreamKind| {
            let mut stream = Stream::with_kind(kind);
            for _ in 0..4 {
                stream.push(Note::from_name("C4").unwrap());
            }
            stream
        };
        let mut score = Stream::with_kind(StreamKind::Score);
        assert!(!score.has_part_like_streams());
        score.insert(0.0, four_notes(StreamKind::Part));
        assert!(score.has_part_like_streams());

        let mut score = Stream::with_kind(StreamKind::Score);
        score.push(four_notes(StreamKind::Measure));
        assert!(!score.has_part_like_streams());

        let mut score = Stream::with_kind(StreamKind::Score);
        score.push(four_notes(StreamKind::Stream));
        assert!(score.has_part_like_streams());
        score.push(four_notes(StreamKind::Stream));
        assert!(!score.has_part_like_streams());
    }

    #[test]
    fn a_stream_says_what_kind_it_is_and_walks_its_events() {
        use super::{Stream, StreamElement, StreamEvent, StreamKind};
        use crate::note::Note;
        use crate::pitch::Pitch;
        use crate::tempo::MetronomeMark;

        assert_eq!(StreamKind::Voice.as_str(), "Voice");
        assert_eq!(StreamKind::Voice.to_string(), "Voice");
        let mut stream = Stream::new();
        assert!(stream.is_empty());
        stream.set_kind(StreamKind::Voice);
        assert_eq!(stream.kind(), StreamKind::Voice);
        assert!(matches!(
            StreamElement::from(MetronomeMark::new(120.0)),
            StreamElement::MetronomeMark(_)
        ));

        let note = Note::from_pitch(Pitch::from_name("C4").unwrap());
        let rebuilt = Stream::from_events([StreamEvent::new(0.0, note)]);
        assert_eq!(rebuilt.iter().count(), 1);
        assert!(!rebuilt.is_empty());
        assert!(rebuilt.voices().is_empty());
        let mut outer = Stream::new();
        outer.push(stream);
        assert_eq!(outer.voices().len(), 1);
    }

    use super::*;

    #[test]
    fn a_stream_iterates_by_reference() {
        let mut stream = Stream::new();
        stream.push(Note::from_name("C4").unwrap());
        stream.push(Note::from_name("E4").unwrap());

        let offsets: Vec<FloatType> = (&stream).into_iter().map(StreamEvent::offset).collect();
        assert_eq!(offsets, vec![0.0, 1.0]);
        assert_eq!((&stream).into_iter().count(), stream.len());
    }

    #[test]
    fn stream_push_uses_durations() {
        let mut stream = Stream::new();
        stream.push(
            Note::from_name("C4")
                .unwrap()
                .with_duration(Duration::half()),
        );
        stream.push(Rest::from_quarter_length(0.5).unwrap());
        assert_eq!(stream.events()[0].offset(), 0.0);
        assert_eq!(stream.events()[1].offset(), 2.0);
        assert_eq!(stream.end_offset(), 2.5);
    }

    #[test]
    fn a_clef_inserted_after_a_note_sorts_before_it() {
        // music21 sorts what stands at one offset by its class order, so
        // a clef put in after a note at the start still comes first.
        let mut stream = Stream::new();
        stream.insert(0.0, Note::from_name("C4").unwrap());
        stream.insert(0.0, Clef::treble());
        assert!(matches!(
            stream.events()[0].element(),
            StreamElement::Clef(_)
        ));
        assert!(matches!(
            stream.events()[1].element(),
            StreamElement::Note(_)
        ));
    }

    #[test]
    fn a_clef_pushed_after_a_dynamic_sorts_before_it() {
        // music21's `append` sorts a stream again where what is appended
        // would sort before the last element.
        let mut stream = Stream::new();
        stream.push(Dynamic::new("p"));
        stream.push(Clef::treble());
        assert!(matches!(
            stream.events()[0].element(),
            StreamElement::Clef(_)
        ));
        assert!(matches!(
            stream.events()[1].element(),
            StreamElement::Dynamic(_)
        ));
    }

    #[test]
    fn first_and_last_follow_the_streams_order() {
        let mut stream = Stream::new();
        assert!(stream.first().is_none());
        assert!(stream.last().is_none());
        stream.insert(1.0, Note::from_name("D4").unwrap());
        stream.insert(0.0, Note::from_name("C4").unwrap());
        stream.insert(0.0, Clef::treble());
        assert!(matches!(
            stream.first().unwrap().element(),
            StreamElement::Clef(_)
        ));
        assert_eq!(stream.last().unwrap().offset(), 1.0);
    }

    #[test]
    fn clear_takes_out_what_music21_holds_as_elements() {
        let mut measure = Stream::with_kind(StreamKind::Measure);
        measure.set_number(3);
        measure.set_id(Some("m3".to_string()));
        measure.push(Note::from_name("C4").unwrap());
        measure.set_right_barline(Some(Barline::default()));
        measure.set_left_barline(Some(Barline::default()));
        measure.set_metadata(Some(Metadata::default()));
        measure.add_staff_group(StaffGroup::new(vec![0]));
        measure.clear();
        assert!(measure.is_empty());
        assert!(measure.right_barline().is_none());
        assert!(measure.left_barline().is_none());
        assert!(measure.metadata().is_none());
        assert!(measure.staff_groups().is_empty());
        assert!(measure.spanners().is_empty());
        assert_eq!(measure.number(), 3);
        assert_eq!(measure.id(), Some("m3"));
        assert_eq!(measure.kind(), StreamKind::Measure);
    }

    #[test]
    fn the_clef_is_one_held_at_the_start() {
        let mut measure = Stream::with_kind(StreamKind::Measure);
        measure.insert(2.0, Clef::bass());
        assert!(
            measure.clef().is_none(),
            "a clef later on is not the opening one"
        );
        measure.insert(0.0, Clef::treble());
        assert_eq!(measure.clef().unwrap().sign(), Some("G"));

        let mut part = Stream::with_kind(StreamKind::Part);
        part.push(measure);
        assert!(part.clef().is_none(), "a measure's clef is not its part's");
    }

    #[test]
    fn a_streams_duration_is_its_highest_time() {
        let mut stream = Stream::new();
        assert_eq!(stream.duration().unwrap().quarter_length(), 0.0);
        stream.repeat_insert(
            &Note::from_name("C4").unwrap().into(),
            &[0.0, 1.0, 2.0, 3.0],
        );
        assert_eq!(stream.duration().unwrap().quarter_length(), 4.0);
        stream.insert(FloatType::INFINITY, Clef::treble());
        assert!(stream.duration().is_err());
    }

    #[test]
    fn an_element_is_found_by_its_id_in_any_case() {
        let mut note = Note::from_name("C4").unwrap();
        note.set_id(Some("green".to_string()));
        let mut stream = Stream::new();
        stream.push(Rest::default());
        stream.push(note);
        assert_eq!(stream.element_by_id("Green").unwrap().offset(), 1.0);
        assert!(stream.element_by_id("blue").is_none());

        // only this stream's own elements are looked at
        let mut outer = Stream::new();
        outer.push(stream);
        assert!(outer.element_by_id("green").is_none());
    }

    /// A part of measures of these numbers, each a whole note long, the
    /// first opening with a bass clef and 4/4, a key change in the third.
    fn numbered_part(numbers: &[IntegerType]) -> Stream {
        let mut part = Stream::with_kind(StreamKind::Part);
        for (index, &number) in numbers.iter().enumerate() {
            let mut measure = Stream::with_kind(StreamKind::Measure);
            measure.set_number(number);
            if index == 0 {
                measure.insert(0.0, Clef::bass());
                measure.insert(0.0, TimeSignature::new(4, 4).unwrap());
                measure.insert(0.0, KeySignature::new(1));
            }
            if index == 2 {
                measure.insert(0.0, KeySignature::new(-2));
            }
            measure.push(
                Note::from_name("C3")
                    .unwrap()
                    .with_duration(Duration::whole()),
            );
            part.push(measure);
        }
        part
    }

    #[test]
    fn a_measure_is_found_by_its_number() {
        let part = numbered_part(&[0, 1, 2, 3]);
        assert_eq!(part.measure(0).unwrap().number(), 0);
        assert_eq!(part.measure(2).unwrap().number(), 2);
        assert!(part.measure(9).is_none());
        assert_eq!(part.measure(-1).unwrap().number(), 3);
        assert_eq!(part.measure(-4).unwrap().number(), 0);
        assert!(part.measure(-5).is_none());

        // all numbered nought: counted from one
        let unnumbered = numbered_part(&[0, 0, 0]);
        assert!(unnumbered.measure(0).is_none());
        assert_eq!(unnumbered.measure(2).unwrap().end_offset(), 4.0);
        assert!(std::ptr::eq(
            unnumbered.measure(2).unwrap(),
            unnumbered.measures()[1]
        ));
    }

    #[test]
    fn measures_between_collect_what_is_in_force() {
        let part = numbered_part(&[1, 2, 3, 4]);
        let excerpt = part.measures_between(2, Some(3));
        assert_eq!(excerpt.kind(), StreamKind::Part);
        let classes: Vec<&str> = excerpt
            .events()
            .iter()
            .map(|event| event.element().music21_classes()[0])
            .collect();
        assert_eq!(
            classes,
            [
                "BassClef",
                "KeySignature",
                "TimeSignature",
                "Measure",
                "Measure"
            ]
        );
        assert!(
            excerpt
                .events()
                .iter()
                .take(3)
                .all(|event| event.offset() == 0.0)
        );
        let numbers: Vec<IntegerType> = excerpt.measures().iter().map(|m| m.number()).collect();
        assert_eq!(numbers, [2, 3]);
        assert_eq!(excerpt.events()[4].offset(), 4.0);

        // the measure opening with a key of its own takes no other
        let from_three = part.measures_between(3, None);
        let keys = from_three
            .events()
            .iter()
            .filter(|event| event.element().is_instance("KeySignature"))
            .count();
        assert_eq!(keys, 0);
        assert_eq!(from_three.measures().len(), 2);

        // the first measure carries its own; nothing is collected
        assert_eq!(part.measures_between(1, Some(1)).len(), 1);
        assert!(part.measures_between(7, Some(9)).is_empty());
    }

    #[test]
    fn a_score_answers_measures_of_each_part() {
        let mut score = Stream::with_kind(StreamKind::Score);
        score.set_id(Some("full".to_string()));
        score.insert(0.0, numbered_part(&[1, 2, 3]));
        score.insert(0.0, numbered_part(&[1, 2, 3]));
        score.add_staff_group(StaffGroup::new(vec![0, 1]));
        let slice = score.measures_between(2, Some(2));
        assert_eq!(slice.kind(), StreamKind::Score);
        assert_eq!(slice.id(), Some("full"));
        assert_eq!(slice.parts().len(), 2);
        assert_eq!(slice.parts()[1].measures().len(), 1);
        assert_eq!(slice.staff_groups().len(), 1);
    }

    #[test]
    fn stream_transposes_notes_and_chords() {
        let mut stream = Stream::new();
        stream.push(Note::from_name("C4").unwrap());
        stream.push(Chord::new("E4 G4").unwrap());
        let out = stream
            .transpose(&Interval::from_name("M2").unwrap())
            .unwrap();
        let names = out
            .pitches()
            .iter()
            .map(Pitch::name_with_octave)
            .collect::<Vec<_>>();
        assert_eq!(names, vec!["D4", "F#4", "A4"]);
    }

    /// A score of one part of two measures, which is the shape music21 puts
    /// almost everything in.
    fn two_measure_score() -> Stream {
        let mut first = Stream::with_kind(StreamKind::Measure);
        first.insert(0.0, KeySignature::new(2));
        first.insert(0.0, TimeSignature::new(4, 4).unwrap());
        first.push(Note::from_name("D4").unwrap());
        first.push(Note::from_name("E4").unwrap());
        first.push(Note::from_name("F#4").unwrap());
        first.push(Note::from_name("G4").unwrap());

        let mut second = Stream::with_kind(StreamKind::Measure);
        second.insert(0.0, KeySignature::new(-1));
        second.push(Note::from_name("A4").unwrap());
        second.push(Note::from_name("Bb4").unwrap());

        let mut part = Stream::with_kind(StreamKind::Part);
        part.push(first);
        part.push(second);

        let mut score = Stream::with_kind(StreamKind::Score);
        score.push(part);
        score
    }

    #[test]
    fn a_nested_stream_flattens_onto_one_timeline() {
        let score = two_measure_score();
        assert_eq!(score.kind(), StreamKind::Score);
        assert_eq!(score.len(), 1, "a score holds its one part, not its notes");
        assert_eq!(score.parts().len(), 1);
        assert_eq!(score.parts()[0].measures().len(), 2);

        // the second measure starts a bar in, so its notes do too
        let notes = score.notes();
        let offsets: Vec<FloatType> = notes.iter().map(|(offset, _)| *offset).collect();
        assert_eq!(offsets, vec![0.0, 1.0, 2.0, 3.0, 4.0, 5.0]);
        assert_eq!(score.end_offset(), 6.0);

        let names: Vec<String> = score
            .pitches()
            .iter()
            .map(Pitch::name_with_octave)
            .collect();
        assert_eq!(names, ["D4", "E4", "F#4", "G4", "A4", "Bb4"]);

        // recurse sees the streams themselves; flatten does not
        assert_eq!(score.recurse().len(), 1 + 2 + 6 + 3);
        assert_eq!(score.flatten().len(), 6 + 3);
    }

    #[test]
    fn the_key_in_force_is_the_last_one_written_before_it() {
        let score = two_measure_score();
        assert_eq!(score.key_signature_at(0.0).unwrap().sharps(), 2);
        assert_eq!(score.key_signature_at(3.5).unwrap().sharps(), 2);
        // the second measure changes it
        assert_eq!(score.key_signature_at(4.0).unwrap().sharps(), -1);
        assert_eq!(score.key_signature_at(100.0).unwrap().sharps(), -1);
        assert_eq!(
            score.time_signature_at(5.0).unwrap().ratio_string(),
            "4/4",
            "a metre stays in force across the bar that follows it"
        );
        assert!(score.metronome_mark_at(0.0).is_none());

        // nothing is in force before the first mark
        let mut late = Stream::new();
        late.insert(2.0, KeySignature::new(3));
        assert!(late.key_signature_at(1.0).is_none());
        assert_eq!(late.key_signature_at(2.0).unwrap().sharps(), 3);
    }

    #[test]
    fn transposing_a_score_moves_its_key_signatures_too() {
        let score = two_measure_score();
        let up = score
            .transpose(&Interval::from_name("M2").unwrap())
            .unwrap();
        assert_eq!(up.key_signature_at(0.0).unwrap().sharps(), 4);
        assert_eq!(up.key_signature_at(4.0).unwrap().sharps(), 1);
        let names: Vec<String> = up.pitches().iter().map(Pitch::name_with_octave).collect();
        assert_eq!(names, ["E4", "F#4", "G#4", "A4", "B4", "C5"]);
        assert_eq!(up.kind(), StreamKind::Score);
    }
}