catena v1.2.0
One new operator and a substantial documentation pass. The pass came out of
an ergonomics and cognitive-load audit whose finding was that the library's
most useful facts were written down where godoc discards them — so nothing
about the API changed, but a good deal more of it is now visible from the
place people read.
Added
BottomN(s, n)— the no-selector form ofBottomNBy, completing the
pair withTopN. Without it, wanting the smallest n meant either
BottomNBy(n, catena.Self[T])or, more likely,Sorted(s).Take(n),
which quietly gives up the O(n) memory bound that makes the operator
worth having. Routes through the same bounded heap, with the same
stability and tie rules.
Fixed
- Four generated
Listmirrors documented themselves as evaluating
"eagerly" while returning a lazy value:WithIndexandZipWithNext
return aSeq2,MapErrandFilterErrreturn aTry. They now say
so, and the claim in Concepts that no operator changes evaluation
strategy names them as the exceptions. - The eager-operators page claimed
Listcarries "the wholeSeq
operation set". It carries the whole method set: the constraint-bound
package functions take aSeq, socatena.Sorted(l.AsSeq()).ToList()
is the round-trip, andConcatneedsl2.AsSeq(). Both are now
documented on theListtype and on the page. - The package doc pointed at a "constructor table" that did not exist in
godoc. The normative re-iterability table now lives on theSeqtype,
and the nine constructors that said nothing about re-iterability now
state it — includingCycle, which is re-iterable iff its source's
first pass is.
Documentation
Try's five error rules were cited by number eight times in godoc and
defined nowhere in it: the block was a file-level comment, which godoc
discards. R1–R5 now live on theTrytype, along with the rule that
Tryis deliberately a small surface — carry errors one stage, then
commit to a policy and continue onSeq. Same fix forSeq2's
"deliberately absent" list and thefuncs.goexplanation of why
constraint-bound operations cannot be methods.- The method-versus-package-function split is now stated in the package
doc and as a fourth rule in Getting started. It is the first thing that
bites a newcomer, and the compiler cannot say it:s.Distinct()
produces an error indistinguishable from a typo. The-Bymethods an
IDE does surface (SortedBy,DistinctBy,SumOf,MaxBy,TopNBy)
now name their unsuffixed package-level siblings. - Added the re-iterability guarantee to Concepts: operators build state
inside the returned closure, so a chain is re-iterable exactly when its
root producer is. This turns an open-ended worry into one lookup. - Added a cross-ecosystem name map (LINQ, Kotlin, Rust) to Getting
started, an index page for the operator reference, and mutual
cross-references for the confusable pairs —MaxBy/MaxOf,
Distinct/Dedupe,Collect/ToList,Chain/Concat,
Once/Once1,JoinBy/Join. - The
[S]marker in the operator catalog read as a warning while
certifying the opposite; it now says what it means. README notes that
adopting catena raises a consumer's owngodirective to 1.27, and its
two non-compiling snippets are fixed. - SPEC's naming law gained the eight suffix patterns it did not cover,
its known exceptions (AssociateWith,WithIndex), and the third
reason an operation lands at package level (receiver shape).