Struct rotary::sequential::Sequential

pub struct Sequential<T> where
    T: Sample,  { /* fields omitted */ }

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 is constrained to only support sample-apt types. 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> where
    T: Sample, 

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

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 dynamic!.

Examples

use rotary::BitSet;

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 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)

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)

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> where
    T: Sample, 

fn frames(&self) -> usize

The number of frames in a buffer.

fn channels(&self) -> usize

The number of channels in the buffer.

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

Return a handler to the buffer associated with the channel.

fn offset(self, offset: usize) -> Offset<Self> where
    Self: Sized, 

Offset the buffer to process by offset number of frames.

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

Limit the buffer to process by limit number of frames.

impl<T> BufMut<T> for Sequential<T> where
    T: Sample, 

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

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

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> Debug for Sequential<T> where
    T: Sample + Debug, 

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

Formats the value using the given formatter.

impl<T> Eq for Sequential<T> where
    T: Sample + Eq, 

impl<T> Hash for Sequential<T> where
    T: Sample + Hash, 

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl<T> Index<usize> for Sequential<T> where
    T: Sample, 

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> where
    T: Sample, 

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> where
    T: Sample, 

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

type Item = <Self::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> where
    T: Sample, 

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

type Item = <Self::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: Sample + Ord, 

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

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<T> PartialEq<Sequential<T>> for Sequential<T> where
    T: Sample + PartialEq, 

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

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

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialOrd<Sequential<T>> for Sequential<T> where
    T: Sample + PartialOrd, 

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

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

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

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

#[must_use]pub fn le(&self, other: &Rhs) -> bool

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

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

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

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

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