BangBang

BangBang.jl implements functions whose name ends with !!. Those functions provide a uniform interface for mutable and immutable data structures. Furthermore, those functions implement the "widening" fallback for the case when the usual mutating function does not work (e.g., push!!(Int[], 1.5) creates a new array Float64[1.5]).

See the supported functions in the documentation

broadcast_inplace!!(f, inputoutput, As...) -> inputoutput′

A mutate-or-widen version of inputoutput .= f.(inputoutput, As...).

__append!!__(dest::CustomType, src) -> dest′

This is an overload interface for append!!. This function must dispatch on the first argument and implemented by the owner of the type of the first argument.

__appendto!!__(dest, src::CustomType) -> dest′

This is an overload interface for append!!. This function must dispatch on the second argument and implemented by the owner of the type of second first argument. This function is used when there is no specific implementation for __append!!__ is found.

add!!(A, B) -> A′

A .+= B if possible; otherwise return A .+ B.

Examples

julia> using BangBang: add!!

julia> add!!((1,), (2,))
(3,)

julia> add!!([1], [2])
1-element Vector{Int64}:
 3

append!!(dest, src) -> dest′

Append items in src to dest. Mutate dest if possible.

This function "owns" dest but not src; i.e., returned value dest′ does not alias src. For example, append!!(Empty(Vector), src) shallow-copies src instead of returning src as-is.

See also push!!.

Examples

julia> using BangBang

julia> append!!((1, 2), (3, 4))
(1, 2, 3, 4)

julia> append!!([1, 2], (3, 4))
4-element Vector{Int64}:
 1
 2
 3
 4

julia> using StaticArrays: SVector

julia> @assert append!!(SVector(1, 2), (3, 4)) === SVector(1, 2, 3, 4)

julia> using DataFrames: DataFrame

julia> @assert append!!(DataFrame(a=[1], b=[2]), [(a=3.0, b=4.0)]) ==
           DataFrame(a=[1.0, 3.0], b=[2.0, 4.0])

julia> using StructArrays: StructVector

julia> @assert append!!(StructVector(a=[1], b=[2]), [(a=3.5, b=4.5)]) ==
           StructVector(a=[1.0, 3.5], b=[2.0, 4.5])

julia> using TypedTables: Table

julia> @assert append!!(Table(a=[1], b=[2]), [(a=3.5, b=4.5)]) ==
           Table(a=[1.0, 3.5], b=[2.0, 4.5])

append!! does not own the second argument:

julia> xs = [1, 2, 3];

julia> ys = append!!(Empty(Vector), xs)
3-element Vector{Int64}:
 1
 2
 3

julia> ys === xs
false

broadcast!!(f, dest, As...) -> dest′

A mutate-or-widen version of dest .= f.(As...).

collector(data::AbstractVector, unsafe::Val = Val(false)) -> c::AbstractCollector
collector(ElType::Type = Union{}) -> c::AbstractCollector

Create a "collector" c that can be used to collect elements; i.e., it supports append!! and push!!. Appending and pushing elements to a collector are more efficient than doing these operations directly to a vector.

Use finish!(c) to get the collected data as a vector.

push!! on the collector can be further optimized by passing Val(true) to the second unsafe argument. This is valid to use only if the number of elements appended to c is less than or equal to length(data).

Examples

julia> using BangBang

julia> c = collector()
       c = push!!(c, 1)
       c = push!!(c, 0.5)
       finish!(c)
2-element Vector{Float64}:
 1.0
 0.5

julia> finish!(append!!(collector(), (x for x in Any[1, 2.0, 3im])))
3-element Vector{ComplexF64}:
 1.0 + 0.0im
 2.0 + 0.0im
 0.0 + 3.0im

julia> finish!(append!!(collector(Vector{Float64}(undef, 10), Val(true)), [1, 2, 3]))
3-element Vector{Float64}:
 1.0
 2.0
 3.0

delete!!(assoc, key) -> assoc′

Examples

julia> using BangBang

julia> delete!!((a=1, b=2), :a)
(b = 2,)

