Struct audio::buf::sequential::Sequential

pub struct Sequential<T> { /* private fields */ }

A dynamically sized, multi-channel sequential audio buffer.

A sequential audio buffer stores all audio data sequentially in memory, one channel after another.

An audio buffer can only be resized if it contains a type which is sample-apt. For more information of what this means, see Sample.

Resizing the buffer might therefore cause a fair bit of copying, and for the worst cases, this might result in having to copy a memory region byte-by-byte since they might overlap.

Resized regions also aren’t zeroed, so certain operations might cause stale data to be visible after a resize.

let mut buf = audio::buf::Sequential::<f32>::with_topology(2, 4);
buf[0].copy_from_slice(&[1.0, 2.0, 3.0, 4.0]);
buf[1].copy_from_slice(&[2.0, 3.0, 4.0, 5.0]);

buf.resize_frames(3);

assert_eq!(&buf[0], &[1.0, 2.0, 3.0]);
assert_eq!(&buf[1], &[2.0, 3.0, 4.0]);

buf.resize_frames(4);

assert_eq!(&buf[0], &[1.0, 2.0, 3.0, 2.0]); // <- 2.0 is stale data.
assert_eq!(&buf[1], &[2.0, 3.0, 4.0, 5.0]); // <- 5.0 is stale data.

To access the full, currently assumed valid slice you can use Sequential::as_slice or Sequential::into_vec.

let mut buf = audio::buf::Sequential::<f32>::with_topology(2, 4);
buf[0].copy_from_slice(&[1.0, 2.0, 3.0, 4.0]);
buf[1].copy_from_slice(&[2.0, 3.0, 4.0, 5.0]);

buf.resize_frames(3);

assert_eq!(buf.as_slice(), &[1.0, 2.0, 3.0, 2.0, 3.0, 4.0]);

Implementations

impl<T> Sequential<T>

pub fn new() -> Self

Construct a new empty audio buffer.

Examples

let buf = audio::buf::Sequential::<f32>::new();

assert_eq!(buf.frames(), 0);

pub fn with_topology(channels: usize, frames: usize) -> Self

where T: Sample,

Allocate an audio buffer with the given topology. A “topology” is a given number of channels and the corresponding number of frames in their buffers.

Examples

let mut buf = audio::buf::Sequential::<f32>::with_topology(4, 256);

assert_eq!(buf.frames(), 256);
assert_eq!(buf.channels(), 4);

pub fn from_vec(data: Vec<T>, channels: usize, frames: usize) -> Self

Allocate an audio buffer from a fixed-size array.

See sequential!.

Examples

let buf = audio::sequential![[2.0; 256]; 4];

assert_eq!(buf.frames(), 256);
assert_eq!(buf.channels(), 4);

for chan in &buf {
    assert_eq!(chan.as_ref(), vec![2.0; 256]);
}

pub fn from_frames<const N: usize>(frames: [T; N], channels: usize) -> Self

where T: Copy,

Allocate an audio buffer from a fixed-size array acting as a template for all the channels.

See sequential!.

Examples

let buf = audio::buf::Sequential::from_frames([1.0, 2.0, 3.0, 4.0], 2);

assert_eq!(buf.frames(), 4);
assert_eq!(buf.channels(), 2);

assert_eq!(buf.as_slice(), &[1.0, 2.0, 3.0, 4.0, 1.0, 2.0, 3.0, 4.0]);

pub fn from_array<const F: usize, const C: usize>(channels: [[T; F]; C]) -> Self

where T: Copy,

Allocate a sequential audio buffer from a fixed-size array.

See sequential!.

Examples

let buf = audio::buf::Sequential::from_array([[1; 4]; 2]);

assert_eq!(buf.frames(), 4);
assert_eq!(buf.channels(), 2);

assert_eq! {
    buf.as_slice(),
    &[1, 1, 1, 1, 1, 1, 1, 1],
}

Using a specific array topology.

let buf = audio::buf::Sequential::from_array([[1, 2, 3, 4], [5, 6, 7, 8]]);

assert_eq!(buf.frames(), 4);
assert_eq!(buf.channels(), 2);

assert_eq! {
    buf.as_slice(),
    &[1, 2, 3, 4, 5, 6, 7, 8],
}

