Struct audio_core::ChannelMut

pub struct ChannelMut<'a, T> { /* fields omitted */ }

The mutable buffer of a single channel.

This doesn’t provide direct access to the underlying buffer, but rather allows us to copy data usinga number of utility functions.

See ChannelsMut::channel_mut.

Implementations

impl<'a, T> ChannelMut<'a, T>

pub fn linear(buf: &'a mut [T]) -> Self

Construct a mutable linear channel buffer.

The buffer provided as-is constitutes the frames of the channel.

Examples

use audio::ChannelMut;

let buf = &mut [1, 3, 5, 7];
let mut channel = ChannelMut::linear(buf);

assert_eq!(channel[1], 3);
assert_eq!(channel[2], 5);

channel[1] *= 4;

assert_eq!(buf, &[1, 12, 5, 7]);

pub fn interleaved(buf: &'a mut [T], channels: usize, channel: usize) -> Self

Construct a mutable interleaved channel buffer.

The provided buffer must be the complete buffer, which includes all other channels. The provided channels argument is the total number of channels in this buffer, and channel indicates which specific channel this buffer belongs to.

Note that this is typically not used directly, but instead through an abstraction which makes sure to provide the correct parameters.

Examples

use audio::ChannelMut;

let buf = &mut [1, 2, 3, 4, 5, 6, 7, 8];
let mut channel = ChannelMut::interleaved(buf, 2, 1);

assert_eq!(channel[1], 4);
assert_eq!(channel[2], 6);

channel[1] *= 4;

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

pub fn into_ref(self) -> Channel<'a, T>

Convert the current mutable channel into a Channel with the lifetime matching the underlying buffer.

This is required in order to fully convert a ChannelMut into a Channel with the lifetime associated with the buffer, because if we only use as_ref we’ll actually be creating a reference to the mutable buffer instead.

Examples

use audio::{Channel, ChannelMut};

struct Foo<'a> {
    channel: ChannelMut<'a, i16>,
}

impl<'a> Foo<'a> {
    fn into_channel(self) -> Channel<'a, i16> {
        self.channel.into_ref()
    }
}

In contrast, this doesn’t compile:

use audio::{Channel, ChannelMut};

struct Foo<'a> {
    channel: ChannelMut<'a, i16>,
}

impl<'a> Foo<'a> {
    fn into_channel(self) -> Channel<'a, i16> {
        self.channel.as_ref()
    }
}

With the following error:

   error[E0515]: cannot return value referencing local data `self.channel`
   --> test.rs:11:9
    |
 11 |         self.channel.as_ref()
    |         ------------^^^^^^^^^
    |         |
    |         returns a value referencing data owned by the current function
    |         `self.channel` is borrowed here

pub fn as_ref(&self) -> Channel<'_, T>

Construct a new Channel reference with a lifetime associated with the current channel instance instead of the underlying buffer.

Examples

use audio::{Channel, ChannelMut};

let buf = &mut [1, 2, 3, 4];
let channel = ChannelMut::linear(buf);

let channel1 = channel.as_ref();
let channel2 = channel1; // Channel is Copy.

assert_eq!(channel1[0], channel2[0]);

pub fn as_mut(&mut self) -> ChannelMut<'_, T>

Construct a new mutable channel reference with a lifetime associated with the current channel instance instead of the underlying buffer.

Reborrowing like this is sometimes necessary, like if you want to pass an instance of ChannelMut directly into another function instead of borrowing it:

use audio::{ChannelsMut, ChannelMut};

fn takes_channel_mut(mut channel: ChannelMut<'_, i16>) {
    channel[1] = 42;
}

let mut buffer = audio::interleaved![[0; 4]; 2];
let mut channel = buffer.channel_mut(1);

takes_channel_mut(channel.as_mut());

assert_eq!(channel[1], 42);

Without the reborrow, we would end up moving the channel:

use audio::{ChannelsMut, ChannelMut};

fn takes_channel_mut(mut channel: ChannelMut<'_, i16>) {
    channel[1] = 42;
}

let mut buffer = audio::interleaved![[0; 4]; 2];
let mut channel = buffer.channel_mut(1);

takes_channel_mut(channel);

assert_eq!(channel[1], 42);

Causing the following error:

   error[E0382]: borrow of moved value: `channel`
   --> test.rs:10:12
    |
 10 | let mut channel = buffer.channel_mut(1);
    |     ----------- move occurs because `channel` has type `ChannelMut<'_, i16>`,
    |                 which does not implement the `Copy` trait
 11 |
 12 | takes_channel_mut(channel);
    |                   ------- value moved here
 13 |
 14 | assert_eq!(channel[1], 42);
    |            ^^^^^^^ value borrowed here after move

pub fn frames(&self) -> usize

