diff options
author | Sam Truzjan <pxqr.sta@gmail.com> | 2013-09-30 06:42:23 +0400 |
---|---|---|
committer | Sam Truzjan <pxqr.sta@gmail.com> | 2013-09-30 06:42:23 +0400 |
commit | 845a3e953ff2ccfe69ae934e1b1d80122363e336 (patch) | |
tree | 94221f393a613c26345ad1a5fdc3b6906e1f33d5 | |
parent | 9f468b73e44421d1e50d0d92a9605becb26c1e8d (diff) |
Added documentation to BDict
-rw-r--r-- | src/Data/BEncode/BDict.hs | 24 |
1 files changed, 20 insertions, 4 deletions
diff --git a/src/Data/BEncode/BDict.hs b/src/Data/BEncode/BDict.hs index 8ef6d20..4ff5caa 100644 --- a/src/Data/BEncode/BDict.hs +++ b/src/Data/BEncode/BDict.hs | |||
@@ -5,8 +5,8 @@ | |||
5 | -- Stability : stable | 5 | -- Stability : stable |
6 | -- Portability : portable | 6 | -- Portability : portable |
7 | -- | 7 | -- |
8 | -- This module defines a simple key value list which both faster and | 8 | -- This module defines a simple key\/value list which both faster |
9 | -- more suitable for bencode dictionaries. | 9 | -- and more suitable for bencode dictionaries then just [(k,v)]. |
10 | -- | 10 | -- |
11 | module Data.BEncode.BDict | 11 | module Data.BEncode.BDict |
12 | ( BKey | 12 | ( BKey |
@@ -22,7 +22,7 @@ module Data.BEncode.BDict | |||
22 | -- * Combine | 22 | -- * Combine |
23 | , Data.BEncode.BDict.union | 23 | , Data.BEncode.BDict.union |
24 | 24 | ||
25 | -- * Transformations | 25 | -- * Traversal |
26 | , Data.BEncode.BDict.map | 26 | , Data.BEncode.BDict.map |
27 | , Data.BEncode.BDict.bifoldMap | 27 | , Data.BEncode.BDict.bifoldMap |
28 | 28 | ||
@@ -46,7 +46,7 @@ type BKey = ByteString | |||
46 | -- one more constructor per cell | 46 | -- one more constructor per cell |
47 | -- | 47 | -- |
48 | 48 | ||
49 | -- | BDictMap is list of key value pairs sorted by keys. | 49 | -- | BDictMap is an ascending list of key\/value pairs sorted by keys. |
50 | data BDictMap a | 50 | data BDictMap a |
51 | = Cons !BKey a !(BDictMap a) | 51 | = Cons !BKey a !(BDictMap a) |
52 | | Nil | 52 | | Nil |
@@ -71,14 +71,17 @@ instance Monoid (BDictMap a) where | |||
71 | mempty = Data.BEncode.BDict.empty | 71 | mempty = Data.BEncode.BDict.empty |
72 | mappend = Data.BEncode.BDict.union | 72 | mappend = Data.BEncode.BDict.union |
73 | 73 | ||
74 | -- | /O(1)/. The empty dicionary. | ||
74 | empty :: BDictMap a | 75 | empty :: BDictMap a |
75 | empty = Nil | 76 | empty = Nil |
76 | {-# INLINE empty #-} | 77 | {-# INLINE empty #-} |
77 | 78 | ||
79 | -- | /O(1)/. Dictionary of one key-value pair. | ||
78 | singleton :: BKey -> a -> BDictMap a | 80 | singleton :: BKey -> a -> BDictMap a |
79 | singleton k v = Cons k v Nil | 81 | singleton k v = Cons k v Nil |
80 | {-# INLINE singleton #-} | 82 | {-# INLINE singleton #-} |
81 | 83 | ||
84 | -- | /O(n)/. Lookup the value at a key in the dictionary. | ||
82 | lookup :: BKey -> BDictMap a -> Maybe a | 85 | lookup :: BKey -> BDictMap a -> Maybe a |
83 | lookup x = go | 86 | lookup x = go |
84 | where | 87 | where |
@@ -88,6 +91,9 @@ lookup x = go | |||
88 | | otherwise = go xs | 91 | | otherwise = go xs |
89 | {-# INLINE lookup #-} | 92 | {-# INLINE lookup #-} |
90 | 93 | ||
94 | -- | /O(n + m)/. Merge two dictionaries by taking pair from both given | ||
95 | -- dictionaries. Dublicated keys are /not/ filtered. | ||
96 | -- | ||
91 | union :: BDictMap a -> BDictMap a -> BDictMap a | 97 | union :: BDictMap a -> BDictMap a -> BDictMap a |
92 | union Nil xs = xs | 98 | union Nil xs = xs |
93 | union xs Nil = xs | 99 | union xs Nil = xs |
@@ -95,6 +101,7 @@ union bd @ (Cons k v xs) bd' @ (Cons k' v' xs') | |||
95 | | k < k' = Cons k v (union xs bd') | 101 | | k < k' = Cons k v (union xs bd') |
96 | | otherwise = Cons k' v' (union bd xs') | 102 | | otherwise = Cons k' v' (union bd xs') |
97 | 103 | ||
104 | -- | /O(n)./ Map a function over all values in the dictionary. | ||
98 | map :: (a -> b) -> BDictMap a -> BDictMap b | 105 | map :: (a -> b) -> BDictMap a -> BDictMap b |
99 | map f = go | 106 | map f = go |
100 | where | 107 | where |
@@ -102,6 +109,9 @@ map f = go | |||
102 | go (Cons k v xs) = Cons k (f v) (go xs) | 109 | go (Cons k v xs) = Cons k (f v) (go xs) |
103 | {-# INLINE map #-} | 110 | {-# INLINE map #-} |
104 | 111 | ||
112 | -- | /O(n)/. Map each key\/value pair to a monoid and fold resulting | ||
113 | -- sequnce using 'mappend'. | ||
114 | -- | ||
105 | bifoldMap :: Monoid m => (BKey -> a -> m) -> BDictMap a -> m | 115 | bifoldMap :: Monoid m => (BKey -> a -> m) -> BDictMap a -> m |
106 | bifoldMap f = go | 116 | bifoldMap f = go |
107 | where | 117 | where |
@@ -109,10 +119,16 @@ bifoldMap f = go | |||
109 | go (Cons k v xs) = f k v `mappend` go xs | 119 | go (Cons k v xs) = f k v `mappend` go xs |
110 | {-# INLINE bifoldMap #-} | 120 | {-# INLINE bifoldMap #-} |
111 | 121 | ||
122 | -- | /O(n)/. Build a dictionary from a list of key\/value pairs where | ||
123 | -- the keys are in ascending order. | ||
124 | -- | ||
112 | fromAscList :: [(BKey, a)] -> BDictMap a | 125 | fromAscList :: [(BKey, a)] -> BDictMap a |
113 | fromAscList [] = Nil | 126 | fromAscList [] = Nil |
114 | fromAscList ((k, v) : xs) = Cons k v (fromAscList xs) | 127 | fromAscList ((k, v) : xs) = Cons k v (fromAscList xs) |
115 | 128 | ||
129 | -- | /O(n)/. Convert the dictionary to a list of key\/value pairs | ||
130 | -- where the keys are in ascending order. | ||
131 | -- | ||
116 | toAscList :: BDictMap a -> [(BKey, a)] | 132 | toAscList :: BDictMap a -> [(BKey, a)] |
117 | toAscList Nil = [] | 133 | toAscList Nil = [] |
118 | toAscList (Cons k v xs) = (k, v) : toAscList xs | 134 | toAscList (Cons k v xs) = (k, v) : toAscList xs |