[commit: packages/containers] ghc-head: Improve the documentation of indexing API of Map and Set. (13092f1)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/containers

On branch  : ghc-head
Link       : http://git.haskell.org/?p=packages/containers.git;a=commit;h=13092f14876aa1a39549ba2b5354e16bcb3f6f6f

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

commit 13092f14876aa1a39549ba2b5354e16bcb3f6f6f
Author: Milan Straka <fox at ucw.cz>
Date:   Sun Nov 11 15:43:01 2012 +0100

    Improve the documentation of indexing API of Map and Set.
    
    * Explain the definition of index in every method.
    * Point out the fact when 'error' can be called.


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

13092f14876aa1a39549ba2b5354e16bcb3f6f6f
 Data/Map/Base.hs |   27 ++++++++++++++++-----------
 Data/Set/Base.hs |   21 +++++++++++++--------
 2 files changed, 29 insertions(+), 19 deletions(-)

diff --git a/Data/Map/Base.hs b/Data/Map/Base.hs
index 8fe866c..f393cc7 100644
--- a/Data/Map/Base.hs
+++ b/Data/Map/Base.hs
@@ -912,9 +912,10 @@ alter = go
 {--------------------------------------------------------------------
   Indexing
 --------------------------------------------------------------------}
--- | /O(log n)/. Return the /index/ of a key. The index is a number from
--- /0/ up to, but not including, the 'size' of the map. Calls 'error' when
--- the key is not a 'member' of the map.
+-- | /O(log n)/. Return the /index/ of a key, which is its zero-based index in
+-- the sequence sorted by keys. The index is a number from /0/ up to, but not
+-- including, the 'size' of the map. Calls 'error' when the key is not
+-- a 'member' of the map.
 --
 -- > findIndex 2 (fromList [(5,"a"), (3,"b")])    Error: element is not in the map
 -- > findIndex 3 (fromList [(5,"a"), (3,"b")]) == 0
@@ -937,8 +938,9 @@ findIndex = go 0
 {-# INLINABLE findIndex #-}
 #endif
 
--- | /O(log n)/. Lookup the /index/ of a key. The index is a number from
--- /0/ up to, but not including, the 'size' of the map.
+-- | /O(log n)/. Lookup the /index/ of a key, which is its zero-based index in
+-- the sequence sorted by keys. The index is a number from /0/ up to, but not
+-- including, the 'size' of the map.
 --
 -- > isJust (lookupIndex 2 (fromList [(5,"a"), (3,"b")]))   == False
 -- > fromJust (lookupIndex 3 (fromList [(5,"a"), (3,"b")])) == 0
@@ -961,8 +963,9 @@ lookupIndex = go 0
 {-# INLINABLE lookupIndex #-}
 #endif
 
--- | /O(log n)/. Retrieve an element by /index/. Calls 'error' when an
--- invalid index is used.
+-- | /O(log n)/. Retrieve an element by its /index/, i.e. by its zero-based
+-- index in the sequence sorted by keys. If the /index/ is out of range (less
+-- than zero, greater or equal to 'size' of the map), 'error' is called.
 --
 -- > elemAt 0 (fromList [(5,"a"), (3,"b")]) == (3,"b")
 -- > elemAt 1 (fromList [(5,"a"), (3,"b")]) == (5, "a")
@@ -979,8 +982,9 @@ elemAt i (Bin _ kx x l r)
   where
     sizeL = size l
 
--- | /O(log n)/. Update the element at /index/. Calls 'error' when an
--- invalid index is used.
+-- | /O(log n)/. Update the element at /index/, i.e. by its zero-based index in
+-- the sequence sorted by keys. If the /index/ is out of range (less than zero,
+-- greater or equal to 'size' of the map), 'error' is called.
 --
 -- > updateAt (\ _ _ -> Just "x") 0    (fromList [(5,"a"), (3,"b")]) == fromList [(3, "x"), (5, "a")]
 -- > updateAt (\ _ _ -> Just "x") 1    (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "x")]
@@ -1004,8 +1008,9 @@ updateAt f i t = i `seq`
       where
         sizeL = size l
 
--- | /O(log n)/. Delete the element at /index/.
--- Defined as (@'deleteAt' i map = 'updateAt' (\k x -> 'Nothing') i map@).
+-- | /O(log n)/. Delete the element at /index/, i.e. by its zero-based index in
+-- the sequence sorted by keys. If the /index/ is out of range (less than zero,
+-- greater or equal to 'size' of the map), 'error' is called.
 --
 -- > deleteAt 0  (fromList [(5,"a"), (3,"b")]) == singleton 5 "a"
 -- > deleteAt 1  (fromList [(5,"a"), (3,"b")]) == singleton 3 "b"
diff --git a/Data/Set/Base.hs b/Data/Set/Base.hs
index 59c74eb..b664870 100644
--- a/Data/Set/Base.hs
+++ b/Data/Set/Base.hs
@@ -1044,9 +1044,10 @@ splitMember x (Bin _ y l r)
   Indexing
 --------------------------------------------------------------------}
 
--- | /O(log n)/. Return the /index/ of an element. The index is a number from
--- /0/ up to, but not including, the 'size' of the set. Calls 'error' when
--- the element is not a 'member' of the set.
+-- | /O(log n)/. Return the /index/ of an element, which is its zero-based
+-- index in the sorted sequence of elements. The index is a number from /0/ up
+-- to, but not including, the 'size' of the set. Calls 'error' when the element
+-- is not a 'member' of the set.
 --
 -- > findIndex 2 (fromList [5,3])    Error: element is not in the set
 -- > findIndex 3 (fromList [5,3]) == 0
@@ -1069,8 +1070,9 @@ findIndex = go 0
 {-# INLINABLE findIndex #-}
 #endif
 
--- | /O(log n)/. Lookup the /index/ of an element. The index is a number from
--- /0/ up to, but not including, the 'size' of the set.
+-- | /O(log n)/. Lookup the /index/ of an element, which is its zero-based index in
+-- the sorted sequence of elements. The index is a number from /0/ up to, but not
+-- including, the 'size' of the set.
 --
 -- > isJust   (lookupIndex 2 (fromList [5,3])) == False
 -- > fromJust (lookupIndex 3 (fromList [5,3])) == 0
@@ -1093,8 +1095,9 @@ lookupIndex = go 0
 {-# INLINABLE lookupIndex #-}
 #endif
 
--- | /O(log n)/. Retrieve an element by /index/. Calls 'error' when an
--- invalid index is used.
+-- | /O(log n)/. Retrieve an element by its /index/, i.e. by its zero-based
+-- index in the sorted sequence of elements. If the /index/ is out of range (less
+-- than zero, greater or equal to 'size' of the set), 'error' is called.
 --
 -- > elemAt 0 (fromList [5,3]) == 3
 -- > elemAt 1 (fromList [5,3]) == 5
@@ -1111,7 +1114,9 @@ elemAt i (Bin _ x l r)
   where
     sizeL = size l
 
--- | /O(log n)/. Delete the element at /index/.
+-- | /O(log n)/. Delete the element at /index/, i.e. by its zero-based index in
+-- the sorted sequence of elements. If the /index/ is out of range (less than zero,
+-- greater or equal to 'size' of the set), 'error' is called.
 --
 -- > deleteAt 0    (fromList [5,3]) == singleton 5
 -- > deleteAt 1    (fromList [5,3]) == singleton 3