From e5486b375483bb70bb267ff914ed801e22042981 Mon Sep 17 00:00:00 2001
From: Fredrik Ekre <fredrik.ekre@chalmers.se>
Date: Fri, 22 Sep 2017 13:24:46 +0200
Subject: [PATCH] deprecate/remove gradient from base, fix #16113

---
 NEWS.md                  |  2 ++
 base/deprecated.jl       | 37 +++++++++++++++++++++++++++++++++++++
 base/exports.jl          |  1 -
 base/linalg/bitarray.jl  |  9 ---------
 base/linalg/dense.jl     | 17 -----------------
 base/linalg/generic.jl   | 25 -------------------------
 base/linalg/linalg.jl    |  1 -
 doc/src/stdlib/arrays.md |  1 -
 test/bitarray.jl         |  4 ----
 test/linalg/dense.jl     | 14 --------------
 10 files changed, 39 insertions(+), 72 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index bc0a7e72ed4b9..04895e1674b09 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -479,6 +479,8 @@ Deprecated or removed
     `prompt_if_incorrect` argument are deprecated. Instead, prompting behavior is controlled using
     the `allow_prompt` keyword in the `LibGit2.CredentialPayload` constructor ([#23690]).
 
+  * `gradient` is deprecated and will be removed in the next release ([#23816]).
+
   * The timing functions `tic`, `toc`, and `toq` are deprecated in favor of `@time` and `@elapsed`
     ([#17046]).
 
diff --git a/base/deprecated.jl b/base/deprecated.jl
index 17578096c5fbd..d8362b23a9eb1 100644
--- a/base/deprecated.jl
+++ b/base/deprecated.jl
@@ -1868,6 +1868,43 @@ function toc()
     return t
 end
 
+# PR #23816: deprecation of gradient
+export gradient
+@eval Base.LinAlg begin
+    export gradient
+
+    function gradient(args...)
+        Base.depwarn("gradient is deprecated and will be removed in the next release.", :gradient)
+        return _gradient(args...)
+    end
+
+    _gradient(F::BitVector) = _gradient(Array(F))
+    _gradient(F::BitVector, h::Real) = _gradient(Array(F), h)
+    _gradient(F::Vector, h::BitVector) = _gradient(F, Array(h))
+    _gradient(F::BitVector, h::Vector) = _gradient(Array(F), h)
+    _gradient(F::BitVector, h::BitVector) = _gradient(Array(F), Array(h))
+
+    function _gradient(F::AbstractVector, h::Vector)
+        n = length(F)
+        T = typeof(oneunit(eltype(F))/oneunit(eltype(h)))
+        g = similar(F, T)
+        if n == 1
+            g[1] = zero(T)
+        elseif n > 1
+            g[1] = (F[2] - F[1]) / (h[2] - h[1])
+            g[n] = (F[n] - F[n-1]) / (h[end] - h[end-1])
+            if n > 2
+                h = h[3:n] - h[1:n-2]
+                g[2:n-1] = (F[3:n] - F[1:n-2]) ./ h
+            end
+        end
+        g
+    end
+
+    _gradient(F::AbstractVector) = _gradient(F, [1:length(F);])
+    _gradient(F::AbstractVector, h::Real) = _gradient(F, [h*(1:length(F));])
+end
+
 @noinline function getaddrinfo(callback::Function, host::AbstractString)
     depwarn("getaddrinfo with a callback function is deprecated, wrap code in @async instead for deferred execution", :getaddrinfo)
     @async begin
diff --git a/base/exports.jl b/base/exports.jl
index 57e0a174cd491..ca34c71c12f38 100644
--- a/base/exports.jl
+++ b/base/exports.jl
@@ -458,7 +458,6 @@ export
     findnz,
     first,
     flipdim,
-    gradient,
     hcat,
     hvcat,
     ind2sub,
diff --git a/base/linalg/bitarray.jl b/base/linalg/bitarray.jl
index ec5b391c4a391..4c6981cb561b5 100644
--- a/base/linalg/bitarray.jl
+++ b/base/linalg/bitarray.jl
@@ -74,15 +74,6 @@ function tril(B::BitMatrix, k::Integer=0)
     A
 end
 
-## diff and gradient
-
-# TODO: this could be improved (is it worth it?)
-gradient(F::BitVector) = gradient(Array(F))
-gradient(F::BitVector, h::Real) = gradient(Array(F), h)
-gradient(F::Vector, h::BitVector) = gradient(F, Array(h))
-gradient(F::BitVector, h::Vector) = gradient(Array(F), h)
-gradient(F::BitVector, h::BitVector) = gradient(Array(F), Array(h))
-
 ## diag and related
 
 function diag(B::BitMatrix)
diff --git a/base/linalg/dense.jl b/base/linalg/dense.jl
index 4cd1819ebde2d..a7945f2a6df27 100644
--- a/base/linalg/dense.jl
+++ b/base/linalg/dense.jl
@@ -215,23 +215,6 @@ function tril!(M::AbstractMatrix, k::Integer)
 end
 tril(M::Matrix, k::Integer) = tril!(copy(M), k)
 
-function gradient(F::AbstractVector, h::Vector)
-    n = length(F)
-    T = typeof(oneunit(eltype(F))/oneunit(eltype(h)))
-    g = similar(F, T)
-    if n == 1
-        g[1] = zero(T)
-    elseif n > 1
-        g[1] = (F[2] - F[1]) / (h[2] - h[1])
-        g[n] = (F[n] - F[n-1]) / (h[end] - h[end-1])
-        if n > 2
-            h = h[3:n] - h[1:n-2]
-            g[2:n-1] = (F[3:n] - F[1:n-2]) ./ h
-        end
-    end
-    g
-end
-
 function diagind(m::Integer, n::Integer, k::Integer=0)
     if !(-m <= k <= n)
         throw(ArgumentError(string("requested diagonal, $k, must be at least $(-m) and ",
diff --git a/base/linalg/generic.jl b/base/linalg/generic.jl
index 23c5a0b3b5b79..65a167044a17a 100644
--- a/base/linalg/generic.jl
+++ b/base/linalg/generic.jl
@@ -271,33 +271,8 @@ function diff(A::AbstractMatrix, dim::Integer=1)
     end
 end
 
-
-gradient(F::AbstractVector) = gradient(F, [1:length(F);])
-
-"""
-    gradient(F::AbstractVector, [h::Real])
-
-Compute differences along vector `F`, using `h` as the spacing between points. The default
-spacing is one.
-
-# Examples
-```jldoctest
-julia> a = [2,4,6,8];
-
-julia> gradient(a)
-4-element Array{Float64,1}:
- 2.0
- 2.0
- 2.0
- 2.0
-```
-"""
-gradient(F::AbstractVector, h::Real) = gradient(F, [h*(1:length(F));])
-
 diag(A::AbstractVector) = throw(ArgumentError("use diagm instead of diag to construct a diagonal matrix"))
 
-#diagm(v::AbstractVecOrMat{T}) where {T}
-
 ###########################################################################################
 # Inner products and norms
 
diff --git a/base/linalg/linalg.jl b/base/linalg/linalg.jl
index cea5d780a7710..cf2d3c9e04e12 100644
--- a/base/linalg/linalg.jl
+++ b/base/linalg/linalg.jl
@@ -84,7 +84,6 @@ export
     eye,
     factorize,
     givens,
-    gradient,
     hessfact,
     hessfact!,
     isdiag,
diff --git a/doc/src/stdlib/arrays.md b/doc/src/stdlib/arrays.md
index 1f6a8d0c4f7e4..abdcc1c865fb1 100644
--- a/doc/src/stdlib/arrays.md
+++ b/doc/src/stdlib/arrays.md
@@ -140,7 +140,6 @@ Base.cumsum!
 Base.cumsum_kbn
 Base.crc32c
 Base.LinAlg.diff
-Base.LinAlg.gradient
 Base.repeat(::AbstractArray)
 Base.rot180
 Base.rotl90
diff --git a/test/bitarray.jl b/test/bitarray.jl
index 31f7d54252235..55101550a2c5a 100644
--- a/test/bitarray.jl
+++ b/test/bitarray.jl
@@ -1401,10 +1401,6 @@ timesofar("cat")
     @check_bit_operation svd(b1)
     @check_bit_operation qr(b1)
 
-    b1 = bitrand(v1)
-    @check_bit_operation gradient(b1)
-    @check_bit_operation gradient(b1, 1.0)
-
     b1 = bitrand(v1)
     @check_bit_operation diagm(b1) BitMatrix
 
diff --git a/test/linalg/dense.jl b/test/linalg/dense.jl
index 82d9818260c80..a0d755432ccd6 100644
--- a/test/linalg/dense.jl
+++ b/test/linalg/dense.jl
@@ -156,20 +156,6 @@ end # for eltya
     end
 end
 
-@testset "Test gradient for $elty" for elty in (Int32, Int64, Float32, Float64, Complex64, Complex128)
-    if elty <: Real
-        x = convert(Vector{elty}, [1:3;])
-        g = ones(elty, 3)
-    else
-        x = convert(Vector{elty}, complex.([1:3;], [1:3;]))
-        g = convert(Vector{elty}, complex.(ones(3), ones(3)))
-    end
-    xsub = view(x, 1:size(x, 1))
-    @test gradient(x) ≈ g
-    @test gradient(xsub) ≈ g # Test gradient on SubArray
-    @test gradient(ones(elty,1)) == zeros(elty,1)
-end
-
 @testset "Tests norms" begin
     nnorm = 10
     mmat = 10