Clarification of indices in documentation

[joe-saronic]

The use of indices in the documentation (e.g., get) shows under-filled buffers, where the index in the view and the underlying buffer match. A couple of examples of how the index behaves in case of an overfilled buffer would be useful.

For example, given

use circular_buffer::CircularBuffer;

let mut buf = CircularBuffer::<3, char>::new();
buf.push_back('a');
buf.push_back('b');
buf.push_back('c');
buf.push_back('d');

Which of the following is correct?

assert_eq!(buf.get(0), Some(&'d'));

OR

assert_eq!(buf.get(0), Some(&'b'));

In the first case, the index is static relative to the underlying memory, which can be convenient. In the latter, the index of an element changes every time something is appended to the buffer. A corrolary of the former would be that it would be nice to have access to the index of the front and back. I would be happy to make a PR for some getters if this turns out to be the case.

The usecase I have in mind is that I want to buffer some data and grab some items that I've flagged in the past (that are still definitely within the buffer).

[andreacorbellini]

Hi, the second one (buf.get(0) returning 'b') is the expected behavior. In other words, get() returns elements relative to the front of the buffer. This behavior is consistent with VecDeque and other collections from the standard library.

Note that you can get the behavior you want by:

• using buf.back()
• using push_front instead of push_back, so that the front element is always the one that you added last, or
• using buf.iter().rev().next() to get the first element at the back of the buffer (or also buf.get(buf.len() - 1) if you can be sure that the buffer is not empty)

Using your example code:

use circular_buffer::CircularBuffer;

let mut buf = CircularBuffer::<3, char>::new();
buf.push_back('a');
buf.push_back('b');
buf.push_back('c');
buf.push_back('d');

assert_eq!(Some(&'b'), buf.get(0));
assert_eq!(Some(&'b'), buf.front());
assert_eq!(Some(&'b'), buf.iter().next());

assert_eq!(Some(&'d'), buf.back());
assert_eq!(Some(&'d'), buf.iter().rev().next());
assert_eq!(Some(&'d'), buf.get(buf.len() - 1));
assert_eq!(Some(&'d'), buf.len().checked_sub(1).and_then(|i| buf.get(i)));

I can consider accepting a PR that introduces new explicit get_front() and get_back() methods if there's a valid use case for them, but I think in your specific example front()/back() do exactly what you need.

[andreacorbellini]

For sure I'll improve the documentation if it's not clear enough on what indexes are relative to

[joe-saronic]

Thanks. I think adding the tests that you show here and adding explicit mention about consistency with VecDeque would be perfect for the docs and would solve 90% of my problem.

The remaining 10% of my problem is that I want to be able to hold on to a reference to the element I just pushed and the one behind it under certain circumstances. My idea was to do it by index, since I can't guarantee that a reference will be around long enough to use it, but I'll have to check before I cry wolf on that one :)

And again, thanks for making this package. It's well designed and convenient to use.