[dox] Cross-reference .merge and .multiwayMerge.

These two functions are related but play two different roles:
std.algorithm.sorting.merge takes a static number of ranges of possibly
disparate types (but compatible elements), and is useful for composing
ranges at compile-time. However, it cannot take a variable number of
ranges at runtime because all ranges must be statically known.

That latter role is played std.algorithm.setops.multiwayMerge, which
takes a range of ranges to merge, and so can merge a variable number of
ranges at runtime.  However, because of that, it cannot merge ranges of
disparate types (of compatible elements), and so is unsuitable for
compile-time range composition, unless a workaround like the range class
interface is used.

The docs for these two functions really should cross-reference each
other so that users can more easily find the correct function for their
needs.
This commit is contained in:
H. S. Teoh 2019-01-31 11:16:04 -08:00 committed by Sebastian Wilzbach
parent 7fe854347e
commit 3cf78da259
2 changed files with 6 additions and 0 deletions

View file

@ -830,6 +830,9 @@ of `ror` and discretionarily swaps and advances elements of it. If
you want `ror` to preserve its contents after the call, you may
want to pass a duplicate to `MultiwayMerge` (and perhaps cache the
duplicate in between calls).
See_Also: $(REF merge, std,algorithm,sorting) for an analogous function that
takes a static number of ranges of possibly disparate types.
*/
struct MultiwayMerge(alias less, RangeOfRanges)
{

View file

@ -1312,6 +1312,9 @@ All of its inputs are assumed to be sorted. This can mean that inputs are
If any of the inputs `rs` is infinite so is the result (`empty` being always
`false`).
See_Also: $(REF multiwayMerge, std,algorithm,setops) for an analogous function
that merges a dynamic number of ranges.
*/
Merge!(less, Rs) merge(alias less = "a < b", Rs...)(Rs rs)
if (Rs.length >= 2 &&