Make API explicit about what it's getting/iterating

[Be-ing]

This renames Buf::get -> Buf::get_channel & Buf::iter -> Buf::iter_channels and likewise for BufMut. This emphasizes that these functions refer to channels rather than frames without needing to read the documentation.

[Be-ing]

This was unfortunately cumbersome to rename because rust-analyzer doesn't work in doc tests. :/

[Be-ing]

I was considering renaming the get/iter functions on Channel/ChannelMut and Frame/FrameMut as well, but I'm not sure that's helpful because it's unambiguous what those functions refer to.

[Be-ing]

Sequential/Interleaved/Dynamic::resize and resize_channels are kinda confusingly named as well. Does resize_channels resize the number of channels, or resize how big each channel is? The name could reasonably be understood either way, so reading the documentation is required to clarify. Perhaps it would be better to rename these to set_frames/set_channels or set_num_frames/set_num_channels?

[udoprog]

🤔

I'm torn. On one hand I see your point. get_channel describes what you're doing better especially once there is different things. But it's a shame to give up on a solid set of default naming conventions. It might just be more beneficial to pick one as the more common one and provide it.

Changing this also implies that we should rename other associated methods and types (like you wrote initially):

• iter_channels / iter_channels_mut.
• Buf::Iter / BufMut::IterMut.
• get / get_channel.

The Buf::skip, Buf::tail, and Buf::limit APIs might also be up for grabs.

I'd suggesting holding of with the refactoring for now until the API is more complete and vetted against third party projects (#21). It might become clearer if one use case is more of a default then.

Perhaps it would be better to rename these to set_frames/set_channels or set_num_frames/set_num_channels?

set_* probably isn't the best naming convention, it implies that something is being cheaply updated in my mind. Something using resize for "maybe expensive operation" has precedence in std.

[Be-ing]

set_* probably isn't the best naming convention, it implies that something is being cheaply updated in my mind. Something using resize for "maybe expensive operation" has precedence in std.

How about resize_channels and resize_frames?

[udoprog]

Yeah, that works for me! Resizing both is currently called resize_topology.

[Be-ing]

I'd suggesting holding of with the refactoring for now until the API is more complete and vetted against third party projects (#21).

I made this PR because of how I wanted the code in my project (https://codeberg.org/moire/moire/pulls/91) to look. Currently, in the main branch of Moire, I'm using Vec<Vec<f32>> for buffers. Sure I can iterate over those like:

for channel in buffer.iter_mut()
   for sample in channel {
       *sample = 0.0;
   }
}

But it's just a Vec of Vecs; there's no meaning communicated in the type's API beyond that. Anyone writing code to work with those buffers has to somehow know that buffer.iter_mut() iterates over the channels rather than the frames. Whereas with the Buf trait, it knows the difference between a channel and a frame, so that can be unambiguously communicated with buffer.iter_channels_mut().

[udoprog]

So what seems to be left is renaming associated types:

• Buf::Iter -> Buf::IterChannels.
• BufMut::IterMut -> ButMut::IterChannelsMut.

And renaming any appropriate resize functions (resize_channels and resize_frames).

Also this associated type should be adjusted to follow the proposed scheme:

• UniformBuf::FramesIter -> UniformBuf::IterFrames.

I don't see anything else right now, but if you see it, change it!

[udoprog]

Also if you want to do this more incrementally I'm OK with merging as-is and I can pick up some of the remaining pieces.

[Be-ing]

Is there a reason that the ResizeBuf trait is implemented as wrappers around methods on the structs?

impl<T> ResizableBuf for Sequential<T>
where
    T: Sample,
{
    fn try_reserve(&mut self, capacity: usize) -> bool {
        self.reserve(capacity);
        true
    }

    fn resize_frames(&mut self, frames: usize) {
        Self::resize_frames(self, frames);
    }

    fn resize_topology(&mut self, channels: usize, frames: usize) {
        Self::resize_frames(self, frames);
        Self::resize_channels(self, channels);
    }
}

Why not move the implementation of try_reserve and resize_frames into this impl ResizableBuf?

[Be-ing]

Also if you want to do this more incrementally I'm OK with merging as-is and I can pick up some of the remaining pieces.

I already took care of the other renames. :)

[udoprog]

Rebased