julia> delete!!(Dict(:a=>1, :b=>2), :a)
Dict{Symbol, Int64} with 1 entry:
  :b => 2

deleteat!!(assoc, i) -> assoc′

Examples

julia> using BangBang

julia> deleteat!!((1, 2, 3), 2)
(1, 3)

julia> deleteat!!([1, 2, 3], 2)
2-element Vector{Int64}:
 1
 3

julia> using StaticArrays: SVector

julia> @assert deleteat!!(SVector(1, 2, 3), 2) === SVector(1, 3)

empty!!(collection) -> collection′

Examples

julia> using BangBang

julia> empty!!((1, 2, 3))
()

julia> empty!!((a=1, b=2, c=3))
NamedTuple()

julia> xs = [1, 2, 3];

julia> empty!!(xs)
Int64[]

julia> xs
Int64[]

julia> using StaticArrays: SVector

julia> @assert empty!!(SVector(1, 2)) == SVector{0, Int}()

finish!(c::AbstractCollector) -> data::AbstractVector

Extract the data collected in the collector c.

See collector.

implements(f!, x) :: Bool

true if in-place function f! can mutate x.

Examples

julia> using BangBang: implements

julia> implements(push!, Vector)
true

julia> implements(push!, [])  # works with instances, too
true

julia> implements(push!, Tuple)
false

julia> using StaticArrays

julia> implements(push!, SVector)
false

julia> implements(setindex!, SVector)
false

julia> implements(push!, MVector)
false

julia> implements(setindex!, MVector)
true

intersect!!(setlike, others...) -> setlike′

Return the set of elements in setlike and in all the collections others. Mutate setlike if possible.

This function "owns" setlike but not others; i.e., returned value setlike′ does not alias any of others. For example, other = Set([1]); intersect!!(Set([1, 2]), other) does not return other as-is.

Examples

julia> using BangBang

julia> xs = Set([1, 2]);

julia> ys = intersect!!(xs, [1]);  # mutates `xs` as it's possible

julia> ys == Set([1])
true

julia> ys === xs  # `xs` is returned
true

lmul!!(A, B) -> B′

materialize!!(dest, x)

julia> using BangBang

julia> using Base.Broadcast: instantiate, broadcasted

julia> bc = instantiate(broadcasted(+, [1.0, 1.5, 2.0], 1));

julia> xs = zeros(Float64, 3);

julia> ys = materialize!!(xs, bc)
3-element Vector{Float64}:
 2.0
 2.5
 3.0

julia> xs === ys  # mutated
true

julia> xs = Vector{Union{}}(undef, 3);

julia> ys = materialize!!(xs, bc)
3-element Vector{Float64}:
 2.0
 2.5
 3.0

julia> xs === ys
false

may(mutate!, args...)

Call mutate!(args...) if possible; fallback to the out-of-place version if not.

merge!!(dictlike, others...) -> dictlike′
merge!!(combine, dictlike, others...) -> dictlike′

Merge key-value pairs from others to dictlike. Mutate dictlike if possible.

This function "owns" dictlike but not others; i.e., returned value dictlike′ does not alias any of others. For example, merge!!(Empty(Dict), other) shallow-copies other instead of returning other as-is.

Method merge!!(combine::Union{Function,Type}, args...) as an alias of mergewith!!(combine, args...) is still available for backward compatibility.

See also mergewith!!.

Examples

julia> using BangBang

julia> merge!!(Dict(:a => 1), Dict(:b => 0.5))
Dict{Symbol, Float64} with 2 entries:
  :a => 1.0
  :b => 0.5

julia> merge!!((a = 1,), Dict(:b => 0.5))
(a = 1, b = 0.5)

julia> merge!!(+, Dict(:a => 1), Dict(:a => 0.5))
Dict{Symbol, Float64} with 1 entry:
  :a => 1.5

merge!! does not own the second argument:

julia> xs = Dict(:a => 1, :b => 2, :c => 3);

julia> ys = merge!!(Empty(Dict), xs)
Dict{Symbol, Int64} with 3 entries:
  :a => 1
  :b => 2
  :c => 3

julia> ys === xs
false

