Struct Arena

pub struct Arena { /* private fields */ }

Helps overcome limitations of the lifetime system when constructing MIDI events and files.

Because many events contain references to data that outlives them, it can be hard to build a MIDI file programatically.

Consider the following code:

use midly::{TrackEvent, TrackEventKind, MetaMessage};

let mut track = Vec::new();
for i in 0..64 {
    let marker_name = format!("Marker {}", i);
    let marker_ref = marker_name.as_bytes();
    track.push(TrackEvent {
        delta: 0.into(),
        kind: TrackEventKind::Meta(MetaMessage::Marker(marker_ref)),
    });
}

Looks pretty good, but it fails to compile with error[E0597]: "marker_name" does not live long enough, with a rightful reason: marker_name is dropped before the next iteration of the for loop.

Instead, use the Arena type like the following code:

use midly::{TrackEvent, TrackEventKind, MetaMessage};

let arena = midly::Arena::new();
let mut track = Vec::new();
for i in 0..64 {
    let marker_name = format!("Marker {}", i);
    let marker_ref = arena.add(marker_name.as_bytes());
    track.push(TrackEvent {
        delta: 0.into(),
        kind: TrackEventKind::Meta(MetaMessage::Marker(marker_ref)),
    });
}

This type is only available with the alloc feature enabled.

Implementations

impl Arena

pub fn new() -> Arena

Create a new empty arena.

pub fn clear(&mut self)

Empty this arena, deallocating all added bytes.

This method is safe to call because it requires a mutable reference.

pub fn len(&self) -> usize

Get the amount of allocations in the arena.

pub fn add<'a, 'b>(&'a self, bytes: &'b [u8]) -> &'a mut [u8]

Add a set of bytes to the arena, returning a longer-lived mutable reference to a copy of these same bytes.

pub fn add_vec<'a>(&'a self, bytes: Vec<u8>) -> &'a mut [u8]

Add a Vec<u8> to the arena, returning a long-lived mutable reference to its contents.

This method is very similar to add, but avoids an allocation and a copy.

pub fn add_u7<'a, 'b>(&'a self, databytes: &'b [u7]) -> &'a mut [u7]

Add a set of databytes to the arena, returning a longer-lived mutable reference to a copy of these same databytes.

pub fn add_u7_vec<'a>(&'a self, databytes: Vec<u7>) -> &'a mut [u7]

Add a Vec<u7> to the arena, returning a long-lived mutable reference to its contents.

This method is very similar to add_u7, but avoids an allocation and a copy.

Trait Implementations

impl Debug for Arena

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Arena

fn default() -> Arena

Returns the “default value” for a type.

impl Drop for Arena

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Arena