diff --git a/elm.json b/elm.json index d5b89d2..a1c9977 100644 --- a/elm.json +++ b/elm.json @@ -15,6 +15,7 @@ "Internal.Tools.Encode", "Internal.Tools.Hashdict", "Internal.Tools.Iddict", + "Internal.Tools.Mashdict", "Internal.Tools.Timestamp", "Internal.Tools.VersionControl", "Internal.Values.Context", diff --git a/src/Internal/Tools/Mashdict.elm b/src/Internal/Tools/Mashdict.elm new file mode 100644 index 0000000..22c27a8 --- /dev/null +++ b/src/Internal/Tools/Mashdict.elm @@ -0,0 +1,300 @@ +module Internal.Tools.Mashdict exposing + ( Mashdict + , empty, singleton, insert, remove, removeKey + , isEmpty, member, memberKey, get, size, isEqual + , keys, values, toList, fromList + , rehash, union + , encode, decoder, softDecoder + ) + +{-| + + +# Mashdict + +A **mashdict**, (short for "maybe mashdict") is a hashdict that uses a hash +function that _maybe_ returns a value. In this case, the mashdict exclusively +stores values for which the hashing algorithm returns a value, and it ignores +the outcome for all other scenarios. + +In general, you are advised to learn more about the +[Hashdict](Internal-Tools-Hashdict) before delving into the Mashdict. + + +## Dictionaries + +@docs Mashdict + + +## Build + +@docs empty, singleton, insert, remove, removeKey + + +## Query + +@docs isEmpty, member, memberKey, get, size, isEqual + + +## Lists + +@docs keys, values, toList, fromList + + +## Transform + +@docs rehash, union + + +## JSON coders + +@docs encode, decoder, softDecoder + +-} + +import FastDict as Dict exposing (Dict) +import Json.Decode as D +import Json.Encode as E + + +{-| A dictionary of keys and values where each key is defined by its value, but +a value is not always given. For example, this can be relevant when not all +inserted values are relevant: + + import Mashdict exposing (Mashdict) + + users : Mashdict Event + users = + Mashdict.fromList .location + [ Event "Graduation party" 8 (Just "park") + , Event "National holiday" 17 Nothing + , Event "Local fair" 11 (Just "town square") + ] + + -- National holiday will be ignored + -- because it does not hash + type alias Event = + { name : String + , participants : Int + , location : Maybe String + } + +In the example listed above, all events are stored by their specified location, +which means that all you need to know is the value "park" to retrieve all the +information about the event at the park. As a result of optimization, this means +all values without a hash, are filtered out, as we can never query them. + +-} +type Mashdict a + = Mashdict + { hash : a -> Maybe String + , values : Dict String a + } + + +{-| Decode a mashdict from a JSON value. To create a mashdict, you are expected +to insert a hash function. If the hash function doesn't properly hash the values +as expected, the decoder will fail to decode the mashdict. +-} +decoder : (a -> Maybe String) -> D.Decoder a -> D.Decoder (Mashdict a) +decoder f xDecoder = + D.keyValuePairs xDecoder + |> D.andThen + (\items -> + if List.all (\( hash, value ) -> f value == Just hash) items then + items + |> Dict.fromList + |> (\d -> { hash = f, values = d }) + |> Mashdict + |> D.succeed + + else + D.fail "Hash function fails to properly hash all values" + ) + + +{-| Create an empty mashdict. +-} +empty : (a -> Maybe String) -> Mashdict a +empty hash = + Mashdict { hash = hash, values = Dict.empty } + + +{-| Encode a Mashdict into a JSON value. Keep in mind that an Elm function +cannot be universally converted to JSON, so it is up to you to preserve that +hash function! +-} +encode : (a -> E.Value) -> Mashdict a -> E.Value +encode encodeX (Mashdict h) = + h.values + |> Dict.toList + |> List.map (Tuple.mapSecond encodeX) + |> E.object + + +{-| Convert an association list into a mashdict. +-} +fromList : (a -> Maybe String) -> List a -> Mashdict a +fromList hash xs = + Mashdict + { hash = hash + , values = + xs + |> List.filterMap (\x -> hash x |> Maybe.map (\hx -> ( hx, x ))) + |> Dict.fromList + } + + +{-| Get the value associated with a hash. If the hash is not found, return +`Nothing`. This is useful when you are not sure if a hash will be in the +mashdict. +-} +get : String -> Mashdict a -> Maybe a +get k (Mashdict h) = + Dict.get k h.values + + +{-| Insert a value into a mashdict. The key is automatically generated by the +hash function. If the function generates a collision, it replaces the existing +value in the mashdict. If the function returns `Nothing`, the value isn't +inserted and the original Mashdict is returned. +-} +insert : a -> Mashdict a -> Mashdict a +insert v (Mashdict h) = + case h.hash v of + Just hash -> + Mashdict { h | values = Dict.insert hash v h.values } + + Nothing -> + Mashdict h + + +{-| Determine if a mashdict is empty. +-} +isEmpty : Mashdict a -> Bool +isEmpty (Mashdict h) = + Dict.isEmpty h.values + + +{-| Since the Hashdict contains a hash function, the == operator does not work +simply. Instead, you should use the isEqual operator. +-} +isEqual : Mashdict a -> Mashdict a -> Bool +isEqual h1 h2 = + toList h1 == toList h2 + + +{-| Get all of the hashes in a mashdict, sorted from lowest to highest. +-} +keys : Mashdict a -> List String +keys (Mashdict h) = + Dict.keys h.values + + +{-| Determine if a value's hash is in a mashdict. +-} +member : a -> Mashdict a -> Bool +member value (Mashdict h) = + h.hash value + |> Maybe.map (\key -> Dict.member key h.values) + |> Maybe.withDefault False + + +{-| Determine if a hash is in a mashdict. +-} +memberKey : String -> Mashdict a -> Bool +memberKey key (Mashdict h) = + Dict.member key h.values + + +{-| Remap a mashdict using a new hashing algorithm. +-} +rehash : (a -> Maybe String) -> Mashdict a -> Mashdict a +rehash f (Mashdict h) = + Mashdict + { hash = f + , values = + h.values + |> Dict.values + |> List.filterMap + (\v -> Maybe.map (\hash -> ( hash, v )) (f v)) + |> Dict.fromList + } + + +{-| Remove a value from a mashdict. If the value's hash is found, the key-value +pair is removed. If the value's hash is not found, no changes are made. + + hdict |> Mashdict.remove (Event "Graduation party" 8 (Just "park")) + +-} +remove : a -> Mashdict a -> Mashdict a +remove v (Mashdict h) = + case h.hash v of + Just hash -> + Mashdict { h | values = Dict.remove hash h.values } + + Nothing -> + Mashdict h + + +{-| Remove a key from a mashdict. If the key is not found, no changes are made. + + hdict |> Mashdict.removeKey "park" + +-} +removeKey : String -> Mashdict a -> Mashdict a +removeKey k (Mashdict h) = + Mashdict { h | values = Dict.remove k h.values } + + +{-| Create a mashdict with a single key-value pair. +-} +singleton : (a -> Maybe String) -> a -> Mashdict a +singleton f v = + empty f |> insert v + + +{-| Determine the number of values in a mashdict. +-} +size : Mashdict a -> Int +size (Mashdict h) = + Dict.size h.values + + +{-| Decode a mashdict from a JSON value. If you cannot deduce the originally +used hash function, (or if you simply do not care) you can use this function to +decode and rehash the Mashdict using your new hash function. +-} +softDecoder : (a -> Maybe String) -> D.Decoder a -> D.Decoder (Mashdict a) +softDecoder f xDecoder = + D.keyValuePairs xDecoder + |> D.map (List.map Tuple.second >> fromList f) + + +{-| Convert a mashdict into an association list of key-value pairs, sorted by +keys. +-} +toList : Mashdict a -> List ( String, a ) +toList (Mashdict h) = + Dict.toList h.values + + +{-| Combine two mashdicts under the hash function of the first. If there is a +collision, preference is given to the first mashdict. +-} +union : Mashdict a -> Mashdict a -> Mashdict a +union (Mashdict h1) hd2 = + case rehash h1.hash hd2 of + Mashdict h2 -> + Mashdict + { hash = h1.hash + , values = Dict.union h1.values h2.values + } + + +{-| Get all values stored in the mashdict, in the order of their keys. +-} +values : Mashdict a -> List a +values (Mashdict h) = + Dict.values h.values diff --git a/tests/Test/Tools/Mashdict.elm b/tests/Test/Tools/Mashdict.elm new file mode 100644 index 0000000..dfddc6c --- /dev/null +++ b/tests/Test/Tools/Mashdict.elm @@ -0,0 +1,204 @@ +module Test.Tools.Mashdict exposing (..) + +import Expect +import Fuzz exposing (Fuzzer) +import Internal.Tools.Mashdict as Mashdict exposing (Mashdict) +import Internal.Values.Event as Event +import Json.Decode as D +import Json.Encode as E +import Test exposing (..) +import Test.Values.Event as TestEvent + + +fuzzer : (a -> Maybe String) -> Fuzzer a -> Fuzzer (Mashdict a) +fuzzer toHash fuz = + Fuzz.map (Mashdict.fromList toHash) (Fuzz.list fuz) + + +eventFuzzer : Fuzzer (Mashdict Event.Event) +eventFuzzer = + fuzzer .stateKey TestEvent.fuzzer + + +suite : Test +suite = + describe "Mashdict" + [ describe "empty" + [ test "empty isEmpty" + (Mashdict.empty identity + |> Mashdict.isEmpty + |> Expect.equal True + |> always + ) + , fuzz TestEvent.fuzzer + "Nothing is member" + (\event -> + Mashdict.empty .stateKey + |> Mashdict.member event + |> Expect.equal False + ) + , fuzz Fuzz.string + "No key is member" + (\key -> + Mashdict.empty identity + |> Mashdict.memberKey key + |> Expect.equal False + ) + , fuzz Fuzz.string + "Get gets Nothing" + (\key -> + Mashdict.empty identity + |> Mashdict.get key + |> Expect.equal Nothing + ) + , test "Size is zero" + (Mashdict.empty identity + |> Mashdict.size + |> Expect.equal 0 + |> always + ) + , test "No keys" + (Mashdict.empty identity + |> Mashdict.keys + |> Expect.equal [] + |> always + ) + , test "No values" + (Mashdict.empty identity + |> Mashdict.values + |> Expect.equal [] + |> always + ) + , test "To list is []" + (Mashdict.empty identity + |> Mashdict.toList + |> Expect.equal [] + |> always + ) + , test "From list is empty" + ([] + |> Mashdict.fromList (\x -> x) + |> Mashdict.isEqual (Mashdict.empty identity) + |> Expect.equal True + |> always + ) + , test "Empty + empty == empty" + (Mashdict.empty Maybe.Just + |> Mashdict.union (Mashdict.empty Maybe.Just) + |> Mashdict.isEqual (Mashdict.empty Maybe.Just) + |> Expect.equal True + |> always + ) + , fuzz (Fuzz.intRange 0 10) + "JSON encode -> JSON decode" + (\indent -> + Mashdict.empty Just + |> Mashdict.encode E.string + |> E.encode indent + |> D.decodeString (Mashdict.decoder Just D.string) + |> Result.map (Mashdict.isEqual (Mashdict.empty Just)) + |> Expect.equal (Ok True) + ) + ] + , describe "singleton" + [ fuzz TestEvent.fuzzer + "singleton = empty + insert" + (\event -> + Mashdict.empty .stateKey + |> Mashdict.insert event + |> Mashdict.isEqual (Mashdict.singleton .stateKey event) + |> Expect.equal True + ) + , fuzz TestEvent.fuzzer + "singleton - event = empty" + (\event -> + Mashdict.singleton .stateKey event + |> Mashdict.remove event + |> Mashdict.isEqual (Mashdict.empty (always Nothing)) + |> Expect.equal True + ) + , fuzz TestEvent.fuzzer + "singleton - event (key) = empty" + (\event -> + case event.stateKey of + Just key -> + Mashdict.singleton .stateKey event + |> Mashdict.removeKey key + |> Mashdict.isEqual (Mashdict.empty .stateKey) + |> Expect.equal True + + Nothing -> + Expect.pass + ) + , fuzz TestEvent.fuzzer + "Only isEmpty when not Nothing" + (\event -> + Expect.equal + (case event.stateKey of + Just _ -> + False + + Nothing -> + True + ) + (event + |> Mashdict.singleton .stateKey + |> Mashdict.isEmpty + ) + ) + , fuzz TestEvent.fuzzer + "member" + (\event -> + Expect.equal + (case event.stateKey of + Just _ -> + True + + Nothing -> + False + ) + (Mashdict.singleton .stateKey event + |> Mashdict.member event + ) + ) + , fuzz2 TestEvent.fuzzer + Fuzz.string + "memberKey" + (\event rkey -> + case event.stateKey of + Just key -> + Mashdict.singleton .stateKey event + |> Mashdict.memberKey key + |> Expect.equal True + + Nothing -> + Mashdict.singleton .stateKey event + |> Mashdict.memberKey rkey + |> Expect.equal False + ) + , fuzz TestEvent.fuzzer + "False memberKey" + (\event -> + if event.stateKey == Just event.roomId then + Expect.pass + + else + Mashdict.singleton .stateKey event + |> Mashdict.memberKey event.roomId + |> Expect.equal False + ) + ] + , describe "JSON" + [ fuzz2 eventFuzzer + (Fuzz.intRange 0 10) + "JSON encode -> JSON decode" + (\hashdict indent -> + hashdict + |> Mashdict.encode Event.encode + |> E.encode indent + |> D.decodeString (Mashdict.decoder .stateKey Event.decoder) + |> Result.map Mashdict.toList + |> Expect.equal (Ok <| Mashdict.toList hashdict) + ) + ] + ]