mergewith!!(combine, dictlike, others...) -> dictlike′
mergewith!!(combine)

Like merge!!(combine, dictlike, others...) but combine does not have to be a Function.

This function "owns" dictlike but not others. See merge!! for more details.

The curried form mergewith!!(combine) returns the function (args...) -> mergewith!!(combine, args...).

mul!!(C, A, B, [α, β]) -> C′

pop!!(sequence) -> (sequence′, value)
pop!!(assoc, key) -> (assoc′, value)
pop!!(assoc, key, default) -> (assoc′, value)

Examples

julia> using BangBang

julia> pop!!([0, 1])
([0], 1)

julia> pop!!((0, 1))
((0,), 1)

julia> pop!!(Dict(:a => 1), :a)
(Dict{Symbol, Int64}(), 1)

julia> pop!!((a=1,), :a)
(NamedTuple(), 1)

julia> using StaticArrays: SVector

julia> @assert pop!!(SVector(1, 2)) === (SVector(1), 2)

popfirst!!(sequence) -> (sequence′, value)

Examples

julia> using BangBang

julia> popfirst!!([0, 1])
([1], 0)

julia> popfirst!!((0, 1))
((1,), 0)

julia> popfirst!!((a=0, b=1))
((b = 1,), 0)

julia> using StaticArrays: SVector

julia> @assert popfirst!!(SVector(1, 2)) === (SVector(2), 1)

possible(f!, args...) :: Bool

Check if f!(args...) is possible.

Examples

julia> using BangBang: possible

julia> possible(push!, Int[], 1)
true

julia> possible(push!, Int[], 0.5)
false

push!!(collection, items...)

Push one or more items to collection. Create a copy of collection if it cannot be mutated or the element type does not match.

Examples

julia> using BangBang

julia> push!!((1, 2), 3)
(1, 2, 3)

julia> push!!([1, 2], 3)
3-element Vector{Int64}:
 1
 2
 3

julia> push!!([1, 2], 3.0)
3-element Vector{Float64}:
 1.0
 2.0
 3.0

julia> using StaticArrays: SVector

julia> @assert push!!(SVector(1, 2), 3.0) === SVector(1.0, 2.0, 3.0)

julia> using DataFrames: DataFrame

julia> @assert push!!(DataFrame(a=[1], b=[2]), (a=3.5, b=4.5)) ==
           DataFrame(a=[1.0, 3.5], b=[2.0, 4.5])

julia> using StructArrays: StructVector

julia> @assert push!!(StructVector(a=[1], b=[2]), (a=3.5, b=4.5)) ==
           StructVector(a=[1.0, 3.5], b=[2.0, 4.5])

julia> using TypedTables: Table

julia> @assert push!!(Table(a=[1], b=[2]), (a=3.5, b=4.5)) ==
           Table(a=[1.0, 3.5], b=[2.0, 4.5])

pushfirst!!(collection, items...)

Examples

julia> using BangBang

julia> pushfirst!!((1, 2), 3, 4)
(3, 4, 1, 2)

julia> pushfirst!!([1, 2], 3, 4)
4-element Vector{Int64}:
 3
 4
 1
 2

julia> pushfirst!!([1, 2], 3, 4.0)
4-element Vector{Float64}:
 3.0
 4.0
 1.0
 2.0

julia> using StaticArrays: SVector

julia> @assert pushfirst!!(SVector(1, 2), 3, 4) === SVector(3, 4, 1, 2)

resize!!(vector::AbstractVector, n::Integer) -> vector′

rmul!!(A, B) -> A′

setdiff!!(setlike, others...) -> setlike′

Return the set of elements in setlike but not in any of the collections others. Mutate setlike if possible.

This function "owns" setlike but not others; i.e., returned value setlike′ does not alias any of others. For example, other = Set([]); setdiff!!(Empty(Set), other) does not return other as-is.

Examples

julia> using BangBang

julia> xs = Set([1]);

julia> ys = setdiff!!(xs, [1]);  # mutates `xs` as it's possible

julia> ys == Set([])
true

julia> ys === xs  # `xs` is returned
true

