OrderedMerge is named too similar to SortedMerge

[fsateler]

The names provide no indication as to how they differ, and the key difference is not prominent in the documentation (AFAICT, OrderedMerge is equivalent to SortedMerge().Distinct(), or am I missing something?).

I'm not sure which one should be renamed, though. Maybe these should be overloads of the same method, with a parameter indicating whether to discard repeated values or not.

[atifaziz]

I agree, the naming is certainly confusing but they do different things. OrderedMerge is like an efficient full outer join so the sequences are joined at keys. The more specific overloads let you decide on the result when either sequence yields an element or both:

Enumerable.Repeat(5, 10)
          .OrderedMerge(Enumerable.Range(5, 10), 
                        n => n,                 // identity key
                        a => new { a, b = -1 }, // left only 
                        b => new { a = -1, b }, // right only
                        (a, b) => new { a, b }) // both

The result will be:

a	b
1	-1
2	-1
3	-1
4	-1
5	5
6	6
7	7
8	8
9	9
10	10
-1	11
-1	12
-1	13
-1	14

The ordered in OrderedMerge is there to say clearly that it expects ordered sequences otherwise the result is undefined.

In contrast, SortedMerge will line up in order:

string.Join(", ", Enumerable.Range(1, 10)
                            .SortedMerge(OrderByDirection.Ascending,
                                         Enumerable.Range(5, 10)))
// output: 1, 2, 3, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 12, 13, 14

OrderedMerge is already there in 1.x so it should stay. However, if you can come up with a way, way better name then we can talk about marking it obsolete in 2.0 while also exposing it under its new name. The older name could then be retired in 3.0. That's assuming if SortedMerge is the perfect name. Another option is to drop SortedMerge for now and introduce it back later when the naming can be clarified. What I want to avoid is a 2.0 release just hanging on this issue.

[fsateler]

@atifaziz Interesing. v2 alpha does not have it.

Perhaps SortedInterleave is a better name for SortedMerge? Also, OrderedMerge could be OrderedJoin.

If you find deprecation and removal in an eventual 3.0 acceptable, then there is no need to hold the 2.0 release on this. The Obsolete attribute can always be added later on.

[atifaziz]

@fsateler v2 alpha doesn't have it because it was added to v1 and released in one of the minor version updates after v2 work had started. It should make it in the next package now that it's been merged in from v1.

Perhaps SortedInterleave is a better name for SortedMerge? Also, OrderedMerge could be OrderedJoin.

Who ever said naming is hard? 😏 And of course, SortMergeJoin would just make a terrible name to mean everything and yet nothing. 😆 If we can borrow a name from a similar operation in another library (on another platform/runtime/language) then it can go a long way to help not tear out hairs on this. Not only many others must have gone through the same motions but chances are good that users will recognize an operation easily. For example, Zip can be found pretty much everywhere you look from LINQ, Python, F#, Haskell and countless others.

If you find deprecation and removal in an eventual 3.0 acceptable, then there is no need to hold the 2.0 release on this. The Obsolete attribute can always be added later on.

True.