http://qs1969.pair.com?node_id=474799

anonymized user 468275 has asked for the wisdom of the Perl Monks concerning the following question:

Dear monks,

I have been having trouble finding (imho) satisfactory documentation for the map function.

For example, this http://www.perlfunc.org/function.php?name=map, just doesn't tell me what I want to know in a way I can unambiguously understand it. For example, the opening line,

Description: Evaluates the BLOCK or EXPR for each element of LIST (locally setting +$_ to each element) and returns the list value composed of the result +s of each such evaluation
with its sort of circular definition of 'evaluation', makes me look ahead at the examples for clues, but the examples seem too obscure.

(1) Is it just me? Do other people find this documentation clear enough?

(2) Can anyone provide a link to better documentation of this function (or suggest an alternative way to document it)?

Update: After about the fifth time reading through it, I finally understood it, although I am still interested in others' opinions.

Thanks in advance!

-Simon

One world, one people

Replies are listed 'Best First'.
Re: Understanding the map function
by dbwiz (Curate) on Jul 14, 2005 at 09:29 UTC
Re: Understanding the map function
by reasonablekeith (Deacon) on Jul 14, 2005 at 09:15 UTC
    IMHO. This sort of documentation is aimed as a reference for programmers who already understand perl, not as a tutorial for beginners. The definition is clear and unambiguous, as long as you know what all the terms mean.

    Keep a copy of learning perl close at hand if this type of documentation scares you.

    ---
    my name's not Keith, and I'm not reasonable.
Re: Understanding the map function
by castaway (Parson) on Jul 14, 2005 at 09:23 UTC
    It makes perfect sense to me, though I would probably rephrase it thusly:

    Evaluates the BLOCK or EXPR for each element of LIST (locally setting $_ to each element) and returns a list of the results .

    That help any?

    C.

      Nitpick.

      ...returns a list value for each element of LIST...

      It took me a while to get my head 'round that. Once you do the docs make more sense.

        That would make it more confusing, to me. It already says 'evaluates something for each element in list', thus 'returns a list of the results' cant mean anything but 'list of evaluated somethings for each element in list' ... or not?

        C.

        That edit makes the definition imprecise. map can return multiple list values for each element of LIST.

        --jwest



        -><- -><- -><- -><- -><-
        All things are Perfect
            To every last Flaw
            And bound in accord
                 With Eris's Law
         - HBT; The Book of Advice, 1:7
        
      Thanks - I prefer your suggestion, which makes a clear overview from the beginning.

      Hmmm... though I wonder if anything makes sense provided you already know everything it is trying to say.

      One world, one people

Re: Understanding the map function
by tlm (Prior) on Jul 14, 2005 at 11:57 UTC

    Here is my tutorial-like attempt to explain map.

    the lowliest monk

      Nice work tlm; the fact that it isn't exactly the my_map subroutine you start off with also serves as an appropriate warning to the reader that something special is going on.

      One world, one people

Re: Understanding the map function
by ysth (Canon) on Jul 14, 2005 at 17:05 UTC
    "evaluation" there means, supposing the BLOCK or EXPR were the body of a sub, see what the sub returns in list-context given $_ aliased to an element of LIST.

    Maybe you are trying to read too much into the word? evaluate 1+1 results in 2; evaluate "a".."e" results in qw/a b c d e/, etc.