tricycle / elm-storage / Storage


type alias Storage =
Internal.Storage

A storage container of keys and values.

import Storage exposing (Storage)
import Storage.Value as Value

configuration: Storage
configuration =
    Storage.fromList [
    ("config.item.a", Value.string "some value")
    , ("config.item.b", Value.float 1.5)
    ]


Storage.getString "config.item.a" configuration
--> Just "some value"

Storage.getString "config.item.b" configuration
--> Nothing

Storage.getStringUnsafe "config.item.a" configuration
--> "some value"

Storage.getStringUnsafe "config.item.b" configuration
--> "1.5"

Storage.getFloat "config.item.a" configuration
--> Nothing

Storage.getFloat "config.item.b" configuration
--> Just "1.5"

Build

empty
    |> insert "foo" (Value.string "bar")
--> fromList [ ( "foo", Value.string "bar" ) ]

empty : Storage

Create an empty Storage container

singleton : String -> Internal.Value.Value -> Storage

Create a Storage container with one String-Value pair.

singleton "fruit" (Value.string "apple")
--> fromList [ ( "fruit", Value.string "apple" ) ]

insert : String -> Internal.Value.Value -> Storage -> Storage

Insert a String-Value pair into a Storage container. Replaces value when there is a collision.

empty
    |> insert "fruit" (Value.string "apple")
    |> insert "fruit" (Value.string "banana")
--> fromList [ ( "fruit", Value.string "banana" ) ]

update : String -> (Maybe Internal.Value.Value -> Maybe Internal.Value.Value) -> Storage -> Storage

Update a Value for a specific key with a given function.

empty
    |> insert "fruit" (Value.string "apple")
    |> update "fruit" (Maybe.map (\_ -> Value.string "banana"))
--> fromList [ ( "fruit", Value.string "banana" ) ]

remove : String -> Storage -> Storage

Remove a String-Value pair from a Storage container. If the key is not found, no changes are made.

empty
    |> insert "fruit" (Value.string "apple")
    |> remove "fruit"
--> empty

Query

isEmpty : Storage -> Basics.Bool

Determine if a Storage container is empty.

isEmpty empty
--> True

isEmpty (fromList [])
--> True

empty
    |> insert "fruit" (Value.string "apple")
    |> isEmpty
--> False

empty
    |> insert "fruit" (Value.string "apple")
    |> remove "fruit"
    |> isEmpty
--> True

member : String -> Storage -> Basics.Bool

Determine if a key is in a Storage.

empty
    |> insert "fruit" (Value.string "apple")
    |> member "fruit"
--> True

empty
    |> insert "fruit" (Value.string "apple")
    |> member "apple"
--> False

size : Storage -> Basics.Int

Determine the number of String-Value pairs in the Storage container.

fromList [("foo", Value.empty)]
|> size
--> 1

get : String -> Storage -> Maybe Internal.Value.Value

Get the Value associated with a key. If the key is not found, return Nothing. This is useful when you are not sure if a key will be in the Storage.

empty
    |> insert "fruit" (Value.string "apple")
    |> get "fruit"
--> Just (Value.string "apple")

empty
    |> insert "fruit" (Value.string "apple")
    |> get "apple"
--> Nothing

getBool : String -> Storage -> Maybe Basics.Bool

Safely get the Bool associated with a key. If the key is not found OR if the value is not a Bool, return Nothing.

empty
    |> insert "is.cool" (Value.bool True)
    |> getBool "is.cool"
    --> Just True

getFloat : String -> Storage -> Maybe Basics.Float

Safely get the Float associated with a key. If the key is not found OR if the value is not a Float, return Nothing.

empty
    |> insert "velocity" (Value.float 1.6)
    |> getFloat "velocity"
    --> Just 1.6

getInt : String -> Storage -> Maybe Basics.Int

Safely get the Int associated with a key. If the key is not found OR if the value is not a Int, return Nothing.

empty
    |> insert "moons" (Value.int 1)
    |> getInt "moons"
    --> Just 1

getString : String -> Storage -> Maybe String

Safely get the String associated with a key. If the key is not found OR if the value is not a String, return Nothing.

empty
    |> insert "fruit" (Value.string "apple")
    |> getString "fruit"
    --> Just "apple"

getJson : String -> Storage -> Maybe Json.Encode.Value

Safely get the Json associated with a key. If the key is not found OR if the value is not a Json, return Nothing.

getStringUnsafe : String -> Storage -> String

Unsafely get a String associated with a key. If the key is not found return an empty String ("")

Lists

keys : Storage -> List String

Get all of the keys in a Storage container, sorted from lowest to highest.

fromList [("foo", Value.empty), ("bar", Value.empty)]
    |> keys
--> ["bar", "foo"]

values : Storage -> List Internal.Value.Value

Get all of the values in a Storage container, in the order of their keys.

fromList [("foo", Value.string "a"), ("bar", Value.string "b")]
    |> values
--> [Value.string "b", Value.string "a"]

toList : Storage -> List ( String, Internal.Value.Value )

Convert a dictionary into an Storage container list of key-StoageItem pairs, sorted by keys.

insert "fruit" (Value.string "apple") empty
|> toList
--> [ ( "fruit", Value.string "apple" ) ]

fromList : List ( String, Internal.Value.Value ) -> Storage

Convert an association list into a Storage container.

fromList [
    ( "fruit", Value.string "apple" )
]
--> insert "fruit" (Value.string "apple") empty

Combine

union : Storage -> Storage -> Storage

Combine two Storage containers. If there is a collision, preference is given to the first Storage container.

union
    ( fromList [("a", Value.string "a1"), ("c", Value.string "c1")] )
    ( fromList [("a", Value.string "a2"), ("b2", Value.string "b2")] )
--> fromList [ ( "a", Value.string "a1" ), ( "b", Value.string "b2" ), ( "c", Value.string "c1" ) ]

intersect : Storage -> Storage -> Storage

Keep a String-value pair when its key appears in the second Storage container. Preference is given to values in the first Storage container.

intersect
    ( fromList [("a", Value.string "a1"), ("c", Value.string "c1")] )
    ( fromList [("a", Value.string "a2"), ("b2", Value.string "b2")] )
--> fromList [ ( "a", Value.string "a1" )]

diff : Storage -> Storage -> Storage

Keep a String-value pair when its key does not appear in the second Storage container.

diff
    ( fromList [("a", Value.string "a1"), ("c", Value.string "c1")] )
    ( fromList [("a", Value.string "a2"), ("b2", Value.string "b2")] )
--> fromList [ ("c", Value.string "c1") ]

merge : (String -> Internal.Value.Value -> result -> result) -> (String -> Internal.Value.Value -> Internal.Value.Value -> result -> result) -> (String -> Internal.Value.Value -> result -> result) -> Storage -> Storage -> result -> result

The most general way of combining two Storage containers. You provide three accumulators for when a given key appears:

You then traverse all the keys from lowest to highest, building up whatever you want.