pub fn into_vec(self) -> Vec<T>

Take ownership of the backing vector.

Examples

let mut buf = audio::buf::Sequential::<f32>::with_topology(2, 4);
buf[0].copy_from_slice(&[1.0, 2.0, 3.0, 4.0]);
buf[1].copy_from_slice(&[2.0, 3.0, 4.0, 5.0]);

buf.resize_frames(3);

assert_eq!(buf.into_vec(), vec![1.0, 2.0, 3.0, 2.0, 3.0, 4.0])

pub fn as_slice(&self) -> &[T]

Access the underlying vector as a slice.

Examples

let mut buf = audio::buf::Sequential::<f32>::with_topology(2, 4);

buf[0].copy_from_slice(&[1.0, 2.0, 3.0, 4.0]);
buf[1].copy_from_slice(&[2.0, 3.0, 4.0, 5.0]);

buf.resize_frames(3);

assert_eq!(buf.as_slice(), &[1.0, 2.0, 3.0, 2.0, 3.0, 4.0])

pub fn as_slice_mut(&mut self) -> &mut [T]

Access the underlying vector as a mutable slice.

Examples

use audio::{Buf, Channel};

let mut buf = audio::buf::Sequential::<u32>::with_topology(2, 4);
buf.as_slice_mut().copy_from_slice(&[1, 2, 3, 4, 5, 6, 7, 8]);

assert_eq! {
    buf.get_channel(0).unwrap(),
    [1u32, 2, 3, 4],
};

assert_eq! {
    buf.get_channel(1).unwrap(),
    [5u32, 6, 7, 8],
};

assert_eq!(buf.as_slice(), &[1, 2, 3, 4, 5, 6, 7, 8]);

pub fn capacity(&self) -> usize

Get the capacity of the buffer in number of frames.

The underlying buffer over-allocates a bit, so this will report the exact capacity available in the buffer.

Examples

let mut buf = audio::buf::Sequential::<f32>::new();

assert_eq!(buf.capacity(), 0);

buf.resize_frames(11);
assert_eq!(buf.capacity(), 0);

buf.resize_channels(2);
assert_eq!(buf.capacity(), 22);

buf.resize_frames(12);
assert_eq!(buf.capacity(), 44);

buf.resize_frames(24);
assert_eq!(buf.capacity(), 44);

pub fn frames(&self) -> usize

Get how many frames there are in the buffer.

Examples

let mut buf = audio::buf::Sequential::<f32>::new();

assert_eq!(buf.frames(), 0);
buf.resize_frames(256);
assert_eq!(buf.frames(), 256);

pub fn channels(&self) -> usize

Get how many channels there are in the buffer.

Examples

let mut buf = audio::buf::Sequential::<f32>::new();

assert_eq!(buf.channels(), 0);
buf.resize_channels(2);
assert_eq!(buf.channels(), 2);

pub fn iter_channels(&self) -> IterChannels<'_, T>

Construct an iterator over all available channels.

Examples

use rand::Rng as _;

let buf = audio::buf::Sequential::<f32>::with_topology(4, 256);

let all_zeros = vec![0.0; 256];

for chan in buf.iter_channels() {
    assert_eq!(chan.as_ref(), &all_zeros[..]);
}

pub fn iter_channels_mut(&mut self) -> IterChannelsMut<'_, T>

Construct a mutable iterator over all available channels.

Examples

use rand::Rng as _;

let mut buf = audio::buf::Sequential::<f32>::with_topology(4, 256);
let mut rng = rand::thread_rng();

for mut chan in buf.iter_channels_mut() {
    rng.fill(chan.as_mut());
}

pub fn resize_channels(&mut self, channels: usize)

where T: Sample,

Set the number of channels in use.

If the size of the buffer increases as a result, the new channels will be zeroed. If the size decreases, the channels that falls outside of the new size will be dropped.

Examples

let mut buf = audio::buf::Sequential::<f32>::new();

assert_eq!(buf.channels(), 0);
assert_eq!(buf.frames(), 0);

buf.resize_channels(4);
buf.resize_frames(256);

assert_eq!(buf.channels(), 4);
assert_eq!(buf.frames(), 256);

pub fn resize_frames(&mut self, frames: usize)

where T: Sample,

