Example for Documentation?

[Chris via Digitalmars-d]

On Tuesday, 21 April 2015 at 17:30:08 UTC, Steven Schveighoffer 
wrote:
> On 4/21/15 11:25 AM, "Marc =?UTF-8?B?U2Now7x0eiI=?= 
> <schuetzm at gmx.net>" wrote:
>> On Tuesday, 21 April 2015 at 14:25:29 UTC, Steven 
>> Schveighoffer wrote:
>>> On 4/21/15 10:07 AM, Chris wrote:
>>>> Here's bearophile's version of sorting an AA by value [1]
>>>>
>>>> void main() {
>>>>    import std.stdio: writeln;
>>>>    import std.algorithm.sorting: multiSort;
>>>>    import std.array: array;
>>>>
>>>>    const size_t[string] wCount = [
>>>>        "hamster": 5,
>>>>        "zorro": 80,
>>>>        "troll": 90,
>>>>        "algorithm": 80,
>>>>        "beer": 80
>>>>    ];
>>>>
>>>>    auto pairs = wCount.byKeyValue.array;
>>>>    assert(wCount.length == pairs.length);
>>>>    pairs.multiSort!(q{a.value > b.value}, q{a.key < b.key});
>>>>    assert(pairs[2].key == "beer");
>>>>    foreach (const ref it; pairs)
>>>>        writeln(it.key, ": ", it.value);
>>>> }
>>>>
>>>> Should we add it to the documentation of
>>>>
>>>> 1. 
>>>> http://dlang.org/phobos/std_algorithm_sorting.html#.multiSort
>>>> 2. http://dlang.org/hash-map.html
>>>
>>> We should not be promoting string-based lambdas:
>>>
>>> pairs.multiSort!((a, b) => a.value > b.value, (a, b) => a.key 
>>> < b.key);
>>>
>>
>> I find the strings to be more readable, simply because they 
>> are shorter.
>> I would probably even prefer normal "" quotes.
>
> quoted lambdas are indeed shorter, but the issue with them is 
> that "a<b" instantiates a different template than "a < b", 
> whereas the lambda does not.
>
> In fact, that is why we added shorthand lambdas to the 
> language. Note that in this case, it's just wasted code space 
> and not a real issue. but for example, RedBlackTree!(int, "a < 
> b") is not compatible with RedBlackTree!(int, "a<b"), even 
> though they are identical.
>
> I'm not saying we shouldn't allow string lambdas, just that we 
> shouldn't encourage them as "proper" D code.
>
>>> I think this would be a perfect addition for the disqus forum 
>>> of that
>>> function (once ddox gets to be the default). I don't want to 
>>> get into
>>> adding sample usages for every use case on every function to 
>>> the
>>> documentation.
>>
>> Not for every possible use case, but I'd prefer examples 
>> demonstrating
>> an actual, practical application to ones that were just made 
>> up for the
>> sake of documentation.
>
> This use case seems niche to me. I haven't ever had the need to 
> "sort" an AA, and if I did, I would use a RedBlackTree.
>
> Not discounting it, or saying it's not valid or useful, just 
> that it's not such a perfect example that it needs to unseat 
> the current example (sorting points by x and y).
>
> It definitely does not belong in the AA documentation.
>
> -Steve

It's not meant to unseat the existing example, but it could be 
added as an additional use case. I agree, I don't need AA.value 
sort everyday, but when you need it, it should be fast and easy 
to implement. I needed it, because I was grinding data in various 
ways (like you would in a spread sheet). It came in handy there.

multiSort should at least be added to the cheat sheet in 
std.algorithm.sorting.