Updated List.filterMap documentation with more realistic examples

[charukiewicz]

I made a change to the filterMap documentation in the List module to provide more realistic examples of its use.

The old text:

Apply a function that may succeed to all values in the list, but only keep the successes.

onlyTeens =
 filterMap isTeen [3, 15, 12, 18, 24] == [15, 18]

isTeen : Int -> Maybe Int
isTeen n =
 if 13 <= n && n <= 19 then
   Just n

 else
   Nothing

To someone who may not have a good understanding of what Maybe is used for, I think this raises the question: "Why does my isTeen function even return a Maybe Int to begin with? Why not return Bool and use filter?" In my opinion this is a very contrived example.

As an alternative, my suggested example text is an application of the head and identity functions, where one can build a good intuition of why Maybe values are produced. My suggested text:

Apply a function that may succeed to all values in the list, but only keep
the successes.

    filterMap head [[1,2,3],[],[4,5,6],[],[]] == [1,4]

filterMap can be combined with identity to clean a list of Maybe values:

    filterMap identity [Just 1, Nothing, Nothing, Just 2, Just 3] == [1,2,3]

[process-bot]

Thanks for the pull request! Make sure it satisfies this checklist. My human colleagues will appreciate it!

Here is what to expect next, and if anyone wants to comment, keep these things in mind.