www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 3923] New: std.algorithm.find is too much hard to understand

reply d-bugmail puremagic.com writes:
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



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: -------
Mar 10 2010
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3923


Bill Baxter <wbaxter gmail.com> changed:

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





 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: -------
Jun 08 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3923


Steven Schveighoffer <schveiguy yahoo.com> changed:

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



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: -------
Jun 08 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3923


Andrei Alexandrescu <andrei metalanguage.com> changed:

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



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: -------
Jun 08 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3923




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: -------
Aug 07 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
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: -------
Jan 09 2011
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=3923


bearophile_hugs eml.cc changed:

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






 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: -------
Jan 19 2012