Set the size of the buffer. The size is the size of each channel’s buffer.

If the size of the buffer increases as a result, the new regions in the frames will be zeroed. If the size decreases, the region will be left untouched. So if followed by another increase, the data will be “dirty”.

Examples

let mut buf = audio::buf::Sequential::<f32>::new();

assert_eq!(buf.channels(), 0);
assert_eq!(buf.frames(), 0);

buf.resize_channels(4);
buf.resize_frames(256);

assert_eq!(buf[1][128], 0.0);
buf[1][128] = 42.0;

assert_eq!(buf.channels(), 4);
assert_eq!(buf.frames(), 256);

Decreasing and increasing the size will modify the underlying buffer:

assert_eq!(buf[1][128], 0.0);
buf[1][128] = 42.0;

buf.resize_frames(64);
assert!(buf[1].get(128).is_none());

buf.resize_frames(256);
assert_eq!(buf[1][128], 0.0);

Stale data

Resizing a channel doesn’t “free” the underlying data or zero previously initialized regions.

Old regions which were previously sized out and ignored might contain stale data from previous uses. So this should be kept in mind when resizing this buffer dynamically.

let mut buf = audio::buf::Sequential::<f32>::new();

buf.resize_channels(4);
buf.resize_frames(128);

let expected = (0..128).map(|v| v as f32).collect::<Vec<_>>();

for mut chan in buf.iter_channels_mut() {
    for (s, v) in chan.iter_mut().zip(&expected) {
        *s = *v;
    }
}

assert_eq!(buf.get_channel(0).unwrap(), &expected[..]);
assert_eq!(buf.get_channel(1).unwrap(), &expected[..]);
assert_eq!(buf.get_channel(2).unwrap(), &expected[..]);
assert_eq!(buf.get_channel(3).unwrap(), &expected[..]);
assert!(buf.get_channel(4).is_none());

buf.resize_channels(2);

assert_eq!(buf.get_channel(0).unwrap(), &expected[..]);
assert_eq!(buf.get_channel(1).unwrap(), &expected[..]);
assert!(buf.get_channel(2).is_none());

// shrink
buf.resize_frames(64);

assert_eq!(buf.get_channel(0).unwrap(), &expected[..64]);
assert_eq!(buf.get_channel(1).unwrap(), &expected[..64]);
assert!(buf.get_channel(2).is_none());

// increase - this causes some weirdness.
buf.resize_frames(128);

let first_overlapping = expected[..64]
    .iter()
    .chain(expected[..64].iter())
    .copied()
    .collect::<Vec<_>>();

assert_eq!(buf.get_channel(0).unwrap(), &first_overlapping[..]);
// Note: second channel matches perfectly up with an old channel that was
// masked out.
assert_eq!(buf.get_channel(1).unwrap(), &expected[..]);
assert!(buf.get_channel(2).is_none());

pub fn get_channel(&self, channel: usize) -> Option<LinearChannel<'_, T>>

Get a reference to the buffer of the given channel.

Examples

let mut buf = audio::buf::Sequential::<f32>::new();

buf.resize_channels(4);
buf.resize_frames(256);

let expected = vec![0.0; 256];

assert_eq!(buf.get_channel(0).unwrap(), &expected[..]);
assert_eq!(buf.get_channel(1).unwrap(), &expected[..]);
assert_eq!(buf.get_channel(2).unwrap(), &expected[..]);
assert_eq!(buf.get_channel(3).unwrap(), &expected[..]);
assert!(buf.get_channel(4).is_none());

pub fn get_mut(&mut self, channel: usize) -> Option<LinearChannelMut<'_, T>>

Get a mutable reference to the buffer of the given channel.

Examples

use rand::Rng as _;

let mut buf = audio::buf::Sequential::<f32>::new();

buf.resize_channels(2);
buf.resize_frames(256);

let mut rng = rand::thread_rng();

if let Some(mut left) = buf.get_mut(0) {
    rng.fill(left.as_mut());
}

if let Some(mut right) = buf.get_mut(1) {
    rng.fill(right.as_mut());
}

pub fn reserve(&mut self, capacity: usize)

Reserve the given capacity in this buffer ensuring it can take at least capacity elements in total before needing to re-allocate again.

Trait Implementations

impl<T> Buf for Sequential<T>

