http://d.puremagic.com/issues/show_bug.cgi?id=3923

           Summary: std.algorithm.find is too much hard to understand
           Product: D
           Version: 2.041
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Phobos
        AssignedTo: nobody@puremagic.com
        ReportedBy: bearophile_hugs@eml.cc


--- Comment #0 from bearophile_hugs@eml.cc 2010-03-10 06:23:10 PST ---
The find() of std.algorithm is too much hard to understand. I can't understand how to use it and what it returns.

It's even hard to understand this in the docs page:

FindResult!(Range,Ranges) find(alias pred = "a == b", Range, Ranges...)(Range
haystack, Ranges needles);
struct BoyerMooreFinder(alias pred,Range);
BoyerMooreFinder!(binaryFun!(pred),Range) boyerMooreFinder(alias pred = "a ==
b", Range)(Range needle);

Such functions must be simple enough for normal people to use. If you need more than 10 minutes to understand how to use something as simple as a "find", then the library API is badly designed. It's not a limit of my brain, it's a problem in the library design.

If I need to know that the substring "foo" is present in "abfoobar" in Python I write:

"foo" in "abfoobar"

This covers 85%+ of the cases in normal programs.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3923


Bill Baxter <wbaxter@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |wbaxter@gmail.com


--- Comment #1 from Bill Baxter <wbaxter@gmail.com> 2010-06-08 06:56:07 PDT ---
(In reply to comment #0)
> If you need more
> than 10 minutes to understand how to use something as simple as a "find", then
> the library API is badly designed. It's not a limit of my brain, it's a problem
> in the library design.

Or else it's a problem in its documentation.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3923


Steven Schveighoffer <schveiguy@yahoo.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |schveiguy@yahoo.com


--- Comment #2 from Steven Schveighoffer <schveiguy@yahoo.com> 2010-06-08 07:44:28 PDT ---
This is typical of STL documentation too.  The issue is that because of the power of templates, you can pack an amazing amount of usages into one function, and IFTI makes it resolve to the simplest form.

What I would advise is to read the examples, not the signature.  Most of the time, you do not need the full power of find's features.  In particular, calling the second argument needles, and calling the type Ranges makes it difficult to understand you can simply just pass a single value to get what you want.  But the examples are easy to understand.

Maybe a message at the top of the std.algorithm page to recommend reading the examples if you don't understand the signatures.

One thing that Tango does to help in this regard is to have a version(ddoc) for complex signatures so one can fine-tune how the signature looks in ddoc.

Maybe an enhancement for ddoc would be to be able to specify a simple signature form, then you could click on a link to have it expand to the full signature.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3923


Andrei Alexandrescu <andrei@metalanguage.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |andrei@metalanguage.com


--- Comment #3 from Andrei Alexandrescu <andrei@metalanguage.com> 2010-06-08 07:57:32 PDT ---
Good ideas. I think we can break std.find into several constrained templates, each with its own documentation - something like std.conv.to. Also, we could and should use auto return types for the win.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3923



--- Comment #4 from bearophile_hugs@eml.cc 2010-08-07 06:30:59 PDT ---
It's not just a problem of documentation. std.algorithm is modelled on the C++ STL algorithms, they are efficient and they are useful in many cases. But not all D programmers are familiar with STL and sometimes C++ API design isn't the best conceivable. The good Python-inspired API of std.string shows that a good "ergonomic" API design allows you a handy string processing. So I suggest to add to the STL-style API design of std.algorithm a more human style, not inspired by C++ and inspired by more user-oriented languages.

This proposal of mine looks not precise, so I can express the ideas in a more defined way.

As with most software it's better to first ask yourself what your software will mostly be used for, and then to write it. Otherwise you are wasting your time and the user time.

From my experience here are the most common usages for find-like functions (every one of the following seven operations takes an optional transform function like schwartzSort), (some of them are already present in std.algorithm with a different name):

1) boolean predicate, is the item/iterable x inside the iterable foo?
(built-"in" operator for arrays, because this is a really common operation. Or
if not possible a "isIn" function).
2) int function, tell me how many items/arrays x are inside the iterable foo
("count" function).
3) int function, tell me the index of the first item/iterable x in the iterable
foo ("index" function).
4 extra) find lazily all the indexes of an item/iterable x inside the iterable
foo ("indexes" struct or class).

5) find the first max/min item in a iterable ("max", "min" functions, they have
overloads for 2 and 3 items too).
6) find the index of the max/min item in a iterable ("maxPos", "minPos"
functions).
7) find lazily all the max/min items in a iterable ("maxs", "mins" structs or
classes).


Here I call 'iterable' a Range (like a string, array, AA, etc) or a struct/class that defines just opApply.

In the first 4 micropatterns it's positive to have a specialization for strings, to increase performance with some string-specific tricks. Such specializations are fitter for the std.string module.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3923


Andrei Alexandrescu <andrei@metalanguage.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |ASSIGNED
         AssignedTo|nobody@puremagic.com        |andrei@metalanguage.com


-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=3923


bearophile_hugs@eml.cc changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|ASSIGNED                    |RESOLVED
         Resolution|                            |FIXED


--- Comment #5 from bearophile_hugs@eml.cc 2012-01-19 04:58:33 PST ---
(In reply to comment #4)

> 7) find lazily all the max/min items in a iterable ("maxs", "mins" structs or
> classes).

This is not present yet, but most other suggestions are now present in Phobos. So I think it's time to close this bug report. More specific problems are better left to other more specific bug reports.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------