The number of frames in the buffer.

Examples

use audio::ChannelsMut;

fn test(buf: &dyn ChannelsMut<f32>) {
    let left = buf.channel(0);
    let right = buf.channel(1);

    assert_eq!(left.frames(), 16);
    assert_eq!(right.frames(), 16);
}

test(&audio::dynamic![[0.0; 16]; 2]);
test(&audio::sequential![[0.0; 16]; 2]);
test(&audio::interleaved![[0.0; 16]; 2]);

pub fn chunks(&self, chunk: usize) -> usize

The number of chunks that can fit with the given size.

Examples

use audio::ChannelsMut;

fn test(buf: &dyn ChannelsMut<f32>) {
    let left = buf.channel(0);
    let right = buf.channel(1);

    assert_eq!(left.chunks(4), 4);
    assert_eq!(right.chunks(4), 4);

    assert_eq!(left.chunks(6), 3);
    assert_eq!(right.chunks(6), 3);
}

test(&audio::dynamic![[0.0; 16]; 2]);
test(&audio::sequential![[0.0; 16]; 2]);
test(&audio::interleaved![[0.0; 16]; 2]);

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

Construct an iterator over the channel.

Examples

use audio::{Channels as _, ChannelsMut as _};

let mut left = audio::interleaved![[0.0f32; 4]; 2];
let mut right = audio::dynamic![[0.0f32; 4]; 2];

for (l, r) in left.channel_mut(0).iter_mut().zip(right.channel_mut(0)) {
    *l = 1.0;
    *r = 1.0;
}

assert!(left.channel(0).iter().eq(right.channel(0).iter()));

assert_eq!(left.as_slice(), &[1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 0.0]);
assert_eq!(&right[0], &[1.0, 1.0, 1.0, 1.0]);
assert_eq!(&right[1], &[0.0, 0.0, 0.0, 0.0]);

pub fn iter_mut(self) -> IterMut<'a, T>

Construct a mutable iterator over the channel.

Examples

use audio::{Channels as _, ChannelsMut as _};

let mut left = audio::interleaved![[0.0f32; 4]; 2];
let mut right = audio::dynamic![[0.0f32; 4]; 2];

for (l, r) in left.channel_mut(0).iter_mut().zip(right.channel_mut(0)) {
    *l = 1.0;
    *r = 1.0;
}

assert!(left.channel(0).iter().eq(right.channel(0).iter()));

assert_eq!(left.as_slice(), &[1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 0.0]);
assert_eq!(&right[0], &[1.0, 1.0, 1.0, 1.0]);
assert_eq!(&right[1], &[0.0, 0.0, 0.0, 0.0]);

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

Construct a channel buffer where the first n frames are skipped.

Examples

use audio::{Channels as _, ChannelsMut as _};

let mut buffer = audio::Interleaved::with_topology(2, 4);

buffer.channel_mut(0).skip(2).copy_from_slice(&[1.0, 1.0]);

assert_eq!(buffer.as_slice(), &[0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0, 0.0])

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

Construct a channel buffer where the last n frames are included.

Examples

use audio::{Channels as _, ChannelsMut as _};

let from = audio::interleaved![[1.0f32; 4]; 2];
let mut to = audio::interleaved![[0.0f32; 4]; 2];

to.channel_mut(0).as_mut().tail(2).copy_from(from.channel(0));
assert_eq!(to.as_slice(), &[0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0, 0.0]);

pub fn limit(self, limit: usize) -> Self

Limit the channel bufferto limit number of frames.

Examples

use audio::{Channels as _, ChannelsMut as _};

let from = audio::interleaved![[1.0f32; 4]; 2];
let mut to = audio::interleaved![[0.0f32; 4]; 2];

to.channel_mut(0).limit(2).copy_from(from.channel(0));
assert_eq!(to.as_slice(), &[1.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0]);

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

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

Which is the range n * len .. n * len + len.

Examples

use audio::{Channels as _, ChannelsMut as _};

let from = audio::interleaved![[1.0f32; 4]; 2];
let mut to = audio::interleaved![[0.0f32; 4]; 2];

to.channel_mut(0).chunk(1, 2).copy_from(from.channel(0));
assert_eq!(to.as_slice(), &[0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0, 0.0]);

Examples

use audio::Channels;

fn test(buf: &dyn Channels<f32>) {
    let channel = buf.channel(0);

    let mut buf = vec![0.0; 4];
    channel.chunk(3, 4).copy_into_slice(&mut buf[..]);

    assert!(buf.iter().all(|f| *f == 1.0));
}

test(&audio::dynamic![[1.0; 16]; 2]);
test(&audio::sequential![[1.0; 16]; 2]);
test(&audio::interleaved![[1.0; 16]; 2]);

