Fix doc test for Vec::retain(), now passes clippy::eval_order_dependence

[schteve]

Doc test for Vec::retain() works correctly but is flagged by clippy::eval_order_dependence. Fix avoids the issue by using an iterator instead of an index.

[rust-highfive]

r? @m-ou-se

(rust-highfive has picked a reviewer for you, use r? to override)

[m-ou-se]

@bors r+ rollup

[bors]

📌 Commit d9d1d3a90992ad0e503b556fad515cd42f87dfbe has been approved by m-ou-se

[LingMan]

That example is supposed to illustrate:

/// The exact order may be useful for tracking external state, like an index.

Now that you removed the index it doesn't make much sense anymore.

[schteve]

I see what you mean. I'm not 100% sure what that comment is saying exactly, but maybe changing "index" to "iterator" would be enough to make it right?
/// The exact order may be useful for tracking external state, like an iterator

[LingMan]

I'm not 100% sure what that comment is saying exactly

Turns out, neither did I. The comment is saying that the result of the ith call of the closure you give to retain will be used to determine whether the ith element of the vec will be retained. That wouldn't be the case if the elements weren't visited in-order. It also says that you can use this property to fetch data from the correct location in other structures - which obviously need to be in sync with the vec you're operating on (keep in this example).

It is NOT talking - as I had misunderstood initially - about the specific binding i which you remove here, but about the high-level concept of indexing into another structure. That high-level operation is still present with the iterator.

You could leave the comment unchanged as it is technically correct after all. Maybe something like
/// The exact order may be useful for accessing externally tracked state.
would be clearer though.

[schteve]

After thinking about it a bit I think the main point is that in the first example the decision is made purely based on the element itself, while in the second it is made based on the external state (the array). With that in mind, I reworked the comment as follows:

/// It may be useful to decide which elements to keep based on external state.

[LingMan]

Sounds good 👍

[schteve]

Great! Thanks very much for your input.

[LingMan]

Hm, didn't notice at first but you replaced The exact order with It. This example is supposed to showcase the exact order property, so I'd leave that first part of the sentence as it was.

/// The exact order may be useful to decide which elements to keep based on external state.

[schteve]

Can you point me to somewhere I can read more about the exact order property? I've googled it but it just points back to this same comment. It doesn't mean anything special to me.

[LingMan]

It refers to the first part of the retain documentation just a few lines above where it says (emphasis mine)

/// This method operates in place, visiting each element exactly once in the
/// original order, and preserves the order of the retained elements.

So for:

let mut vec = vec![1, 2, 3, 4, 5];
let keep = [false, true, true, false, true];
let mut iter = keep.iter();
let f = |_| { *iter.next().unwrap()};

retain will do:

f(&1);
f(&2);
f(&3);
f(&4);
f(&5);

which results in
assert_eq!(vec, [2, 3, 5]);

If the elements weren't visited in the original order, retain could otherwise do this without violating its contract:

f(&2);
f(&1);
f(&5);
f(&4);
f(&3);

giving you
assert_eq!(vec, [1, 3, 5]);

If it wouldn't visit elements exactly once it could even do

f(&1);
f(&1);
f(&2);
f(&2);
f(&3);
f(&3);
...

which would panic on the unwrap.

[schteve]

Yeah, ok, I guess it sounded a bit strange the way it's written as "exact order". I found the wording confusing originally, but I get the gist of it. I think I can clarify it though.

/// Because the elements are visited exactly once in the original order, external state may be used to decide which elements to keep.

[schteve]

@m-ou-se There were some additional comments after your approval but think it's ready to re-approve now, could you please take a look?

[schteve]

Hi @m-ou-se, are you able to re-approve? Is there some other process for getting this back into the queue?

[m-ou-se]

@bors r+ rollup

[bors]

📌 Commit 0488afd has been approved by m-ou-se