@@ -1,5 +1,5 @@
11module Dict (empty,singleton,insert,update
2− ,lookup,findWithDefault
2+ ,get,getMaybe,getWithDefault
33 ,remove,member
44 ,filter
55 ,partition
@@ -19,7 +19,7 @@ Insert, remove, and query operations all take *O(log n)* time.
1919@docs empty, singleton, insert, update, remove
2020
2121# Query
22−@docs member, lookup, findWithDefault
22+@docs member, get, getMaybe, getWithDefault
2323
2424# Combine
2525@docs union, intersect, diff
@@ -37,6 +37,7 @@ import Basics (..)
3737import Maybe (..)
3838import Native.Error
3939import List
40+import String
4041import Native.Utils
4142
4243-- BBlack and NBlack should only be used during the deletion
@@ -86,33 +87,71 @@ max t =
8687 RBNode _ _ _ _ r -> max r
8788 RBEmpty _ -> Native.Error.raise "(max Empty) is not defined"
8889
89−{-| Lookup the value associated with a key. -}
90−lookup : comparable -> Dict comparable v -> Maybe v
91−lookup k t =
90+{-| Get the value associated with a key.
91+
92+ animals = fromList [ ("Tom", Cat), ("Jerry", Mouse) ]
93+
94+ get "Tom" animals == Cat
95+ get "Mouse" animals == Mouse
96+ get "Spike" animals -- Runtime Error!
97+
98+Warning: this function will result in a runtime error if the key is not found,
99+so it is best to use `getMaybe` or `getWithDefault` unless you are very
100+confident the key will be found.
101+-}
102+get : comparable -> Dict comparable v -> v
103+get k t =
104+ case t of
105+ RBEmpty LBlack -> Native.Error.raise <| String.concat [ "key ", String.show k, " not found." ]
106+ RBNode _ k' v l r ->
107+ case Native.Utils.compare k k' of
108+ LT -> get k l
109+ EQ -> v
110+ GT -> get k r
111+
112+{-| Get the value associated with a key. If the key is not found, return
113+`Nothing`. This is useful when you are not sure if a key will be in the
114+dictionary.
115+
116+ animals = fromList [ ("Tom", Cat), ("Jerry", Mouse) ]
117+
118+ getMaybe "Tom" animals == Just Cat
119+ getMaybe "Mouse" animals == Just Mouse
120+ getMaybe "Spike" animals == Nothing
121+-}
122+getMaybe : comparable -> Dict comparable v -> Maybe v
123+getMaybe k t =
92124 case t of
93125 RBEmpty LBlack -> Nothing
94126 RBNode _ k' v l r ->
95127 case Native.Utils.compare k k' of
96− LT -> lookup k l
128+ LT -> getMaybe k l
97129 EQ -> Just v
98− GT -> lookup k r
130+ GT -> getMaybe k r
99131
100−{-| Find the value associated with a key. If the key is not found,
101−return the default value. -}
102−findWithDefault : v -> comparable -> Dict comparable v -> v
103−findWithDefault base k t =
132+{-| Get the value associated with a key. If the key is not found,
133+return a default value.
134+
135+ animals = fromList [ ("Tom", Cat), ("Jerry", Mouse) ]
136+
137+ getWithDefault Dog "Tom" animals == Cat
138+ getWithDefault Dog "Mouse" animals == Mouse
139+ getWithDefault Dog "Spike" animals == Dog
140+-}
141+getWithDefault : v -> comparable -> Dict comparable v -> v
142+getWithDefault base k t =
104143 case t of
105144 RBEmpty LBlack -> base
106145 RBNode _ k' v l r ->
107146 case Native.Utils.compare k k' of
108− LT -> findWithDefault base k l
147+ LT -> getWithDefault base k l
109148 EQ -> v
110− GT -> findWithDefault base k r
149+ GT -> getWithDefault base k r
111150
112151{-| Determine if a key is in a dictionary. -}
113152member : comparable -> Dict comparable v -> Bool
114153-- Does t contain k?
115−member k t = isJust <| lookup k t
154+member k t = isJust <| getMaybe k t
116155
117156ensureBlackRoot : Dict k v -> Dict k v
118157ensureBlackRoot t =
@@ -358,8 +397,10 @@ filter p dict =
358397 let add k v t = if p k v then insert k v t else t
359398 in foldl add empty dict
360399
361−{-| Partition the Dict according to a predicate. The first Dict contains all
362−key-value pairs which satisfy it; the second contains the rest. -}
400+{-| Partition a dictionary according to a predicate. The first dictionary
401+contains all key-value pairs which satisfy the predicate, and the second
402+contains the rest.
403+-}
363404partition : (comparable -> v -> Bool) -> Dict comparable v -> (Dict comparable v, Dict comparable v)
364405partition p dict =
365406 let add k v (t1, t2) = if p k v