add replace & replace! for collections

base/exports.jl

@@ -748,6 +748,7 @@ export
  randstring,
  repeat,
  replace,
+ replace!,
  repr,
  reverseind,
  rpad,

base/set.jl

@@ -474,3 +474,249 @@ end
 
 convert(::Type{Set{T}}, s::Set{T}) where {T} = s
 convert(::Type{Set{T}}, x::Set) where {T} = Set{T}(x)
+
+
+
+## replace/replace! ##
+
+"""
+ replace!(A, old_new::Pair...; [count::Integer])
+
+For each pair `old=>new` in `old_new`, replace all occurrences
+of `old` in collection `A` by `new`.
+If `count` is specified, then replace at most `count` occurrences in total.
+See also [`replace`](@ref replace(A, old_new::Pair...)).
+
+# Examples
+```jldoctest
+julia> replace!([1, 2, 1, 3], 1=>0, 2=>4, count=2)
+4-element Array{Int64,1}:
+ 0
+ 4
+ 1
+ 3
+
+julia> replace!(Set([1, 2, 3]), 1=>0)
+Set([0, 2, 3])
+```
+"""
+replace!(A, old_new::Pair...; count::Integer=typemax(Int)) = _replace!(A, eltype(A), count, old_new)
+
+# we use this wrapper because using directly eltype(A) as the type
+# parameter below for Some degrades performance
+function _replace!(A, ::Type{K}, count::Integer, old_new::Tuple{Vararg{Pair}}) where K
+ @inline function prednew(x)
+ for o_n in old_new
+ first(o_n) == x && return Some{K}(last(o_n))
+ end
+ end
+ replace!(prednew, A, count=count)
+end
+
+"""
+ replace!(pred::Function, A, new; [count::Integer])
+
+Replace all occurrences `x` in collection `A` for which `pred(x)` is true
+by `new`.
+
+# Examples
+```jldoctest
+julia> A = [1, 2, 3, 1];
+
+julia> replace!(isodd, A, 0, count=2)
+4-element Array{Int64,1}:
+ 0
+ 2
+ 0
+ 1
+```
+"""
+replace!(pred::Callable, A, new; count::Integer=typemax(Int)) =
+ replace!(x -> if pred(x) Some(new) end, A, count=count)
+
+"""
+ replace!(prednew::Function, A; [count::Integer])
+
+For each value `x` in `A`, `prednew(x)` is called and must
+return either `nothing`, in which case no replacement occurs,
+or a value, possibly wrapped as a [`Some`](@ref) object, which
+will be used as a replacement for `x`.
+
+# Examples
+```jldoctest
+julia> replace!(x -> isodd(x) ? 2x : nothing, [1, 2, 3, 4])
+4-element Array{Int64,1}:
+ 2
+ 2
+ 6
+ 4
+
+julia> replace!(Union{Int,Void}[0, 1, 2, nothing, 4], count=2) do x
+ x !== nothing && iseven(x) ? Some(nothing) : nothing
+ end
+5-element Array{Union{Void,Int64},1}:
+ nothing
+ 1
+ nothing
+ nothing
+ 4
+
+julia> replace!(Dict(1=>2, 3=>4)) do kv
+ if first(kv) < 3; first(kv)=>3 end
+ end
+Dict{Int64,Int64} with 2 entries:
+ 3 => 4
+ 1 => 3
+```
+
+!!! note
+ When `A` is an `AbstractDict` or `AbstractSet` collection, if
+ there are collisions among old and newly created keys, the result
+ depends on the iteration order (which can be undefined).
+ For example, the following may appear unexpected:
+
+```jldoctest
+julia> replace!(x->2x, Set([3, 6]))
+Set([12])
+```
+"""
+replace!(prednew::Callable, A; count::Integer=typemax(Int)) = replace!(prednew, A, count=count)
+
+replace(prednew::Callable, A; count::Integer=typemax(Int)) =
+ replace(prednew, A, count=clamp(count, typemin(Int), typemax(Int)) % Int)
+
+
+"""
+ replace(A, old_new::Pair...; [count::Integer])
+
+Return a copy of collection `A` where, for each pair `old=>new` in `old_new`,
+all occurrences of `old` are replaced by `new`.
+If `count` is specified, then replace at most `count` occurrences in total.
+See also [`replace!`](@ref).
+
+# Examples
+```jldoctest
+julia> replace([1, 2, 1, 3], 1=>0, 2=>4, count=2)
+4-element Array{Int64,1}:
+ 0
+ 4
+ 1
+ 3
+```
+"""
+replace(A, old_new::Pair...; count::Integer=typemax(Int)) =
+ _replace!(copy(A), eltype(A), count, old_new)
+
+"""
+ replace(pred::Function, A, new; [count::Integer])
+
+Return a copy of collection `A` where all occurrences `x` for which
+`pred(x)` is true are replaced by `new`.
+
+# Examples
+```jldoctest
+julia> replace(isodd, [1, 2, 3, 1], 0, count=2)
+4-element Array{Int64,1}:
+ 0
+ 2
+ 0
+ 1
+```
+"""
+replace(pred::Callable, A, new; count::Integer=typemax(Int)) =
+ replace!(x -> if pred(x) Some(new) end, copy(A), count=count)
+
+"""
+ replace(prednew::Function, A; [count::Integer])
+
+Return a copy of `A` where for each value `x` in `A`, `prednew(x)` is called
+and must return either `nothing`, in which case no replacement occurs,
+or a value, possibly wrapped as a [`Some`](@ref) object, which
+will be used as a replacement for `x`.
+
+# Examples
+```jldoctest
+julia> replace(x -> isodd(x) ? 2x : nothing, [1, 2, 3, 4])
+4-element Array{Int64,1}:
+ 2
+ 2
+ 6
+ 4
+
+julia> replace(Union{Int,Void}[0, 1, 2, nothing, 4], count=2) do x
+ x !== nothing && iseven(x) ? Some(nothing) : nothing
+ end
+5-element Array{Union{Void,Int64},1}:
+ nothing
+ 1
+ nothing
+ nothing
+ 4
+
+julia> replace(Dict(1=>2, 3=>4)) do kv
+ if first(kv) < 3; first(kv)=>3 end
+ end
+Dict{Int64,Int64} with 2 entries:
+ 3 => 4
+ 1 => 3
+```
+"""
+replace(prednew::Callable, A; count::Integer=typemax(Int)) = replace!(prednew, copy(A), count=count)
+
+# Handle ambiguities
+replace!(a::Callable, b::Pair; count::Integer=-1) = throw(MethodError(replace!, (a, b)))
+replace!(a::Callable, b::Pair, c::Pair; count::Integer=-1) = throw(MethodError(replace!, (a, b, c)))
+replace(a::Callable, b::Pair; count::Integer=-1) = throw(MethodError(replace, (a, b)))
+replace(a::Callable, b::Pair, c::Pair; count::Integer=-1) = throw(MethodError(replace, (a, b, c)))
+replace(a::AbstractString, b::Pair, c::Pair) = throw(MethodError(replace, (a, b, c)))
+
+
+### replace! for AbstractDict/AbstractSet
+
+askey(k, ::AbstractDict) = k.first
+askey(k, ::AbstractSet) = k
+
+function _replace_update_dict!(repl::Vector{<:Pair}, x, y::Some)
+ push!(repl, x => y.value)
+ true
+end
+
+_replace_update_dict!(repl::Vector{<:Pair}, x, ::Void) = false
+_replace_update_dict!(repl::Vector{<:Pair}, x, y) = _replace_update_dict!(repl, x, Some(y))
+
+function replace!(prednew::Callable, A::Union{AbstractDict,AbstractSet}; count::Int=typemax(Int))
+ count < 0 && throw(DomainError(count, "`count` must not be negative"))
+ count == 0 && return A
+ repl = Pair{eltype(A),eltype(A)}[]
+ c = 0
+ for x in A
+ c += _replace_update_dict!(repl, x, prednew(x))
+ c == count && break
+ end
+ for oldnew in repl
+ pop!(A, askey(first(oldnew), A))
+ push!(A, last(oldnew))
+ end
+ A
+end
+
+### AbstractArray
+
+function _replace_update!(A::AbstractArray, i::Integer, y::Some)
+ @inbounds A[i] = y.value
+ true
+end
+
+_replace_update!(A::AbstractArray, i::Integer, ::Void) = false
+_replace_update!(A::AbstractArray, i::Integer, y) = _replace_update!(A, i, Some(y))
+
+function replace!(prednew::Callable, A::AbstractArray; count::Int=typemax(Int))
+ count < 0 && throw(DomainError(count, "`count` must not be negative"))
+ count == 0 && return A
+ c = 0
+ for i in eachindex(A)
+ c += _replace_update!(A, i, prednew(A[i]))
+ c == count && break
+ end
+ A
+end

