feat: Add the Skip higher-order stream

[Hywan]

This patch adds the Skip higher-order stream. Similarly to Head or Tail, it computes a limited view of the underlying ObservableVector's items. The view starts after count number of values are skipped, until the end. It must not be confused with Tail where Tail keeps the last values, while Skip skips the first values.

use eyeball_im::{ObservableVector, VectorDiff};
use eyeball_im_util::vector::VectorObserverExt;
use imbl::vector;
use stream_assert::{assert_closed, assert_next_eq, assert_pending};

// Our vector.
let mut ob = ObservableVector::<char>::new();
let (values, mut sub) = ob.subscribe().skip(3);

assert!(values.is_empty());
assert_pending!(sub);

// Append multiple values.
ob.append(vector!['a', 'b', 'c', 'd', 'e']);
// We get a `VectorDiff::Append` with the latest 2 values because the
// first 3 values have been skipped!
assert_next_eq!(sub, VectorDiff::Append { values: vector!['d', 'e'] });

// Let's recap what we have. `ob` is our `ObservableVector`,
// `sub` is the “limited view” of `ob`:
// | `ob`  | a b c d e |
// | `sub` | _ _ _ d e |
// “_” means the item has been skipped.

// Append multiple values.
ob.append(vector!['f', 'g']);
// We get a single `VectorDiff`.
assert_next_eq!(sub, VectorDiff::Append { values: vector!['f', 'g'] });

// Let's recap what we have:
// | `ob`  | a b c d e f g |
// | `sub` | _ _ _ d e f g |
//                     ^^^
//                     |
//                     `VectorDiff::Append { .. }`

// Insert a single value.
ob.insert(1, 'h');
// We get a single `VectorDiff::PushFront`. Indeed, `h` is inserted at
// index 1, so every value after that is shifted to the right, thus `c`
// “enters the view” via a `PushFront`.
assert_next_eq!(sub, VectorDiff::PushFront { value: 'c' });

// Let's recap what we have:
// | `ob`  | a h b c d e f g |
// | `sub` | _ _ _ c d e f g |
//                 ^
//                 |
//                 `VectorDiff::PushFront { .. }`

assert_pending!(sub);
drop(ob);
assert_closed!(sub);

---

• Built on top of feat: Add the Tail higher-order stream #69.

[jplatte]

I am not finding this word in a dictionary, what's going on here? ^^

[Hywan]

Hehe, it's skip but I don't to use the same name as skip to highlight it does a difference thing. If you don't like that, I can fallback to skip, not a big deal after all. If you check the Skeep trait and its implementation, you'll notice that the skeep method on the Vector implementation tries to be smart than the Vector::skip method to avoid useless clones or splits.

[Hywan]

(rebased on top of main)

[jplatte]

Why not submit a PR to imbl to make the upstream skip more efficient like this? It even has a fixme in there about making it more efficient.

[Hywan]

Let's do it then 🙂

[Hywan]

jneem/imbl#104 PR is here

[Hywan]

Oh you merged it anyway? I'll open a follow-up PR as soon as imbl merges my patch.

[jplatte]

Yeah, I saw that it's a private API anyways. I figured it might take a while until imbl releases a new version with that improvement.