pub fn copy_from_slice(&mut self, buf: &[T]) where
    T: Copy, 

Copy from the given slice.

Examples

use audio::ChannelsMut;

fn test(buf: &mut dyn ChannelsMut<f32>) {
    buf.channel_mut(0).copy_from_slice(&[1.0; 4][..]);

    let mut out = vec![0.0; 8];
    buf.channel(0).copy_into_slice(&mut out);

    assert_eq!(out, vec![1.0, 1.0, 1.0, 1.0, 0.0, 0.0, 0.0, 0.0]);
}

test(&mut audio::dynamic![[0.0; 8]; 2]);
test(&mut audio::sequential![[0.0; 8]; 2]);
test(&mut audio::interleaved![[0.0; 8]; 2]);

pub fn copy_from_iter<I>(&mut self, iter: I) where
    I: IntoIterator<Item = T>, 

Copy a chunked destination from an iterator.

Examples

use audio::ChannelsMut;

fn test(buf: &mut dyn ChannelsMut<f32>) {
    buf.channel_mut(0).skip(2).copy_from_iter(vec![1.0; 4]);

    let mut out = vec![0.0; 8];
    buf.channel(0).copy_into_slice(&mut out);

    assert_eq!(out, vec![0.0, 0.0, 1.0, 1.0, 1.0, 1.0, 0.0, 0.0]);
}

test(&mut audio::dynamic![[0.0; 8]; 2]);
test(&mut audio::sequential![[0.0; 8]; 2]);
test(&mut audio::interleaved![[0.0; 8]; 2]);

use audio::ChannelsMut;

fn test(buf: &mut dyn ChannelsMut<f32>) {
    buf.channel_mut(0).skip(2).chunk(0, 2).copy_from_iter(vec![1.0; 4]);

    let mut out = vec![0.0; 8];
    buf.channel(0).copy_into_slice(&mut out);

    assert_eq!(out, vec![0.0, 0.0, 1.0, 1.0, 0.0, 0.0, 0.0, 0.0]);
}

test(&mut audio::dynamic![[0.0; 8]; 2]);
test(&mut audio::sequential![[0.0; 8]; 2]);
test(&mut audio::interleaved![[0.0; 8]; 2]);

pub fn copy_from(&mut self, from: Channel<'_, T>) where
    T: Copy, 

Copy this channel from another.

Examples

use audio::{Channels as _, ChannelsMut as _};

let from = audio::dynamic![[1.0f32; 4]; 2];
let mut to = audio::interleaved![[0.0f32; 4]; 3];

to.channel_mut(0).copy_from(from.channel(1));
assert_eq!(to.as_slice(), &[1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0, 0.0]);

pub fn translate_from<U>(&mut self, from: Channel<'_, U>) where
    U: Copy,
    T: Translate<U>, 

Translate this channel from another.

This will translate each sample in the channel through the appropriate Translate implementation.

This is used for converting a buffer containing one type of sample into another.

Examples

use audio::{Channels as _, ChannelsMut as _};

let from = audio::dynamic![[u16::MAX; 4]; 2];
let mut to = audio::interleaved![[0.0f32; 4]; 3];

to.channel_mut(0).translate_from(from.channel(1));
assert_eq!(to.as_slice(), &[1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 0.0, 0.0]);

Trait Implementations

impl<T> Debug for ChannelMut<'_, T> where
    T: Copy + Debug, 

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

Formats the value using the given formatter.

impl<T> Eq for ChannelMut<'_, T> where
    T: Copy + Eq, 

impl<T> Hash for ChannelMut<'_, T> where
    T: Copy + Hash, 

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

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 ChannelMut<'_, 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 ChannelMut<'_, T>

Get a mutable reference to the frame at the given index.

Panics

Panics if the given frame is out of bounds for this channel.

See frames.

Examples

use audio::ChannelsMut;

fn test(buf: &mut dyn ChannelsMut<f32>) {
    buf.channel_mut(0)[1] = 1.0;
    buf.channel_mut(0)[7] = 1.0;

    let mut out = vec![0.0; 8];
    buf.channel(0).copy_into_slice(&mut out);

    assert_eq!(out, vec![0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0]);
}

test(&mut audio::dynamic![[0.0; 8]; 2]);
test(&mut audio::sequential![[0.0; 8]; 2]);
test(&mut audio::interleaved![[0.0; 8]; 2]);

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

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

impl<'a, T> IntoIterator for ChannelMut<'a, T>

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T> IntoIterator for &'a mut ChannelMut<'_, T>

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T> Ord for ChannelMut<'_, T> where
    T: Copy + 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<ChannelMut<'_, T>> for ChannelMut<'_, T> where
    T: Copy + 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<ChannelMut<'_, T>> for ChannelMut<'_, T> where
    T: Copy + 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.