Struct 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 buffer = rotary::Sequential::<f32>::with_topology(2, 4);
buffer[0].copy_from_slice(&[1.0, 2.0, 3.0, 4.0]);
buffer[1].copy_from_slice(&[2.0, 3.0, 4.0, 5.0]);

buffer.resize(3);

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

buffer.resize(4);

assert_eq!(&buffer[0], &[1.0, 2.0, 3.0, 2.0]); // <- 2.0 is stale data.
assert_eq!(&buffer[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 buffer = rotary::Sequential::<f32>::with_topology(2, 4);
buffer[0].copy_from_slice(&[1.0, 2.0, 3.0, 4.0]);
buffer[1].copy_from_slice(&[2.0, 3.0, 4.0, 5.0]);

buffer.resize(3);

assert_eq!(buffer.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 mut buffer = rotary::Sequential::<f32>::new();

assert_eq!(buffer.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 buffer = rotary::Sequential::<f32>::with_topology(4, 256);

assert_eq!(buffer.frames(), 256);
assert_eq!(buffer.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 mut buffer = rotary::sequential![[2.0; 256]; 4];

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

for chan in &buffer {
    assert_eq!(chan, 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 mut buffer = rotary::Sequential::from_frames([1.0, 2.0, 3.0, 4.0], 2);

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

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

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

Take ownership of the backing vector.

Examples

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

buffer.resize(3);

assert_eq!(buffer.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 buffer = rotary::Sequential::<f32>::with_topology(2, 4);

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

buffer.resize(3);

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

pub fn frames(&self) -> usize

Get the number of frames in the channels of an audio buffer.

Examples

let mut buffer = rotary::Sequential::<f32>::new();

assert_eq!(buffer.frames(), 0);
buffer.resize(256);
assert_eq!(buffer.frames(), 256);

pub fn channels(&self) -> usize

Check how many channels there are in the buffer.

Examples

let mut buffer = rotary::Sequential::<f32>::new();

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

pub fn iter(&self) -> Iter<'_, T>

Construct an iterator over all available channels.

Examples

use rand::Rng as _;

let mut buffer = rotary::Sequential::<f32>::with_topology(4, 256);

let all_zeros = vec![0.0; 256];

for chan in buffer.iter() {
    assert_eq!(chan, &all_zeros[..]);
}

pub fn iter_mut(&mut self) -> IterMut<'_, T>

Construct a mutable iterator over all available channels.

Examples

use rand::Rng as _;

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

for chan in buffer.iter_mut() {
    rng.fill(chan);
}

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 buffer = rotary::Sequential::<f32>::new();

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

buffer.resize_channels(4);
buffer.resize(256);

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

pub fn resize(&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 buffer = rotary::Sequential::<f32>::new();

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

buffer.resize_channels(4);
buffer.resize(256);

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

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

Decreasing and increasing the size will modify the underlying buffer:

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

buffer.resize(64);
assert!(buffer[1].get(128).is_none());

buffer.resize(256);
assert_eq!(buffer[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 buffer = rotary::Sequential::<f32>::new();

buffer.resize_channels(4);
buffer.resize(128);

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

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

assert_eq!(buffer.get(0), Some(&expected[..]));
assert_eq!(buffer.get(1), Some(&expected[..]));
assert_eq!(buffer.get(2), Some(&expected[..]));
assert_eq!(buffer.get(3), Some(&expected[..]));
assert_eq!(buffer.get(4), None);

buffer.resize_channels(2);

assert_eq!(buffer.get(0), Some(&expected[..]));
assert_eq!(buffer.get(1), Some(&expected[..]));
assert_eq!(buffer.get(2), None);

// shrink
buffer.resize(64);

assert_eq!(buffer.get(0), Some(&expected[..64]));
assert_eq!(buffer.get(1), Some(&expected[..64]));
assert_eq!(buffer.get(2), None);

// increase - this causes some weirdness.
buffer.resize(128);

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

assert_eq!(buffer.get(0), Some(&first_overlapping[..]));
// Note: second channel matches perfectly up with an old channel that was
// masked out.
assert_eq!(buffer.get(1), Some(&expected[..]));
assert_eq!(buffer.get(2), None);

pub fn get(&self, channel: usize) -> Option<&[T]>

Get a reference to the buffer of the given channel.

Examples

let mut buffer = rotary::Sequential::<f32>::new();

buffer.resize_channels(4);
buffer.resize(256);

let expected = vec![0.0; 256];

assert_eq!(Some(&expected[..]), buffer.get(0));
assert_eq!(Some(&expected[..]), buffer.get(1));
assert_eq!(Some(&expected[..]), buffer.get(2));
assert_eq!(Some(&expected[..]), buffer.get(3));
assert_eq!(None, buffer.get(4));

pub fn get_mut(&mut self, channel: usize) -> Option<&mut [T]>

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

Examples

use rand::Rng as _;

let mut buffer = rotary::Sequential::<f32>::new();

buffer.resize_channels(2);
buffer.resize(256);

let mut rng = rand::thread_rng();

if let Some(left) = buffer.get_mut(0) {
    rng.fill(left);
}

if let Some(right) = buffer.get_mut(1) {
    rng.fill(right);
}

Trait Implementations

impl<T> Buf<T> for Sequential<T>

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

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

fn channels(&self) -> usize

The number of channels in the buffer.

fn channel(&self, channel: usize) -> Channel<'_, T>

Return a handler to the buffer associated with the channel.

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

where Self: Sized,

Construct a new buffer where n frames are skipped.

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

where Self: Sized,

Construct a new buffer where n frames are skipped.

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

where Self: Sized,

Limit the channel buffer to limit number of frames.

fn chunk(self, n: usize, len: usize) -> Chunk<Self>

where Self: Sized,

Construct a range of frames corresponds to the chunk with len and position n.

impl<T> BufMut<T> for Sequential<T>

fn channel_mut(&mut self, channel: usize) -> ChannelMut<'_, T>

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

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> ExactSizeBuf for Sequential<T>

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 = Iter<'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 = IterMut<'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,

Restrict a value to a certain interval.

impl<T> PartialEq for Sequential<T>

where T: PartialEq,

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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 resize(&mut self, frames: usize)

Resize the number of frames in the buffer.

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

Resize the buffer to match the given topology.

impl<T> Eq for Sequential<T>

where T: Eq,