[commit: containers] master: A first stab at documenting strictness properties (e8dc088)

[Ian Lynagh]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/containers

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/e8dc0883b2f7fd88034039c6d6dd744345ae1833

>---------------------------------------------------------------

commit e8dc0883b2f7fd88034039c6d6dd744345ae1833
Author: Johan Tibell <johan.tibell at gmail.com>
Date:   Thu Nov 17 21:22:07 2011 -0800

    A first stab at documenting strictness properties

>---------------------------------------------------------------

 Data/Map/Strict.hs |   15 +++++++++++++++
 1 files changed, 15 insertions(+), 0 deletions(-)

diff --git a/Data/Map/Strict.hs b/Data/Map/Strict.hs
index a9868be..d3a1545 100644
--- a/Data/Map/Strict.hs
+++ b/Data/Map/Strict.hs
@@ -56,6 +56,8 @@
 
 module Data.Map.Strict
     (
+    -- * Strictness properties
+    -- $strictness
 
     -- * Map type
 #if !defined(TESTING)
@@ -259,6 +261,19 @@ import Data.Map.Base hiding
     , updateMaxWithKey
     )
 
+-- $strictness
+--
+-- * All functions are strict in both key and value arguments.  Examples:
+--
+-- > insertWith (+) k undefined m  ==  undefined
+-- > delete undefined m  ==  undefined
+--
+-- * Keys and values are evaluated to WHNF before they are stored in
+-- the map.  Examples:
+--
+-- > map (\ v -> undefined)  ==  undefined
+-- > mapKeys (\ k -> undefined)  ==  undefined
+
 {--------------------------------------------------------------------
   Query
 --------------------------------------------------------------------}