[Haskell-cafe] Documenting strictness properties for Data.Map.Strict

[Johan Tibell]

On Fri, Nov 18, 2011 at 5:02 AM, Twan van Laarhoven <twanvl at gmail.com> wrote:
>> * key and value function arguments passed to functions are
>>  evaluated to WHNF before the function body is evaluated, and
>
> "function arguments passed to functions" sounds a bit redundant. Either say
> "arguments passed to functions" or "function arguments". Also "before the
> function body is evaluated" says something about evaluation order, does that
> really matter for strictness?

It is a bit redundant. I will remove it.

>>  * keys and values returned by high-order function arguments are
>>    evaluated to WHNF before they are inserted into the map.
>
> Keys and values not returned by higher order functions, but passed in
> directly are also evaluated to WHNF (per the first rule), so that
> qualification is unnecessary. Just say:
>
>  * keys and values are evaluated to WHNF before they are
>    inserted into the map.

I don't think we have any higher-order functions that don't store
evaluated keys/values in the map so this should be equivalent. Without
the part about higher-order functions it's not quite clear why this
second property is needed and that's why I included it to begin with.
Perhaps I should instead clarify that particular part with an example.

> I also think 'stored' is better here than 'inserted', because the latter
> might give the impression that it only applies to the insert function, and
> not to things like map.

'stored' is a bit more clear, I agree.

>>      insertWith (+) k undefined m  ==  undefined
>
>>       etc.
>
> As Roman suggested, use = here instead of ==.

I was trying to be consistent with e.g. Control.Functor etc, which use
== and two surrounding spaces. I think it's good, as it avoids
confusion with function declarations.

> To really illustrate the first rule, insertWith (+) is not enough, you would
> really need a function that doesn't use the value, so
>
>    insertWith (\new old -> old) k undefined m = undefined
>
> But that is just nitpicking.

My example is enough, but I forgot to include the side condition that
k is in the map. You're example is a bit better in that it doesn't
require that side condition.

-- Johan