Repository : ssh://[email protected]/containers On branch : ghc-head Link : http://git.haskell.org/?p=packages/containers.git;a=commit;h=13092f14876aa1a39549ba2b5354e16bcb3f6f6f
>--------------------------------------------------------------- commit 13092f14876aa1a39549ba2b5354e16bcb3f6f6f Author: Milan Straka <[email protected]> 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 _______________________________________________ ghc-commits mailing list [email protected] http://www.haskell.org/mailman/listinfo/ghc-commits
