www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Example for Documentation?

reply "Chris" <wendlec tcd.ie> writes:
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

I think it's quite a common task and people will duckduckgo or 
google for it.


[1] 
http://forum.dlang.org/thread/jhcmegyrasivotqfmhbr forum.dlang.org#post-flvdtewuyehvdetoxjrw:40forum.dlang.org
Apr 21 2015
parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
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 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. -Steve
Apr 21 2015
next sibling parent reply "Marc =?UTF-8?B?U2Now7x0eiI=?= <schuetzm gmx.net> writes:
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. Compare: pairs.multiSort!((a, b) => a.value > b.value, (a, b) => a.key < b.key); pairs.multiSort!(q{a.value > b.value}, q{a.key < b.key}); pairs.multiSort!("a.value > b.value", "a.key < b.key");
 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.
Apr 21 2015
parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 4/21/15 11:25 AM, "Marc =?UTF-8?B?U2Now7x0eiI=?= <schuetzm 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
Apr 21 2015
next sibling parent reply "Chris" <wendlec tcd.ie> writes:
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 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.
Apr 21 2015
parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 4/21/15 2:06 PM, Chris wrote:

 multiSort should at least be added to the cheat sheet in
 std.algorithm.sorting.
This I can agree with. Can you add a pull request for it? -Steve
Apr 21 2015
next sibling parent reply "Chris" <wendlec tcd.ie> writes:
On Tuesday, 21 April 2015 at 18:10:25 UTC, Steven Schveighoffer 
wrote:
 On 4/21/15 2:06 PM, Chris wrote:

 multiSort should at least be added to the cheat sheet in
 std.algorithm.sorting.
This I can agree with. Can you add a pull request for it? -Steve
Yeah, but I have to ask a stupid question. How do I add a PR? I've never done it before.
Apr 21 2015
parent reply Justin Whear <justin economicmodeling.com> writes:
On Tue, 21 Apr 2015 18:34:35 +0000, Chris wrote:
 Yeah, but I have to ask a stupid question. How do I add a PR? I've never
 done it before.
This wiki page will walk you through it: http://wiki.dlang.org/Pull_Requests
Apr 21 2015
next sibling parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 4/21/15 2:53 PM, Justin Whear wrote:
 On Tue, 21 Apr 2015 18:34:35 +0000, Chris wrote:
 Yeah, but I have to ask a stupid question. How do I add a PR? I've never
 done it before.
This wiki page will walk you through it: http://wiki.dlang.org/Pull_Requests
Just FYI, the thing you want to fork is phobos. And I would, at this point, just avoid trying to build the whole thing. This isn't a very complex change. But you can try if you want. Building the docs is a pain, and trying to get it to build with what you checked out instead of it trying to get it from github is not exactly straightforward. -Steve
Apr 21 2015
prev sibling parent "Chris" <wendlec tcd.ie> writes:
On Tuesday, 21 April 2015 at 18:53:08 UTC, Justin Whear wrote:
 On Tue, 21 Apr 2015 18:34:35 +0000, Chris wrote:
 Yeah, but I have to ask a stupid question. How do I add a PR? 
 I've never
 done it before.
This wiki page will walk you through it: http://wiki.dlang.org/Pull_Requests
Cool. Thanks!
Apr 21 2015
prev sibling parent "Chris" <wendlec tcd.ie> writes:
On Tuesday, 21 April 2015 at 18:10:25 UTC, Steven Schveighoffer 
wrote:
 On 4/21/15 2:06 PM, Chris wrote:

 multiSort should at least be added to the cheat sheet in
 std.algorithm.sorting.
This I can agree with. Can you add a pull request for it? -Steve
I've added a pull request for it. The first I've ever committed, and a very simple one. I hope everything is ok. It's PR #3236.
Apr 27 2015
prev sibling next sibling parent reply "Meta" <jared771 gmail.com> writes:
On Tuesday, 21 April 2015 at 17:30:08 UTC, Steven Schveighoffer 
wrote:
 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.
Unfortunately, it doesn't work at all for lambdas. RedBlackTree!(int, (a, b) => a < b) tree1; RedBlackTree!(int, (a, b) => a < b) tree2; //Fails assert(is(typeof(tree1) == typeof(tree2)));
Apr 21 2015
parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 4/21/15 3:00 PM, Meta wrote:
 On Tuesday, 21 April 2015 at 17:30:08 UTC, Steven Schveighoffer wrote:
 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.
Unfortunately, it doesn't work at all for lambdas. RedBlackTree!(int, (a, b) => a < b) tree1; RedBlackTree!(int, (a, b) => a < b) tree2; //Fails assert(is(typeof(tree1) == typeof(tree2)));
What? I thought this was the entire point of these? Hm... let me dig it up. https://issues.dlang.org/show_bug.cgi?id=10819 http://forum.dlang.org/post/jnlqesrwxfekdsxjerlp forum.dlang.org Looks like that's not solved :( I was sure we introduced this to fix this string quirkiness problem, but I am wrong. I can't find the discussion I remember about this triggering the new syntax. Is there any possibility to move towards a solution where two identical context-free lambdas are equivalent when generating a template? There were also some pretty good ideas in that thread I referenced that never got fleshed out. -Steve
Apr 21 2015
prev sibling parent "John Colvin" <john.loughran.colvin gmail.com> writes:
On Tuesday, 21 April 2015 at 17:30:08 UTC, Steven Schveighoffer 
wrote:
 for example, RedBlackTree!(int, "a < b") is not compatible with 
 RedBlackTree!(int, "a<b"), even though they are identical.
I'm pretty sure this can and should be fixed. Removing whitespace before creating the function would be start.
Apr 21 2015
prev sibling next sibling parent "bachmeier" <no spam.com> writes:
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 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. -Steve
What about putting it on the wiki and then providing a link with a label like "View other examples on the wiki". That would (a) be available now, and (b) let users know it's there, as few would know to look on the wiki. As I recall, the plan with Discus is to have something like PHP's documentation, and that's not a great solution.
Apr 21 2015
prev sibling parent "Chris" <wendlec tcd.ie> writes:
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 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. -Steve
Not for every use case, but multiSort is the perfect match for sorting AAs, isn't it? I suggested to add it, because it is a) useful and b) one of _the_ use cases of multiSort. The current example in the documentation is ok, but adding how to sort AA would be useful. Also, multiSort is not even mentioned in the cheat sheet section. Given that it does more or less what spread sheets can do, it might be of interest to people who work a lot with stats and numbers and that kinda stuff.
Apr 21 2015