[Sequence] Add "terminal" methods: querying

[nikophil]

Related to #23, follows #29.

Second of four PRs bringing the terminal vocabulary to Sequence — element access landed in #29, querying here, then aggregation and forEach/toMap. This adds isEmpty/isNotEmpty, contains/containsAll, all/any/none and count()/countWhere.

Five bodies move into the shared trait

#29 settled that a body identical on both sides lives in IterableTerminalsLogic rather than being copied. all, any, none, countWhere and isNotEmpty qualify, so they leave CollectionLogic for the trait — hence 50 lines deleted there against 61 added in the trait. Collection behaviour is unchanged, and the existing suite is what proves it.

What stays per side, and why

isEmpty, contains and count are the same structural split as first/last: the eager side answers them from its store in O(1), a sequence has to pull. isEmpty() stops at the first element, contains() at the first match, count() drains — each pinned by a test that counts exactly what the source handed out.

containsAll — the one that cannot be shared

The eager body is already generic:

foreach ($elements as $x) {
    if (!$this->contains($x)) {
        return false;
    }
}

It calls $this->contains() once per value, and every store specialises that call — which is exactly where a hash set gets its O(m):

store	contains()	⇒ containsAll()
HashElementStore (Set)	array_key_exists(hash) — O(1)	O(m)
ArrayIndexStore (List)	in_array(…, true) — O(n)	O(n·m)
HashKeyValueStore (Map values)	array_any — O(n)	O(n·m)

A sequence has no store to specialise. One contains() costs a whole pass, and a second one on a single-pass source does not cost anything — it throws NonReplayableSourceException. Sharing that body would not merely be slow on the lazy side, it would be wrong.

So the sequence walks once instead, carrying the values it still looks for and dropping them as it meets them, stopping as soon as none is left. Every equal entry drops at once, so containsAll([1, 1]) asks whether 1 is there rather than whether it is there twice — the answer the eager side gives, pinned by a parity assertion.

The comparison stays ===, consistent with Sequence::contains(). Hashing the wanted values through KeyHasher would bring it to O(n + m), but hashSetKey() is deliberately not === — a Hashable collides two distinct instances by design, floats round at %.12F — so contains() and containsAll() would disagree with each other on the same sequence. Every Collection type is self-consistent on that point and Sequence should be too.

Three methods the plan had excluded from v1

isEmpty/isNotEmpty/containsAll sat on the v1 exclusion list among the buffering ops. They do not belong there: all three are single-pass and short-circuiting. And without isEmpty(), asking a sequence whether it holds anything comes down to firstOrNull() !== null, which is wrong the moment it can hold null — there is a test for that.

count() does not make Sequence countable

Native count($sequence) stays a TypeError by design, and SequenceFactoryTest already asserts the type is not Countable. The interface docblock used to say counting would silently consume a pass; it now says $sequence->count() is the explicit O(n) terminal that drains one.

#[NoDiscard]

None of these carry it — they hand back a bool or an int rather than a new container, which is where #29 settled the rule.

Test file moves (separate commit)

tests/Type/ holds one directory per family — Collection/, List/, Map/, Set/ — each split by aspect. The Sequence type tests were the only ones left flat at the root, so they move under tests/Type/Sequence/. SequenceTerminalTypeTest becomes AccessTypeTest: it only ever covered element access, and "terminal" stops naming anything specific once querying — just as terminal — lands beside it. The behaviour test takes the same correction.

Verification

composer qa green — PHPStan level 9 with no new ignores, phpcs clean, 6357 tests (+19).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[delacry]

btw contains() is fine as is, only Set uses hashing, other collections like List or Map->values do === comparison

[delacry]

lgtm, and good call pulling isEmpty, isNotEmpty and containsAll from the v1 exclusion list, when I read issue and checklist last time I was about to ask about why was it excluded