From 2cb02a13aaa8e74c241fe8ea965bee87c3d6089d Mon Sep 17 00:00:00 2001 From: "Randolph M. Fritz" Date: Fri, 16 May 2025 20:40:30 -0700 Subject: [PATCH 1/4] collections.md: add ImmutableDict to list of dictionary types --- doc/src/base/collections.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/src/base/collections.md b/doc/src/base/collections.md index e724930222a13..d47b3bae3d0ea 100644 --- a/doc/src/base/collections.md +++ b/doc/src/base/collections.md @@ -186,6 +186,8 @@ thus may be garbage collected even when referenced in a hash table. Like `Dict` it uses `hash` for hashing and `isequal` for equality, unlike `Dict` it does not convert keys on insertion. + [`ImmutableDict`](@ref Base.ImmutableDict) is a linked list implementation. + [`Dict`](@ref)s can be created by passing pair objects constructed with `=>` to a [`Dict`](@ref) constructor: `Dict("A"=>1, "B"=>2)`. This call will attempt to infer type information from the keys and values (i.e. this example creates a `Dict{String, Int64}`). To explicitly specify types From 09c8a932602ec641534e546baaf1ee5012f6dc99 Mon Sep 17 00:00:00 2001 From: "Randolph M. Fritz" Date: Fri, 16 May 2025 20:42:22 -0700 Subject: [PATCH 2/4] dict.jl: revise and expand ImmutableDict docstring for clarity --- base/dict.jl | 54 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 47 insertions(+), 7 deletions(-) diff --git a/base/dict.jl b/base/dict.jl index e059fde102bab..60eaed1063d5b 100644 --- a/base/dict.jl +++ b/base/dict.jl @@ -776,20 +776,60 @@ struct ImmutableDict{K,V} <: AbstractDict{K,V} end """ - ImmutableDict + ImmutableDict(key=>value, key=>value, ...) -`ImmutableDict` is a dictionary implemented as an immutable linked list, -which is optimal for small dictionaries that are constructed over many individual insertions. -Note that it is not possible to remove a value, although it can be partially overridden and hidden -by inserting a new value with the same key. +`ImmutableDict{K,V}()` - ImmutableDict(KV::Pair) +`ImmutableDict` is a dictionary implemented as an immutable linked +list, used for small mappings with a few entries where the overhead +of accessing a hash table is higher than that of a linear search of a +linked list. -Create a new entry in the `ImmutableDict` for a `key => value` pair + Base.ImmutableDict(key=>value, key=>value, ...) + +`Base.ImmutableDict(key=>value, key=>value, ...)` constructs a linked +list; the first argument sets the type of the keys and values. Keys +are compared with `isequal`. + +`Base.ImmutableDict{K,V}()` constructs an empty list with keys of type +K and values of type V. + + Base.ImmutableDict(imdict, key=>value, key=>value, ...) + +`Base.ImmutableDict(imdict, key=>value, key=>value, ...)` constructs a +new `ImmutableDict` from an existing `ImmutableDict` and additional KV +pairs, returning a new list. The original `ImmutableDict` becomes the +tail of the new list. + +Pairs cannot be removed from an immutable dictionary, but they can be +shadowed by adding an additional pair with a duplicate key; indexing +operations will find the the last key added. - use `(key => value) in dict` to see if this particular combination is in the properties set - use `get(dict, key, default)` to retrieve the most recent value for a particular key +# Examples + + julia> ctypes = Base.ImmutableDict("char"=>:char, "int"=>:int) + Base.ImmutableDict{String, Symbol} with 2 entries: + "int" => :int + "char" => :char + + julia> ctypes = Base.ImmutableDict(ctypes, "float"=>:float, "double"=>:double) + Base.ImmutableDict{String, Symbol} with 4 entries: + "double" => :double + "float" => :float + "int" => :int + "char" => :char + + julia> viewparameters = Base.ImmutableDict{String,Any}() + Base.ImmutableDict{String, Any}() + + julia> viewparameters = Base.ImmutableDict( + viewparameters, "type"=>"perspective", "direction"=>(0, 0, 1)) + Base.ImmutableDict{String, Any} with 2 entries: + "direction" => (0, 0, 1) + "type" => "perspective" """ ImmutableDict ImmutableDict(KV::Pair{K,V}) where {K,V} = ImmutableDict{K,V}(KV[1], KV[2]) From ab3959d42bc36a0f6613d029bf056f70b3206ad2 Mon Sep 17 00:00:00 2001 From: "Randolph M. Fritz" Date: Mon, 19 May 2025 19:23:11 -0700 Subject: [PATCH 3/4] Switch key=>value, key=>value to key1=>value1, key2=>value2 for clarity Co-authored-by: Mason Protter --- base/dict.jl | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/base/dict.jl b/base/dict.jl index 60eaed1063d5b..dffcb7996909c 100644 --- a/base/dict.jl +++ b/base/dict.jl @@ -785,18 +785,17 @@ list, used for small mappings with a few entries where the overhead of accessing a hash table is higher than that of a linear search of a linked list. - Base.ImmutableDict(key=>value, key=>value, ...) -`Base.ImmutableDict(key=>value, key=>value, ...)` constructs a linked +`Base.ImmutableDict(key1=>value1, key2=>value2, ...)` constructs a linked list; the first argument sets the type of the keys and values. Keys are compared with `isequal`. `Base.ImmutableDict{K,V}()` constructs an empty list with keys of type K and values of type V. - Base.ImmutableDict(imdict, key=>value, key=>value, ...) + Base.ImmutableDict(imdict, key1=>value1, key2=>value2, ...) -`Base.ImmutableDict(imdict, key=>value, key=>value, ...)` constructs a +`Base.ImmutableDict(imdict, key1=>value1, key2=>value2, ...)` constructs a new `ImmutableDict` from an existing `ImmutableDict` and additional KV pairs, returning a new list. The original `ImmutableDict` becomes the tail of the new list. From 216fd221ceac2be9951f763a6ab9252a3c5f6cfe Mon Sep 17 00:00:00 2001 From: "Randolph M. Fritz" Date: Tue, 20 May 2025 11:33:40 -0700 Subject: [PATCH 4/4] Switch a last key=>value to numbered keys and values. Co-authored-by: Mason Protter --- base/dict.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/base/dict.jl b/base/dict.jl index dffcb7996909c..dde62736d8c9e 100644 --- a/base/dict.jl +++ b/base/dict.jl @@ -776,7 +776,7 @@ struct ImmutableDict{K,V} <: AbstractDict{K,V} end """ - ImmutableDict(key=>value, key=>value, ...) + ImmutableDict(key1=>value1, key2=>value2, ...) `ImmutableDict{K,V}()`