add docstrings

Author: eulerkochy

src/swiss_dict.jl

@@ -1,6 +1,31 @@
-const SWISS_DICT_LOAD_FACTOR = 0.75      
+const SWISS_DICT_LOAD_FACTOR = 0.97
 const _u8x16 = NTuple{16, VecElement{UInt8}}
 
+"""
+    SwissDict([itr])
+
+`SwissDict{K,V}()` constructs a hash table with keys of type `K` and values of type `V`.
+Keys are compared with [`isequal`](@ref) and hashed with [`hash`](@ref).
+Given a single iterable argument, constructs a [`SwissDict`](@ref) whose key-value pairs
+are taken from 2-tuples `(key,value)` generated by the argument.
+
+# Examples
+```jldoctest
+julia> SwissDict([("A", 1), ("B", 2)])
+SwissDict{String,Int64} with 2 entries:
+  "B" => 2
+  "A" => 1
+```
+
+Alternatively, a sequence of pair arguments may be passed.
+
+```jldoctest
+julia> SwissDict("A"=>1, "B"=>2)
+SwissDict{String,Int64} with 2 entries:
+  "B" => 2
+  "A" => 1
+```
+"""
 mutable struct SwissDict{K,V} <: AbstractDict{K,V}
     slots::Vector{_u8x16}
     keys::Vector{K}
@@ -57,7 +82,7 @@ function SwissDict(kv)
     end
 end
 
-##SIMD utilities
+# SIMD utilities
 @inline _expand16(u::UInt8) = ntuple(i->VecElement(u), Val(16))
 _blsr(i::UInt32)= i & (i-Int32(1))
 
@@ -215,6 +240,7 @@ function _iterslots(h::SwissDict, start::Int)
     sl = ((~sl & 0xffff)>>off) << off
     return _iterslots(h, (i0, sl))
 end
+
 function _iterslots(h::SwissDict, state)
     i, sl = state
     while iszero(sl)
@@ -248,12 +274,6 @@ function maybe_rehash_shrink!(h::SwissDict)
    end
 end
 
-# function _dictsizehint(sz)
-#     (sz <= 16) && return 16
-#     nsz = _tablesz(sz)
-#     return (sz > SWISS_DICT_LOAD_FACTOR*nsz) ? (nsz<<1) : nsz
-# end
-
 function sizehint!(d::SwissDict, newsz)
     newsz = _tablesz(newsz*2)  # *2 for keys and values in same array
     oldsz = length(d.keys)
@@ -328,6 +348,24 @@ end
 isempty(t::SwissDict) = (t.count == 0)
 length(t::SwissDict) = t.count
 
+"""
+    empty!(collection) -> collection
+
+Remove all elements from a `collection`.
+
+# Examples
+```jldoctest
+julia> A = SwissDict("a" => 1, "b" => 2)
+SwissDict{String,Int64} with 2 entries:
+  "b" => 2
+  "a" => 1
+
+julia> empty!(A);
+
+julia> A
+SwissDict{String,Int64} with 0 entries
+```
+"""
 function empty!(h::SwissDict{K,V}) where {K, V}
     fill!(h.slots, _expand16(0x00))
     sz = length(h.keys)
@@ -344,9 +382,6 @@ end
 
 function setindex!(h::SwissDict{K,V}, v0, key0) where {K, V}
     key = convert(K, key0)
-    if !isequal(key, key0)
-        throw(ArgumentError("$(limitrepr(key0)) is not a valid key for type $K"))
-    end
     _setindex!(h, v0, key)
 end
 
@@ -359,23 +394,61 @@ function _setindex!(h::SwissDict{K,V}, v0, key::K) where {K, V}
         @inbounds h.keys[index] = key
         @inbounds h.vals[index] = v
     else
-        @inbounds _setindex!(h, v, key, -index, tag)
+        _setindex!(h, v, key, -index, tag)
     end
 
     return h
 end
 
+"""
+    get!(collection, key, default)
+
+Return the value stored for the given key, or if no mapping for the key is present, store
+`key => default`, and return `default`.
+
+# Examples
+```jldoctest
+julia> d = SwissDict("a"=>1, "b"=>2, "c"=>3);
+
+julia> get!(d, "a", 5)
+1
+
+julia> get!(d, "d", 4)
+4
+
+julia> d
+SwissDict{String,Int64} with 4 entries:
+  "c" => 3
+  "b" => 2
+  "a" => 1
+  "d" => 4
+```
+"""
 get!(h::SwissDict{K,V}, key0, default) where {K,V} = get!(()->default, h, key0)
 
+"""
+    get!(f::Function, collection, key)
+
+Return the value stored for the given key, or if no mapping for the key is present, store
+`key => f()`, and return `f()`.
+
+This is intended to be called using `do` block syntax:
+```julia
+get!(dict, key) do
+    # default value calculated here
+    time()
+end
+```
+"""
 function get!(default::Callable, h::SwissDict{K,V}, key0) where {K, V}
     key = convert(K, key0)
