audio_core/
write_buf.rs

1/// Trait used to govern sequential writing to an audio buffer.
2///
3/// This is the "out" part of "buffered I/O". It allows for buffers to govern
4/// which slice of frames in them has been read so that operations can be
5/// performed in multiple stages.
6///
7/// This can be accomplished manually using available buffer combinators such as
8/// [Buf::tail][crate::Buf::tail]. But buffered I/O allows us to do this in a
9/// much more structured fashion.
10///
11/// # Examples
12///
13/// ```
14/// use audio::WriteBuf;
15/// use audio::{io, wrap};
16/// # fn recv_data(buf: &mut [i16]) {}
17///
18/// // A simple buffer we want to read from to. Fits 2 channels with 64
19/// // frames each.
20/// let mut from = [0i16; 128];
21///
22/// // A buffer we want to write to. 2 channels with 512 frames each.
23/// let to = audio::interleaved![[0i16; 512]; 2];
24/// let mut to = io::Write::new(to);
25///
26/// let mut steps = 0;
27///
28/// while to.has_remaining_mut() {
29///     // Fill the buffer with something interesting.
30///     recv_data(&mut from[..]);
31///
32///     // Wrap the filled buffer according to format so it can be written to
33///     // correctly.
34///     io::copy_remaining(wrap::interleaved(&mut from[..], 2), &mut to);
35///
36///     steps += 1;
37/// }
38///
39/// // We needed to write 8 times to fill our entire buffer.
40/// assert_eq!(steps, 8);
41/// ```
42pub trait WriteBuf {
43    /// Test if this buffer has remaining mutable frames that can be written.
44    ///
45    /// # Examples
46    ///
47    /// ```
48    /// use audio::WriteBuf;
49    ///
50    /// let mut buf = [0, 1, 2, 3, 4, 5, 6, 7];
51    /// let mut buf = audio::wrap::interleaved(&mut buf[..], 2);
52    ///
53    /// assert!(buf.has_remaining_mut());
54    /// assert_eq!(buf.remaining_mut(), 4);
55    /// buf.advance_mut(4);
56    /// assert_eq!(buf.remaining_mut(), 0);
57    /// ```
58    fn has_remaining_mut(&self) -> bool {
59        self.remaining_mut() > 0
60    }
61
62    /// Remaining number of frames that can be written.
63    ///
64    /// # Examples
65    ///
66    /// ```
67    /// use audio::WriteBuf;
68    ///
69    /// let mut buf = [0, 1, 2, 3, 4, 5, 6, 7];
70    /// let buf = audio::wrap::interleaved(&mut buf[..], 2);
71    ///
72    /// assert_eq!(buf.remaining_mut(), 4);
73    /// ```
74    fn remaining_mut(&self) -> usize;
75
76    /// Advance the number of frames that have been written.
77    ///
78    /// # Examples
79    ///
80    /// ```
81    /// use audio::WriteBuf;
82    ///
83    /// let mut buf = [0, 1, 2, 3, 4, 5, 6, 7];
84    /// let mut buf = audio::wrap::interleaved(&mut buf[..], 2);
85    ///
86    /// assert_eq!(buf.remaining_mut(), 4);
87    /// buf.advance_mut(2);
88    /// assert_eq!(buf.remaining_mut(), 2);
89    /// ```
90    fn advance_mut(&mut self, n: usize);
91}
92
93impl<B> WriteBuf for &mut B
94where
95    B: WriteBuf,
96{
97    fn has_remaining_mut(&self) -> bool {
98        (**self).has_remaining_mut()
99    }
100
101    fn remaining_mut(&self) -> usize {
102        (**self).remaining_mut()
103    }
104
105    fn advance_mut(&mut self, n: usize) {
106        (**self).advance_mut(n);
107    }
108}
audio_core/write_buf.rs

audio_core/
write_buf.rs
