Skip to content

catena v1.2.0

Choose a tag to compare

@github-actions github-actions released this 31 Aug 11:08
· 13 commits to main since this release

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 of BottomNBy, completing the
    pair with TopN. 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 List mirrors documented themselves as evaluating
    "eagerly" while returning a lazy value: WithIndex and ZipWithNext
    return a Seq2, MapErr and FilterErr return a Try. 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 List carries "the whole Seq
    operation set". It carries the whole method set: the constraint-bound
    package functions take a Seq, so catena.Sorted(l.AsSeq()).ToList()
    is the round-trip, and Concat needs l2.AsSeq(). Both are now
    documented on the List type 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 the Seq type,
    and the nine constructors that said nothing about re-iterability now
    state it — including Cycle, 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 the Try type, along with the rule that
    Try is deliberately a small surface — carry errors one stage, then
    commit to a policy and continue on Seq. Same fix for Seq2's
    "deliberately absent" list and the funcs.go explanation 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 -By methods 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 own go directive 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).