setindex!!(collection, value, indices...) -> collection′

Examples

julia> using BangBang

julia> setindex!!((1, 2), 10.0, 1)
(10.0, 2)

julia> setindex!!([1, 2], 10.0, 1)
2-element Vector{Float64}:
 10.0
  2.0

julia> using StaticArrays: SVector

julia> @assert setindex!!(SVector(1, 2), 10.0, 1) == SVector(10.0, 2.0)

setproperties!!(value, patch::NamedTuple)
setproperties!!(value; patch...)

Examples

julia> using BangBang

julia> setproperties!!((a=1, b=2); b=3)
(a = 1, b = 3)

julia> struct Immutable
           a
           b
       end

julia> setproperties!!(Immutable(1, 2); b=3)
Immutable(1, 3)

julia> mutable struct Mutable{T, S}
           a::T
           b::S
       end

julia> s = Mutable(1, 2);

julia> setproperties!!(s; b=3)
Mutable{Int64, Int64}(1, 3)

julia> setproperties!!(s, b=4.0)
Mutable{Int64, Float64}(1, 4.0)

julia> s
Mutable{Int64, Int64}(1, 3)

setproperty!!(value, name::Symbol, x)

An alias of setproperties!!(value, (name=x,)).

splice!!(sequence, i, [replacement]) -> (sequence′, item)

Examples

julia> using BangBang

julia> splice!!([1, 2, 3], 2)
([1, 3], 2)

julia> splice!!((1, 2, 3), 2)
((1, 3), 2)

julia> using StaticArrays: SVector

julia> @assert splice!!(SVector(1, 2, 3), 2) === (SVector(1, 3), 2)

symdiff!!(setlike, others...) -> setlike′

Return the set of elements that occur an odd number of times in setlike and the others collections. Mutate setlike if possible.

This function "owns" setlike but not others; i.e., returned value setlike′ does not alias any of others. For example, symdiff!!(Empty(Set), other) shallow-copies other instead of returning other as-is.

Examples

julia> using BangBang

julia> xs = Set([1, 2]);

julia> ys = symdiff!!(xs, [2, 3]);  # mutates `xs` as it's possible

julia> ys == Set([1, 3])
true

julia> ys === xs  # `xs` is returned
true

union!!(setlike, others...) -> setlike′

Return the union of all sets in the arguments. Mutate setlike if possible.

This function "owns" setlike but not others; i.e., returned value setlike′ does not alias any of others. For example, union!!(Empty(Set), other) shallow-copies other instead of returning other as-is.

Examples

julia> using BangBang

julia> xs = Set([1]);

julia> ys = union!!(xs, Set([2]));  # mutates `xs` as it's possible

julia> ys == Set([1, 2])
true

julia> ys === xs  # `xs` is returned
true

julia> zs = union!!(xs, Set([0.5]));  # incompatible element type

julia> zs == Set([0.5, 1, 2])
true

julia> zs === xs  # a new set is returned
false

union!! does not own the second argument:

julia> xs = Set([1]);

julia> ys = union!!(Empty(Set), xs)
Set{Int64} with 1 element:
  1

julia> ys === xs
false

unique!!(set) -> set
unique!!(sequence) -> sequence′

@! expr

Convert all supported mutating calls to double bang equivalent.

Examples

julia> using BangBang

julia> @! push!(empty!((0, 1)), 2, 3)
(2, 3)

julia> y = [1, 2];

julia> @! y .= 2 .* y
       y
2-element Vector{Int64}:
 2
 4

julia> y = (1, 2);

julia> @! y .= 2 .* y
       y
(2, 4)

Empty(T)

Create a proxy of an empty container of type T.

This is a simple API for solving problems such as:

• There is no consistent way to create an empty container given its type.
• There is no consistent way to know that nothing was appended into the container in type-domain.

Internally, this function simply works by creating a singleton container (a container with one element) using singletonof when the first element is push!!'ed.

Examples

julia> using BangBang

julia> push!!(Empty(Vector), 1)
1-element Vector{Int64}:
 1