base/sysimg.jl

@@ -207,6 +207,9 @@ if !isdefined(Core, :Inference)
  Core.atdoc!(CoreDocs.docm)
 end
 
+# Some type
+include("some.jl")
+
 include("dict.jl")
 include("set.jl")
 include("iterators.jl")
@@ -259,9 +262,6 @@ include("multidimensional.jl")
 include("permuteddimsarray.jl")
 using .PermutedDimsArrays
 
-# Some type
-include("some.jl")
-
 include("broadcast.jl")
 using .Broadcast
 

doc/src/stdlib/collections.md

@@ -133,6 +133,10 @@ Base.collect(::Type, ::Any)
 Base.issubset(::Any, ::Any)
 Base.filter
 Base.filter!
+Base.replace(::Any, ::Pair...)
+Base.replace(::Base.Callable, ::Any, ::Any)
+Base.replace(::Base.Callable, ::Any)
+Base.replace!
 ```
 
 ## Indexable Collections

doc/src/stdlib/strings.md

@@ -38,7 +38,7 @@ Base.searchindex
 Base.rsearchindex
 Base.contains(::AbstractString, ::AbstractString)
 Base.reverse(::Union{String,SubString{String}})
-Base.replace
+Base.replace(s::AbstractString, pat, f)
 Base.split
 Base.rsplit
 Base.strip

test/sets.jl

@@ -344,3 +344,46 @@ end
  @test typeof(cssset) == Set{String}
  @test cssset == Set(["foo", "bar"])
 end
+
+@testset "replace! & replace" begin
+ maybe1(v, p) = if p Some(v) end
+ maybe2(v, p) = if p v end
+ for maybe = (maybe1, maybe2)
+ a = [1, 2, 3, 1]
+ @test replace(x->maybe(2x, iseven(x)), a) == [1, 4, 3, 1]
+ @test replace!(x->maybe(2x, iseven(x)), a) === a
+ @test a == [1, 4, 3, 1]
+ @test replace(a, 1=>0) == [0, 4, 3, 0]
+ @test replace(a, 1=>0, count=1) == [0, 4, 3, 1]
+ @test replace!(a, 1=>2) === a
+ @test a == [2, 4, 3, 2]
+
+ d = Dict(1=>2, 3=>4)
+ @test replace(x->x.first > 2, d, 0=>0) == Dict(1=>2, 0=>0)
+ @test replace!(x->maybe(x.first=>2*x.second, x.first > 2), d) === d
+ @test d == Dict(1=>2, 3=>8)
+ @test replace(d, (3=>8)=>(0=>0)) == Dict(1=>2, 0=>0)
+ @test replace!(d, (3=>8)=>(2=>2)) === d
+ @test d == Dict(1=>2, 2=>2)
+ @test replace(x->x.second == 2, d, 0=>0, count=1) in [Dict(1=>2, 0=>0),
+ Dict(2=>2, 0=>0)]
+
+ s = Set([1, 2, 3])
+ @test replace(x->maybe(2x, x>1), s) == Set([1, 4, 6])
+ @test replace(x->maybe(2x, x>1), s, count=1) in [Set([1, 4, 3]), Set([1, 2, 6])]
+ @test replace(s, 1=>4) == Set([2, 3, 4])
+ @test replace!(s, 1=>2) === s
+ @test s == Set([2, 3])
+
+ @test replace([1, 2], 1=>0, 2=>0, count=0) == [1, 2] # count=0 --> no replacements
+ end
+ # test Some(nothing)
+ a = [1, 2, nothing, 4]
+ @test replace(x -> x === nothing ? 0 : Some(nothing), a) == [nothing, nothing, 0, nothing]
+ @test replace(x -> x === nothing ? 0 : nothing, a) == [1, 2, 0, 4]
+ @test replace!(x -> x !== nothing ? Some(nothing) : nothing, a) == [nothing, nothing, nothing, nothing]
+ s = Set([1, 2, nothing, 4])
+ @test replace(x -> x === nothing ? 0 : Some(nothing), s) == Set([0, nothing])
+ @test replace(x -> x === nothing ? 0 : nothing, s) == Set([1, 2, 0, 4])
+ @test replace(x -> x !== nothing ? Some(nothing) : nothing, s) == Set([nothing])
+end