Removed string predicates from std.algorithm.iteration documentation

[JackStouffer]

The two most common things that I hear when introducing D to people are

• "Is writeln actually a property of string!?" (misunderstanding of UFCS)
• "Does D really use strings instead of lambdas?"

Nothing much can be done for the first one, idiosyncrasies are part of learning a new language. But the second one is mostly because the docs use string predicates more than lambdas. String predicates are bad practice compared to lambdas IMO and should be discouraged by not including them in docs. Yes, there are legitimate uses of string predicates, but 99% of the time, you should use lambdas.

[schveiguy]

I don't agree. Strings are perfectly acceptable here, and offer another benefit (besides brevity) that some template with a string parameter is a singleton, while templates based on lambdas are unique.

For instance, the following code creates 2 instances of template filter:

auto foo(R)(R r) if(isInputRange!R)
{
   return filter!(a => a==5)(r);
}

auto bar(R)(R r, int x) if(isInputRange!R)
{
   return sum(r.filter!(a => a==5), x)
}

while using string lambdas only produces one. Saves on code bloat, and other things. Until we can factor those into one instance, I think string lambdas are here to stay.

What can be done, however, is to mix strings and lambdas in the docs so it's obvious both are possible.

However, I'd say in the cheat sheet, go ahead and change everything to lambdas, it should be consistent (right now, it looks like some functions only take strings, while others take lambdas).

[JackStouffer]

IMO exe size is a small price to pay for syntax highlighting, better errors from the compiler, the ability to forget about special cases like the fact that "a++" modifies in place, and the ability to name parameters whatever you want.

Also, my point still stands that changing these makes the docs clearer for new comers. From these examples you can infer you can pass function literals or function pointers logically from the fact that you can pass lambdas. Where as the string examples, you can be forgiven for believing that you can only use strings. I mean, we can't expect every newcomer to read Ali's or Andrei's book for the full picture; a lot of people are just going to be reading the Phobos docs.

[schveiguy]

IMO exe size is a small price to pay for syntax highlighting, better errors from the compiler, the ability to forget about special cases like the fact that "a++" modifies in place, and the ability to name parameters whatever you want.

It's a small price, but it's a price. I'm just saying that we shouldn't remove string lambdas because they offer benefits (for now), and showing that both strings and lambdas work in the examples identifies the capabilities phobos supports. I don't want to remove all string lambdas from the docs or from phobos.

[JackStouffer]

I'm just saying that we shouldn't remove string lambdas because they offer benefits (for now), and showing that both strings and lambdas work in the examples identifies the capabilities phobos supports.

The problem is that it doesn't make much sense to have two lines for every example with a predicate defined, one with a string and one with a lambda.

How about this: because of the problem above, we keep lambdas in the docs, as I think that they are the best option most of the time. But, we modify the docs of these functions so fact that the predicate is passed to std.functional.binaryFun is made clear with a link directly to binaryFun docs so people know what their options are, including strings.

[JackStouffer]

@schveiguy ping.

[schveiguy]

Can you modify one doc and show me what you mean?

[JackStouffer]

@schveiguy I modified the docs for splitter as an example.

[schveiguy]

There are many things that work here, including delegates, functors, functions, templates, etc.

I think it's probably best to identify that strings here are a special case. Everything else is an alias to a "callable" entity. Perhaps: "The predicate can be either a string lambda (see $(XREF functional,binaryFun) for more details) or an alias that can be called with $(D pred(element, s))"

[JackStouffer]

@schveiguy fixed.

[schveiguy]

Looks better. On the second splitter overload, it looks like the predicate must accept an element of r and an element of s, so the blurb about what predicates are accepted may need to be reworded, or maybe we can come up with a more "portable" way of saying it.

[JackStouffer]

@schveiguy Ok. But on the whole is this a good compromise? Can I start applying this to the other functions?

[schveiguy]

It's fine with me, I cannot speak for others who haven't looked at it yet.

[JackStouffer]

Updated the rest of the docs.

[JackStouffer]

ping

[quickfur]

This has been brought up before. Some people support this, some don't. Maybe @andralex should make a judgment call here and settle this issue once and for all, instead of letting this PR bit-rot?

[andralex]

Yah, we need to fix function equality in the future but string lambdas should be slowly and surely phased out. @JackStouffer thx for the work, when modifying comments in the future please take the opportunity to replace $(D ...) with backquotes.

[andralex]

Auto-merge toggled on

[quickfur]

Function equality is, in the general case, undecidable. However, for our purposes, equality for most of the function literals we'll need to compare in normal use cases can probably be sufficiently approximated by some kind of AST structure matching. It won't catch all the cases, but it will certainly catch the cases that string lambdas can catch, and many more besides. (E.g., currently a==b, a == b, a ==b, a== b, are all distinct string lambdas, but the corresponding function literals would be identified as equal by AST comparison.)

[JackStouffer]

Thanks!

[andralex]

@quickfur yah, alpha renaming too. Someone should write a DIP for this...