julia> append!!(Empty(Dict), (:a=>1, :b=>2))
Dict{Symbol, Int64} with 2 entries:
  :a => 1
  :b => 2

julia> using DataFrames: DataFrame

julia> @assert push!!(Empty(DataFrame), (a=1, b=2)) == DataFrame(a=[1], b=[2])

julia> using StructArrays: StructVector

julia> @assert push!!(Empty(StructVector), (a=1, b=2)) == StructVector(a=[1], b=[2])

julia> using TypedTables: Table

julia> @assert push!!(Empty(Table), (a=1, b=2)) == Table(a=[1], b=[2])

julia> using StaticArrays: SVector

julia> @assert push!!(Empty(SVector), 1) === SVector(1)

Empty(T) object is an iterable with length 0 and element type Union{}:

julia> collect(Empty(Vector))
Union{}[]

julia> length(Empty(Vector))
0

julia> eltype(typeof(Empty(Vector)))
Union{}

julia> Base.IteratorSize(Empty)
Base.HasLength()

julia> Base.IteratorEltype(Empty)
Base.HasEltype()

singletonof(::Type{T}, x) :: T
singletonof(::T, x) :: T

Create a singleton container of type T.

Examples

julia> using BangBang

julia> @assert singletonof(Vector, 1) == [1]

julia> @assert singletonof(Dict, :a => 1) == Dict(:a => 1)

julia> @assert singletonof(Set, 1) == Set([1])

julia> using StructArrays: StructVector

julia> @assert singletonof(StructVector, (a=1, b=2)) == StructVector(a=[1], b=[2])

julia> using TypedTables: Table

julia> @assert singletonof(Table, (a=1, b=2)) == Table(a=[1], b=[2])

julia> using StaticArrays: SArray, SVector

julia> @assert singletonof(SArray, 1) === SVector(1)

julia> @assert singletonof(SVector, 1) === SVector(1)

BangBang.Extras

BangBang APIs that have no counterparts in Base.

modify!!(f, dictlike, key) -> (dictlike′, ret)

Lookup and then update, insert or delete in one go. If supported (e.g., when dictlike isa Dict), it is done without re-computing the hash. Immutable containers like NamedTuple is also supported.

The callable f must accept a single argument of type Union{Some{valtype(dictlike)}, Nothing}. The value Some(dictlike[key]) is passed to f if haskey(dictlike, key); otherwise nothing is passed.

If f returns nothing, corresponding entry in the dictionary dictlike is removed. If f returns non-nothing value x, key => something(x) is inserted to dictlike (equivalent to dictlike[key] = something(x) but more efficient).

modify!! returns a 2-tuple (dictlike′, ret) where dictlike′ is an updated version of dictlike (which may be identical to dictlike) and ret is the returned value of f.

This API is inspired by Control.Lens.At of Haskell's lens library.

Examples

julia> using BangBang.Extras: modify!!

julia> dict = Dict("a" => 1);

julia> dict′, ret = modify!!(dict, "a") do val
           Some(something(val, 0) + 1)
       end;

julia> ret
Some(2)

julia> dict === dict′
true

julia> dict
Dict{String, Int64} with 1 entry:
  "a" => 2

julia> dict = Dict();

julia> modify!!(dict, "a") do val
           Some(something(val, 0) + 1)
       end;

julia> dict
Dict{Any, Any} with 1 entry:
  "a" => 1

julia> modify!!(_ -> nothing, dict, "a");

julia> dict
Dict{Any, Any}()

Discussion

• Add modify! function for lookup/update/insert/delete in one go by tkf · Pull Request #33758 · JuliaLang/julia
• Support adding to named tuples? · Issue #65 · jw3126/Setfield.jl

prefermutation(lens::Lens) :: Lens

See also @set!!.

@set!! assignment

Like Accessors.@set, but prefer mutation if possible.

Examples

julia> using BangBang

julia> mutable struct Mutable
           a
           b
       end

julia> x = orig = Mutable((x=Mutable(1, 2), y=3), 4);

julia> @set!! x.a.x.a = 10;

julia> @assert x.a.x.a == orig.a.x.a == 10