Filtering and queries

Use a collection filter to find matching sessions, windows, or panes. Use an exactly-one lookup when your next operation requires a single target.

• Filtering returns a collection; exactly-one lookup checks the result count. A filter returns zero or more matches. An exactly-one operation returns one object or reports a missing or ambiguous match.

• Choose where to filter. Filter a snapshot in your program when you need several queries over the same data. A tmux format filter can reduce the rows returned by a live read. The cost depends on the data and queries you need.

Typed and local filters¶

Typed field operations let the compiler reject incompatible comparisons:

CPane_, CWindow_, and CSession_ expose typed field accessors for stream predicates. A numeric field has no mstartsWith operation. Use mSelections.exactlyOne to reject absent or ambiguous matches.

Examples of typed and local filters:

List<Window> editors = server.windows().stream()
        .filter(Window_.name().startsWith("edit"))
        .toList();

// Selections.exactlyOne() is the `.get()`-shaped call.
Session build = Selections.exactlyOne(
        server.sessions().stream().filter(Session_.name().is("build")).toList());

Result counts¶

Filter with Stream.filter and require one match with mSelections.exactlyOne. Empty and multiple results raise CCardinalityException.NoMatch and CCardinalityException.MultipleMatches, respectively.

Filtering and querying shows exactly-one lookups and their error handling. Do not index the first result until the operation has established that a match exists.