rename pop!(vector, idx, [default]) to popat! (#36070)

* rename pop!(vector, idx, [default]) to popat!

* popat! : explain what `default` is

(cherry picked from commit 0164101)

Author: rfourquet

base/array.jl

@@ -1153,13 +1153,44 @@ function pop!(a::Vector)
     return item
 end
 
-function pop!(a::Vector, i::Integer)
+"""
+    popat!(a::Vector, i::Integer, [default])
+
+Remove the item at the given `i` and return it. Subsequent items
+are shifted to fill the resulting gap.
+When `i` is not a valid index for `a`, return `default`, or throw an error if
+`default` is not specified.
+See also [`deleteat!`](@ref) and [`splice!`](@ref).
+
+!!! compat "Julia 1.5"
+    This function is available as of Julia 1.5.
+
+# Examples
+```jldoctest
+julia> a = [4, 3, 2, 1]; popat!(a, 2)
+3
+
+julia> a
+3-element Array{Int64,1}:
+ 4
+ 2
+ 1
+
+julia> popat!(a, 4, missing)
+missing
+
+julia> popat!(a, 4)
+ERROR: BoundsError: attempt to access 3-element Array{Int64,1} at index [4]
+[...]
+```
+"""
+function popat!(a::Vector, i::Integer)
     x = a[i]
     _deleteat!(a, i, 1)
     x
 end
 
-function pop!(a::Vector, i::Integer, default)
+function popat!(a::Vector, i::Integer, default)
     if 1 <= i <= length(a)
         x = @inbounds a[i]
         _deleteat!(a, i, 1)

base/dict.jl

@@ -576,9 +576,6 @@ end
 Delete and return the mapping for `key` if it exists in `collection`, otherwise return
 `default`, or throw an error if `default` is not specified.
 
-!!! compat "Julia 1.5"
-    For `collection::Vector`, this method requires at least Julia 1.5.
-
 # Examples
 ```jldoctest
 julia> d = Dict("a"=>1, "b"=>2, "c"=>3);

base/exports.jl

@@ -472,6 +472,7 @@ export
     append!,
     insert!,
     pop!,
+    popat!,
     prepend!,
     push!,
     resize!,

doc/src/base/collections.md

@@ -269,6 +269,7 @@ Partially implemented by:
 ```@docs
 Base.push!
 Base.pop!
+Base.popat!
 Base.pushfirst!
 Base.popfirst!
 Base.insert!

test/arrayops.jl

@@ -467,17 +467,17 @@ end
     @test_throws BoundsError insert!(v, 5, 5)
 end
 
-@testset "pop!(::Vector, i, [default])" begin
+@testset "popat!(::Vector, i, [default])" begin
     a = [1, 2, 3, 4]
-    @test_throws BoundsError pop!(a, 0)
-    @test pop!(a, 0, "default") == "default"
+    @test_throws BoundsError popat!(a, 0)
+    @test popat!(a, 0, "default") == "default"
     @test a == 1:4
-    @test_throws BoundsError pop!(a, 5)
-    @test pop!(a, 1) == 1
+    @test_throws BoundsError popat!(a, 5)
+    @test popat!(a, 1) == 1
     @test a == [2, 3, 4]
-    @test pop!(a, 2) == 3
+    @test popat!(a, 2) == 3
     @test a == [2, 4]
-    badpop() = @inbounds pop!([1], 2)
+    badpop() = @inbounds popat!([1], 2)
     @test_throws BoundsError badpop()
 end