-    return get!(default, h, key)
+    return _get!(default, h, key)
 end
 
-function get!(default::Callable, h::SwissDict{K,V}, key::K) where {K, V}
+function _get!(default::Callable, h::SwissDict{K,V}, key::K) where {K, V}
     index, tag = ht_keyindex2!(h, key)
 
-    index > 0 && return h.vals[index]
+    index > 0 && return @inbounds h.vals[index]
 
     age0 = h.age
     v = convert(V, default())
@@ -387,7 +460,7 @@ function get!(default::Callable, h::SwissDict{K,V}, key::K) where {K, V}
         @inbounds h.keys[index] = key
         @inbounds h.vals[index] = v
     else
-        @inbounds _setindex!(h, v, key, -index, tag)
+        _setindex!(h, v, key, -index, tag)
     end
     return v
 end
@@ -397,25 +470,118 @@ function getindex(h::SwissDict{K,V}, key) where {K, V}
     @inbounds return (index < 0) ? throw(KeyError(key)) : h.vals[index]::V
 end
 
+"""
+    get(collection, key, default)
+
+Return the value stored for the given key, or the given default value if no mapping for the
+key is present.
+
+# Examples
+```jldoctest
+julia> d = SwissDict("a"=>1, "b"=>2);
+
+julia> get(d, "a", 3)
+1
+
+julia> get(d, "c", 3)
+3
+```
+"""
 function get(h::SwissDict{K,V}, key, default) where {K, V}
     index = ht_keyindex(h, key)
     @inbounds return (index < 0) ? default : h.vals[index]::V
 end
 
+"""
+    get(f::Function, collection, key)
+
+Return the value stored for the given key, or if no mapping for the key is present, return
+`f()`.  Use [`get!`](@ref) to also store the default value in the dictionary.
+
+This is intended to be called using `do` block syntax
+
+```julia
+get(dict, key) do
+    # default value calculated here
+    time()
+end
+```
+"""
 function get(default::Callable, h::SwissDict{K,V}, key) where {K, V}
     index = ht_keyindex(h, key)
     @inbounds return (index < 0) ? default() : h.vals[index]::V
 end
 
+"""
+    haskey(collection, key) -> Bool
+
+Determine whether a collection has a mapping for a given `key`.
+
+# Examples
+```jldoctest
+julia> D = SwissDict('a'=>2, 'b'=>3)
+SwissDict{Char,Int64} with 2 entries:
+  'a' => 2
+  'b' => 3
+
+julia> haskey(D, 'a')
+true
+
+julia> haskey(D, 'c')
+false
+```
+"""
 haskey(h::SwissDict, key) = (ht_keyindex(h, key) > 0)
 in(key, v::KeySet{<:Any, <:SwissDict}) = (ht_keyindex(v.dict, key) > 0)
 
+"""
+    getkey(collection, key, default)
+
+Return the key matching argument `key` if one exists in `collection`, otherwise return `default`.
+
+# Examples
+```jldoctest
+julia> D = SwissDict('a'=>2, 'b'=>3)
+SwissDict{Char,Int64} with 2 entries:
+  'a' => 2
+  'b' => 3
+
+julia> getkey(D, 'a', 1)
+'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)
 
+julia> getkey(D, 'd', 'a')
+'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)
+```
+"""
 function getkey(h::SwissDict{K,V}, key, default) where {K, V}
     index = ht_keyindex(h, key)
     @inbounds return (index<0) ? default : h.keys[index]::K
 end
 
+"""
+    pop!(collection, key[, default])
+
+Delete and return the mapping for `key` if it exists in `collection`, otherwise return
+`default`, or throw an error if `default` is not specified.
+
+# Examples
+```jldoctest
+julia> d = SwissDict("a"=>1, "b"=>2, "c"=>3);
+
+julia> pop!(d, "a")
+1
+
+julia> pop!(d, "d")
+ERROR: KeyError: key "d" not found
+Stacktrace:
+[...]
+
+julia> pop!(d, "e", 4)
+4
+```
+"""
+pop!(collection, key, default)
+
 function _pop!(h::SwissDict, index)
     @inbounds val = h.vals[index]
     _delete!(h, index)
@@ -445,6 +611,23 @@ function pop!(h::SwissDict)
     return key => val
 end
 
+"""
+    delete!(collection, key)
+
+Delete the mapping for the given key in a collection, and return the collection.
+
+# Examples
+```jldoctest
+julia> d = SwissDict("a"=>1, "b"=>2)
+SwissDict{String,Int64} with 2 entries:
+  "b" => 2
+  "a" => 1
+
+julia> delete!(d, "b")
+SwissDict{String,Int64} with 1 entry:
+  "a" => 1
+```
+"""
 function delete!(h::SwissDict, key)
     index = ht_keyindex(h, key)
     if index > 0