From ef74b6707aff5ab6feddef78ed03e0d64219386e Mon Sep 17 00:00:00 2001
From: Andy Ferris <andy.ferris@roames.com.au>
Date: Mon, 30 Oct 2017 11:46:32 +1000
Subject: [PATCH] Made less breaking, added news, empty works on more
 containers.

---
 NEWS.md               |  7 +++++++
 base/abstractarray.jl | 18 ++++++++++++++++++
 base/associative.jl   |  6 +++++-
 base/deprecated.jl    |  1 +
 base/tuple.jl         |  7 +++++++
 test/abstractarray.jl | 16 ++++++++++++++--
 test/dict.jl          | 10 +++++-----
 test/tuple.jl         |  2 ++
 8 files changed, 59 insertions(+), 8 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index cdf940755907f..0b376ea54bb64 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1229,6 +1229,13 @@ Deprecated or removed
 
   * `EnvHash` has been renamed to `EnvDict` ([#24167]).
 
+  * Introduced the `empty` function, the functional pair to `empty!` which returns a new,
+    empty container ([#24390]).
+
+  * `similar(::Associative)` has been deprecated in favor of `empty(::Associative)`, and
+    `similar(::Associative, ::Pair{K, V})` has been deprecated in favour of
+    `empty(::Associative, K, V)` ([#24390]).
+
 Command-line option changes
 ---------------------------
 
diff --git a/base/abstractarray.jl b/base/abstractarray.jl
index 2c3dc59422da7..4b95a707251f6 100644
--- a/base/abstractarray.jl
+++ b/base/abstractarray.jl
@@ -566,6 +566,24 @@ indices of `A`.
 similar(f, shape::Tuple) = f(to_shape(shape))    # doesn't share well with Associative
 similar(f, dims::DimOrInd...) = similar(f, dims) # doesn't share well with Associative
 
+"""
+    empty(v::AbstractVector, [eltype])
+
+Create an empty vector similar to `v`, optionally changing the `eltype`.
+
+# Examples
+
+```jldoctest
+julia> empty([1.0, 2.0, 3.0])
+0-element Array{Float64,1}
+
+julia> empty([1.0, 2.0, 3.0], String)
+0-element Array{String,1}
+```
+"""
+empty(a::AbstractVector) = empty(a, eltype(a))
+empty(a::AbstractVector, ::Type{T}) where {T} = Vector{T}()
+
 ## from general iterable to any array
 
 function copy!(dest::AbstractArray, src)
diff --git a/base/associative.jl b/base/associative.jl
index a8a9be34760f6..1a9dcbbf0222a 100644
--- a/base/associative.jl
+++ b/base/associative.jl
@@ -147,10 +147,14 @@ Custom `Associative` subtypes may choose which specific associative type is best
 return for the given value type and indices, by specializing on the three-argument
 signature. The default is to return a `Dict`.
 """
-similar(a::Associative) = similar(a, valtype(a), keys(a))
+# v1.0: similar(a::Associative) = similar(a, valtype(a), keys(a))
 similar(a::Associative, ::Type{T}) where {T} = similar(a, T, keys(a))
 similar(a::Associative, inds) = similar(a, valtype(a), inds)
 
+# disambiguation
+similar(a::Associative, t::Tuple) = similar(a, eltype(a), t)
+similar(a::Associative, d::DimOrInd) = similar(a, eltype(a), d)
+
 """
     empty(a::Associative, [index_type=keytype(a)], [value_type=valtype(a)])
 
diff --git a/base/deprecated.jl b/base/deprecated.jl
index 94c8457d58312..1f9b3fb315e58 100644
--- a/base/deprecated.jl
+++ b/base/deprecated.jl
@@ -2073,6 +2073,7 @@ end
 @deprecate EnvHash EnvDict
 
 # issue #24019
+@deprecate similar(a::Associative) empty(a)
 @deprecate similar(a::Associative, ::Type{Pair{K,V}}) where {K, V} empty(a, K, V)
 
 # END 0.7 deprecations
diff --git a/base/tuple.jl b/base/tuple.jl
index 72f13b1b82aed..2572b8db3f393 100644
--- a/base/tuple.jl
+++ b/base/tuple.jl
@@ -328,3 +328,10 @@ any(x::Tuple{}) = false
 any(x::Tuple{Bool}) = x[1]
 any(x::Tuple{Bool, Bool}) = x[1]|x[2]
 any(x::Tuple{Bool, Bool, Bool}) = x[1]|x[2]|x[3]
+
+"""
+    empty(x::Tuple)
+
+Returns an empty tuple, `()`.
+"""
+empty(x::Tuple) = ()
diff --git a/test/abstractarray.jl b/test/abstractarray.jl
index a1d698d2ac933..2069b5b96fd69 100644
--- a/test/abstractarray.jl
+++ b/test/abstractarray.jl
@@ -870,5 +870,17 @@ end
     Base.convert(::Type{Array{T,n}}, a::Array{T,n}) where {T<:Number,n} = a
     Base.convert(::Type{Array{T,n}}, a::Array) where {T<:Number,n} =
         copy!(Array{T,n}(size(a)), a)
-    @test isa(similar(Dict(:a=>1, :b=>2.0), Pair{Union{},Union{}}), Dict{Union{}, Union{}})
-end
+    @test isa(empty(Dict(:a=>1, :b=>2.0), Union{}, Union{}), Dict{Union{}, Union{}})
+end
+
+@testset "empty" begin
+    @test isempty([])
+    v = [1, 2, 3]
+    v2 = empty(v)
+    v3 = empty(v, Float64)
+    @test !isempty(v)
+    empty!(v)
+    @test isempty(v)
+    @test isempty(v2::Vector{Int})
+    @test isempty(v3::Vector{Float64})
+end
\ No newline at end of file
diff --git a/test/dict.jl b/test/dict.jl
index 202fb54b78feb..91ce3696ea829 100644
--- a/test/dict.jl
+++ b/test/dict.jl
@@ -433,11 +433,11 @@ end
 @testset "similar" begin
     d = Dict(:a=>2, :b=>3)
 
-    d2 = similar(d)
-    @test d2 isa typeof(d)
-    @test length(keys(d2)) == 2
-    @test :a ∈ keys(d2)
-    @test :b ∈ keys(d2)
+    # v1.0: d2 = similar(d)
+    # v1.0: @test d2 isa typeof(d)
+    # v1.0: @test length(keys(d2)) == 2
+    # v1.0: @test :a ∈ keys(d2)
+    # v1.0: @test :b ∈ keys(d2)
 
     d3 = similar(d, Float64)
     @test d3 isa Dict{Symbol, Float64}
diff --git a/test/tuple.jl b/test/tuple.jl
index 438fe0e0d47ca..7fda7483c9572 100644
--- a/test/tuple.jl
+++ b/test/tuple.jl
@@ -83,6 +83,8 @@ end
         @test Tuple{Int,Vararg{Any}}.ninitialized == 1
         @test Tuple{Any,Any,Vararg{Any}}.ninitialized == 2
     end
+
+    @test empty((1, 2.0, "c")) === ()
 end
 
 @testset "size" begin