The semantic of `push_overwrite` is a bit strange

[xmh0511]

use ringbuf::{traits::*, HeapRb};

let mut rb = HeapRb::<i32>::new(2);

assert_eq!(rb.push_overwrite(0), None);
assert_eq!(rb.push_overwrite(1), None);
assert_eq!(rb.push_overwrite(2), Some(0));

assert_eq!(rb.try_pop(), Some(1));
assert_eq!(rb.try_pop(), Some(2));
assert_eq!(rb.try_pop(), None);

In this example, the capacity of the ring buffer is 2, and the operation rb.push_overwrite(1) pushed the latest element such that the ring buffer is full. As said in the document

Pushes an item to the ring buffer overwriting the latest item if the buffer is full.
Returns overwritten item if overwriting took place.

Doesn't the latest item have value 1? rb.push_overwrite(2) should overwrite 1, and the subsequent pop operations should return Some(0) and Some(2).

The current example looks like rb.push_overwrite(2) overwrites the first element, and the subsequent pop returns the value in reverse order.

If comment rb.push_overwrite(2)

    let mut rb = HeapRb::<i32>::new(2);

    assert_eq!(rb.push_overwrite(0), None);
    assert_eq!(rb.push_overwrite(1), None);
    //assert_eq!(rb.push_overwrite(2), Some(0));

    assert_eq!(rb.try_pop(), Some(0));
    assert_eq!(rb.try_pop(), Some(1));
    assert_eq!(rb.try_pop(), None);

The subsequent pop instead behaves as the normal order.

[agerasev]

Thanks for finding this inconsistency! I've fixed the doc comment: a838983

[xmh0511]

Thanks for finding this inconsistency! I've fixed the doc comment: a838983

But why, in this documented example, does the first try_pop return Some(1)?

use ringbuf::{traits::*, HeapRb};

let mut rb = HeapRb::<i32>::new(2);

assert_eq!(rb.push_overwrite(0), None);  // #1
assert_eq!(rb.push_overwrite(1), None); // #2
assert_eq!(rb.push_overwrite(2), Some(0)); // #3

assert_eq!(rb.try_pop(), Some(1)); // #4
assert_eq!(rb.try_pop(), Some(2)); // #5
assert_eq!(rb.try_pop(), None);

IIUC, #3 overwrites the value written #1. However, the first try_pop should return the first one; in this example, it returns the second element. By contrast, in this example:

    let mut rb = HeapRb::<i32>::new(2);

    assert_eq!(rb.push_overwrite(0), None);
    assert_eq!(rb.push_overwrite(1), None);
    //assert_eq!(rb.push_overwrite(2), Some(0));

    assert_eq!(rb.try_pop(), Some(0));
    assert_eq!(rb.try_pop(), Some(1));
    assert_eq!(rb.try_pop(), None);

The first try_pop returns the first element.