merge

fun <T> merge(comparator: Comparator<T>, iterables: Iterable<Iterable<T>>): Sequence<T>

Performs a k-way merge of the given iterables, each of which is assumed to already be sorted according to comparator, producing a single Sequence that yields all their elements in the order induced by comparator (like the "merge" step of a merge-sort, generalized to more than two inputs).

This is lazy (elements are pulled from the inputs only as the resulting sequence is consumed) and cheaper than concatenating the iterables and sorting the result, since it exploits the fact that each input is already ordered. It is used, for instance, by the Rete-based clause indexes in the :theory module to merge per-index-bucket clause sequences (each already sorted by insertion order) back into a single globally-ordered sequence:

fun merge(iterable: Iterable<Sequence<SituatedIndexedClause>>): Sequence<SituatedIndexedClause> =
    mergeSequences(iterable) { c1, c2 -> ... }

If any element supplied by iterables is not consistent with comparator's ordering (i.e. the inputs are not actually sorted), the result is unspecified.

fun <T> merge(iterables: Iterable<Iterable<T>>, comparator: (T, T) -> Int): Sequence<T>

Same as merge, with comparator expressed as a plain comparison lambda instead of a Comparator.

fun <T> merge(vararg iterables: Iterable<T>, comparator: (T, T) -> Int): Sequence<T>

fun <T> merge(comparator: Comparator<T>, vararg iterables: Iterable<T>): Sequence<T>

Same as merge, taking the iterables to merge as varargs instead of an Iterable.

fun <T> merge(iterables: Sequence<Iterable<T>>, comparator: (T, T) -> Int): Sequence<T>

fun <T> merge(comparator: Comparator<T>, iterables: Sequence<Iterable<T>>): Sequence<T>

Same as merge, taking the iterables to merge as a Sequence of Iterables.