From ddcf47b10abe4e3712f1a3de93c1aecee168a2db Mon Sep 17 00:00:00 2001
From: Sam Buercklin <SBuercklin@users.noreply.github.com>
Date: Wed, 11 Oct 2023 10:27:21 -0400
Subject: [PATCH] Update README.md

---
 README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/README.md b/README.md
index 68e5f52..b4a456b 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,68 @@
 # ConcreteTupleDicts.jl
 TupleDicts are type-stable dictionaries which support multiple sets of key-value pair types
+
+# Basic Usage
+Say you would like to make the following `Dict`, but you want key retrieval to be type stable
+
+```julia
+using Test
+
+d = Dict{Union{Int,Float64,String},Union{Int,Float64}}(1 => 2, 2.0 => 3.0, "three" => 4)
+
+@inferred d[1]     # Inference fails because it infers Union{Int, Float64}
+```
+
+A `TupleDict` can be constructed by passing in a tuple of `Dict`s, and it preserves the association of each keytype to its correspdonding valtype. 
+
+These `Dict`s can then be treated as one single `Dict`, while maintaining type stable retrieval
+
+```julia
+using ConcreteTupleDicts
+
+d1 = Dict(1 => 2)
+d2 = Dict(2.0 => 3.0)
+d3 = Dict("three" => 4)
+
+ds = (d1, d2, d3)
+
+td = TupleDict(ds)
+
+@inferred td[1]        # Properly infers Int
+@inferred td[2.0]      # Properly infers Float64
+@inferred td["three"]  # Properly infers Int
+```
+
+These `Dict`s must not have overlapping key types in order to permit an unambiguous mapping from a given keytype to a valtype.
+
+```julia
+d1 = Dict(1 => 2)
+d2 = Dict(3 => 4.0)
+
+TupleDict((d1, d2))  # Throws an error, Int maps to both Int and Float64
+```
+
+But `TupleDict`s are smart enough to merge keytypes which map to the same valtype
+
+```julia
+d1 = Dict(1 => 2)
+d2 = Dict{Union{Int, String}, Int}(3 => 4, "five" => 6)
+
+td = TupleDict((d1, d2)) # no issues, everything unamibuously maps to `Int`
+
+@inferred td["five"]     # Properly infers Int
+```
+
+And the expected `Dict` behavior is still there
+
+```julia
+d1 = Dict(1 => 2)
+d2 = Dict(2.0 => 3.0)
+d3 = Dict("three" => 4)
+
+ds = (d1, d2, d3)
+
+td = TupleDict(ds)
+
+keytype(td)     # Union{Float64, Int64, String}
+valtype(td)     # Union{Float64, Int64)  
+```