where T: Copy,

type Sample = T

The type of a single sample.

type Channel<'this> = LinearChannel<'this, <Sequential<T> as Buf>::Sample> where Self::Sample: 'this

The type of the channel container.

type IterChannels<'this> = IterChannels<'this, T> where Self: 'this

An iterator over available channels.

fn frames_hint(&self) -> Option<usize>

A typical number of frames for each channel in the buffer, if known.

fn channels(&self) -> usize

The number of channels in the buffer.

fn get_channel(&self, channel: usize) -> Option<Self::Channel<'_>>

Return a handler to the buffer associated with the channel.

fn iter_channels(&self) -> Self::IterChannels<'_>

Construct an iterator over all the channels in the audio buffer.

fn skip(self, n: usize) -> Skip<Self>

where Self: Sized,

Construct a wrapper around this buffer that skips the first n frames.

fn tail(self, n: usize) -> Tail<Self>

where Self: Sized,

Construct a wrapper around this buffer that skips to the last n frames.

fn limit(self, limit: usize) -> Limit<Self>

where Self: Sized,

Construct a wrapper around this buffer which stops after limit frames.

impl<T> BufMut for Sequential<T>

where T: Copy,

type ChannelMut<'this> = LinearChannelMut<'this, <Sequential<T> as Buf>::Sample> where Self: 'this

The type of the mutable channel container.

type IterChannelsMut<'this> = IterChannelsMut<'this, T> where Self: 'this

A mutable iterator over available channels.

fn get_channel_mut(&mut self, channel: usize) -> Option<Self::ChannelMut<'_>>

Return a mutable handler to the buffer associated with the channel.

fn copy_channel(&mut self, from: usize, to: usize)

Copy one channel into another.

fn iter_channels_mut(&mut self) -> Self::IterChannelsMut<'_>

Construct a mutable iterator over available channels.

fn fill(&mut self, value: T)

where T: Copy,

Fill the entire buffer with the specified value

impl<T> Debug for Sequential<T>

where T: Debug,

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

Formats the value using the given formatter.

impl<T: Default> Default for Sequential<T>

fn default() -> Sequential<T>

Returns the “default value” for a type.

impl<T> ExactSizeBuf for Sequential<T>

where T: Copy,

fn frames(&self) -> usize

The number of frames in a buffer.

impl<T> Hash for Sequential<T>

where T: Hash,

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Index<usize> for Sequential<T>

type Output = [T]

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T> IndexMut<usize> for Sequential<T>

fn index_mut(&mut self, index: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<'a, T> IntoIterator for &'a Sequential<T>

type IntoIter = IterChannels<'a, T>

Which kind of iterator are we turning this into?

type Item = <<&'a Sequential<T> as IntoIterator>::IntoIter as Iterator>::Item

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T> IntoIterator for &'a mut Sequential<T>

type IntoIter = IterChannelsMut<'a, T>

Which kind of iterator are we turning this into?

type Item = <<&'a mut Sequential<T> as IntoIterator>::IntoIter as Iterator>::Item

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T> Ord for Sequential<T>

where T: Ord,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<T> PartialEq for Sequential<T>

where T: PartialEq,

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd for Sequential<T>

where T: PartialOrd,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> ResizableBuf for Sequential<T>

where T: Sample,

fn try_reserve(&mut self, capacity: usize) -> bool

Ensure that the audio buffer has space for at least the given capacity of contiguous memory. The capacity is specified in number of Samples.

fn resize_frames(&mut self, frames: usize)

Resize the number of per-channel frames in the buffer.

fn resize_topology(&mut self, channels: usize, frames: usize)

Resize the buffer to match the given topology.

impl<T> UniformBuf for Sequential<T>

where T: Copy,

type Frame<'this> = SequentialFrame<'this, T> where Self: 'this

The type the channel assumes when coerced into a reference.

type IterFrames<'this> = SequentialFramesIter<'this, T> where Self: 'this

A borrowing iterator over the channel.

fn get_frame(&self, frame: usize) -> Option<Self::Frame<'_>>

Get a single frame at the given offset.

fn iter_frames(&self) -> Self::IterFrames<'_>

Construct an iterator over all the frames in the audio buffer.

impl<T> Eq for Sequential<T>

where T: Eq,