Merge pull request JuliaCollections#730 from mbauman/mb/default-dict-docs

Document Default*Dict and add Default*Dict{K,V} constructors

Author: oxinabox

Project.toml

@@ -2,7 +2,6 @@ name = "DataStructures"
 uuid = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 version = "0.19.0-DEV"
 
-
 [deps]
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"

src/default_dict.jl

@@ -85,6 +85,19 @@ end
 for _Dict in [:Dict, :OrderedDict]
     DefaultDict = Symbol("Default"*string(_Dict))
     @eval begin
+        """
+            $($DefaultDict)(default, pairs...; passkey=false)
+            $($DefaultDict)(default, d::AbstractDict; passkey=false)
+            $($DefaultDict){K, V}(default, pairs...; passkey=false)
+            $($DefaultDict){K, V}(default, dict::AbstractDict; passkey=false)
+        
+        Construct an $($(_Dict == :Dict ? "un" : ""))ordered dictionary from the given key-value `pairs` or `dict`
+        with a `default` value to be returned for keys that are not stored in the dictionary. The key and value
+        types may be optionally specified with the `K` and `V` parameters.
+        
+        If the `default` value is a `Function` or `Type`, then it will be _called_ upon the retrieval of a missing key,
+        with either 0 arguments (if `passkey==false`) or with the key that was requested.
+        """
         struct $DefaultDict{K,V,F} <: AbstractDict{K,V}
             d::DefaultDictBase{K,V,F,$_Dict{K,V}}
 
@@ -113,7 +126,8 @@ for _Dict in [:Dict, :OrderedDict]
 
         # Constructor syntax: DefaultDictBase{Int,Float64}(default)
         $DefaultDict{K,V}(; kwargs...) where {K,V} = throw(ArgumentError("$DefaultDict: no default specified"))
-        $DefaultDict{K,V}(default::F; kwargs...) where {K,V,F} = $DefaultDict{K,V,F}(default; kwargs...)
+        $DefaultDict{K,V}(default::F, pairs...; kwargs...) where {K,V,F} = $DefaultDict{K,V,F}(default, $_Dict{K,V}(pairs...); kwargs...)
+        $DefaultDict{K,V}(default::F, d::AbstractDict; kwargs...) where {K,V,F} = $DefaultDict{K,V,F}(default, $_Dict{K,V}(d); kwargs...)
 
         ## Functions
 

test/test_default_dict.jl

@@ -1,4 +1,4 @@
-import DataStructures: DefaultDictBase
+import DataStructures: DefaultDictBase, OrderedDict
 
 @testset "DefaultDict" begin
 
@@ -26,6 +26,14 @@ import DataStructures: DefaultDictBase
             @test_throws ArgumentError DefaultDict{AbstractString, Int}()
 
             @test isa(DefaultDict(0.0, 1 => 1.0), DefaultDict{Int, Float64, Float64})
+            @test isa(DefaultDict(0.0, Dict(1 => 1.0)), DefaultDict{Int, Float64, Float64})
+
+            @test isa(DefaultDict{Float64, Int}(0.0), DefaultDict{Float64, Int, Float64})
+            @test isa(DefaultDict{Float64, Int}(0.0, Dict()), DefaultDict{Float64, Int, Float64})
+            @test isa(DefaultDict{Float64, Int}(0.0, OrderedDict()), DefaultDict{Float64, Int, Float64})
+            @test isa(DefaultDict{Float64, Int}(0.0, 1 => 1.0), DefaultDict{Float64, Int, Float64})
+            @test isa(DefaultDict{Float64, Int}(0.0, Dict(1 => 1.0)), DefaultDict{Float64, Int, Float64})
+            @test isa(DefaultDict{Float64, Int}(0.0, OrderedDict(1 => 1.0)), DefaultDict{Float64, Int, Float64})
         end
 
         @testset "Core Functionality" begin
@@ -132,7 +140,18 @@ import DataStructures: DefaultDictBase
     @testset "DefaultOrderedDict" begin
         @testset "construction" begin
             @test_throws ArgumentError DefaultOrderedDict()
+            @test_throws ArgumentError DefaultOrderedDict(AbstractString, Int)
             @test_throws ArgumentError DefaultOrderedDict{AbstractString, Int}()
+
+            @test isa(DefaultOrderedDict(0.0, 1 => 1.0), DefaultOrderedDict{Int, Float64, Float64})
+            @test isa(DefaultOrderedDict(0.0, Dict(1 => 1.0)), DefaultOrderedDict{Int, Float64, Float64})
+
+            @test isa(DefaultOrderedDict{Float64, Int}(0.0), DefaultOrderedDict{Float64, Int, Float64})
+            @test isa(DefaultOrderedDict{Float64, Int}(0.0, Dict()), DefaultOrderedDict{Float64, Int, Float64})
+            @test isa(DefaultOrderedDict{Float64, Int}(0.0, OrderedDict()), DefaultOrderedDict{Float64, Int, Float64})
+            @test isa(DefaultOrderedDict{Float64, Int}(0.0, 1 => 1.0), DefaultOrderedDict{Float64, Int, Float64})
+            @test isa(DefaultOrderedDict{Float64, Int}(0.0, Dict(1 => 1.0)), DefaultOrderedDict{Float64, Int, Float64})
+            @test isa(DefaultOrderedDict{Float64, Int}(0.0, OrderedDict(1 => 1.0)), DefaultOrderedDict{Float64, Int, Float64})
         end
 
         @testset "Core Functionality" begin