ConstructionBase.jl

ConstructionBase

ConstructionBase is a very lightwight package, that provides primitive functions for construction of objects:

setproperties(obj::MyType, patch::NamedTuple)
constructorof(MyType)

These functions can be overloaded and doing so provides interoperability with the following packages:

• Flatten.jl
• Setfield.jl
• BangBang.jl

constructorof(T::Type) -> constructor

Return an object constructor that can be used to construct objects of type T from their field values. Typically constructor will be the type T with all parameters removed:

julia> using ConstructionBase

julia> struct T{A,B}
           a::A
           b::B
       end

julia> constructorof(T{Int,Int})
T

It is however not guaranteed, that constructor is a type at all:

julia> struct S
           a
           b
           checksum
           S(a,b) = new(a,b,a+b)
       end

julia> ConstructionBase.constructorof(::Type{<:S}) =
           (a, b, checksum=a+b) -> (@assert a+b == checksum; S(a,b))

julia> constructorof(S)(1,2)
S(1, 2, 3)

julia> constructorof(S)(1,2,4)
ERROR: AssertionError: a + b == checksum

Instead constructor can be any object that satisfies the following properties:

• It must be possible to reconstruct an object from its fields:

ctor = constructorof(typeof(obj))
@assert obj == ctor(fieldvalues(obj)...)
@assert typeof(obj) == typeof(ctor(fieldvalues(obj)...))

• The other direction should hold for as many values of args as possible:

ctor = constructorof(T)
fieldvalues(ctor(args...)) == args

For instance given a suitable parametric type it should be possible to change the type of its fields:

julia> struct T{A,B}
           a::A
           b::B
       end

julia> t = T(1,2)
T{Int64,Int64}(1, 2)

julia> constructorof(typeof(t))(1.0, 2)
T{Float64,Int64}(1.0, 2)

julia> constructorof(typeof(t))(10, 2)
T{Int64,Int64}(10, 2)

See also Tips section in the manual

setproperties(obj, patch::NamedTuple)

Return a copy of obj with attributes updates accoring to patch.

Examples

julia> using ConstructionBase

julia> struct S
           a
           b
           c
       end

julia> s = S(1,2,3)
S(1, 2, 3)

julia> setproperties(s, (a=10,c=4))
S(10, 2, 4)

julia> setproperties((a=1,c=2,b=3), (a=10,c=4))
(a = 10, c = 4, b = 3)

There is also a convenience method, which builds the patch argument from keywords:

setproperties(obj; kw...)

Examples

julia> using ConstructionBase

julia> struct S
           a
           b
           c
       end

julia> o = S(10, 2, 4)
S(10, 2, 4)

julia> setproperties(o, a="A", c="cc")
S("A", 2, "cc")

Implementation

For a custom type MyType, a method setproperties(obj::MyType, patch::NamedTuple) may be defined.

• Prefer to overload constructorof whenever makes sense (e.g., no getproperty method is defined). Default setproperties is defined in terms of constructorof.

• If getproperty is customized, it may be a good idea to define setproperties.

Specification

setproperties guarantees a couple of invariants. When overloading it, the user is responsible for ensuring them:

1. Purity: setproperties is supposed to have no side effects. In particular setproperties(obj, patch::NamedTuple) may not mutate obj.
2. Relation to propertynames and fieldnames: setproperties relates to propertynames and getproperty, not to fieldnames and getfield. This means that any subset p₁, p₂, ..., pₙ of propertynames(obj) is a valid set of properties, with respect to which the lens laws below must hold.
3. setproperties should satisfy the lens laws:

For any valid set of properties p₁, p₂, ..., pₙ, following equalities must hold:

• You get what you set.

let obj′ = setproperties(obj, ($p₁=v₁, $p₂=v₂, ..., $pₙ=vₙ))
    @assert obj′.$p₁ == v₁
    @assert obj′.$p₂ == v₂
    ...
    @assert obj′.$pₙ == vₙ
end

• Setting what was already there changes nothing:

@assert setproperties(obj, ($p₁=obj.$p₁, $p₂=obj.$p₂, ..., $pₙ=obj.$pₙ)) == obj

• The last set wins:

let obj′ = setproperties(obj, ($p₁=v₁, $p₂=v₂, ..., $pₙ=vₙ)),
    obj′′ = setproperties(obj′, ($p₁=w₁, $p₂=w₂, ..., $pₙ=wₙ))
    @assert obj′′.$p₁ == w₁
    @assert obj′′.$p₂ == w₂
    ...
    @assert obj′′.$pₙ == wₙ
end