Iterator::skip_while Tests Only One Prefix

I once used skip_while as if it meant “skip every item while this condition is true whenever it appears.” A later matching item was kept. The adaptor had already crossed its one prefix boundary.

The failing fixture iterates [1, 2, 1] with the predicate value < 2. It yields [2, 1], and the predicate runs only twice, not three times.

The method removes one matching prefix

Iterator::skip_while asks the predicate about elements from the start of the iterator. It discards values while the answer is true. The first false answer ends the skipping phase permanently.

That first false item is yielded. Every later item passes through without another predicate call, even if it would have returned true.

For the fixture:

1 -> true  -> skipped
2 -> false -> yielded, boundary found
1 -> not tested -> yielded

This behavior models headers, leading whitespace, warm-up samples, and sorted prefixes naturally.

filter asks a global question

If I want to remove every value below two, I use filter. It applies its predicate to each visited element and yields only matches.

The repaired fixture compares both operations. skip_while yields [2, 1]; filter(|x| *x >= 2) yields [2].

The names look similar because both accept predicates, but their state machines differ. filter has no permanent “done filtering” state. skip_while does.

Predicate side effects expose the state

Counting calls makes the contract easy to see. It also shows why predicates should not hide essential work. With skip_while, that work stops after the boundary. With any lazy iterator, it also occurs only as the consumer requests items.

I keep predicates pure when practical. If metrics are useful, I treat call counts as implementation observations only where the public API documents them. Here the transition after first false is part of the behavior.

A predicate that mutates external state may leave partial work if the consumer drops the iterator early.

The first yielded item was already inspected

The boundary item is not lost. skip_while must consume it from the underlying iterator to discover the false result, but the adaptor stores or directly returns it as its first output.

This differs from take_while, whose first rejected underlying item is consumed and not yielded by that adaptor. Similar names do not imply symmetrical remainder behavior.

When exact ownership of a boundary record matters, I write a small fixture and inspect the underlying iterator through by_ref where possible.

Infinite and streaming inputs make the distinction important

On an infinite iterator that always satisfies the predicate, asking for the first output never completes. The adaptor keeps searching for a boundary that does not exist.

On a stream of sorted timestamps, skip_while(|t| t < cutoff) is efficient because once the cutoff is reached, all later values are expected to remain relevant. On unsorted data, later old timestamps still pass through. The iterator does not know or verify the sort invariant.

I document the monotonicity assumption next to the call when it is what makes prefix skipping correct.

Borrowing adds one small syntax surprise

Iterator adaptors often pass references to predicates when the iterator itself yields references, producing a double-reference shape. I let pattern matching or explicit dereferencing state which value is compared rather than changing the algorithm because of an inference error.

That type detail is separate from the prefix state. Once compiled, the first false answer still disables later calls.

My boundary test uses true-false-true

A monotonically changing test such as [1, 2, 3] does not reveal whether the predicate is called again, because later answers would remain false anyway. I use a true-false-true sequence and a call counter.

I also test an empty iterator, a first false item, and an all-true finite iterator. These cases define the complete prefix behavior with little code.

The core principle is that while describes a phase, not a global selection. skip_while consumes one initial region satisfying the condition. After the first false result, its job is finished and the remaining iterator passes through unchanged.

A small test that protects the boundary

I use a three-part input when this distinction matters: one item that passes the predicate, one that fails it, and a later item that passes again. The final item is the important probe. If it survives without another predicate call, the test proves prefix behavior rather than merely checking a convenient output. This shape is more useful than an all-true or all-false example because those inputs make skip_while and several mistaken implementations look identical.