switch to component interface (#167)

* switch to _getfield interface

* fix tests

* fix pooledarray doctest

* _getfield cleanup

* update docstrings

* avoid fieldnames and fieldtypes

* rename to component

* rename fieldarrays to componens

* test edge case of lazyrows collection

* add fieldarrays deprecation

* test interoperability with typed tables

* typo

* update news

* unexport components

* only run ci on linux

Author: Pietro Vertechi

.github/workflows/CI.yml

@@ -20,8 +20,6 @@ jobs:
           - 'nightly'
         os:
           - ubuntu-latest
-          - windows-latest
-          - macos-latest
         arch:
           - x64
     steps:

NEWS.md

@@ -1,12 +1,21 @@
 # NEWS
 
+## Version 0.6.0
+
+### Breaking
+
+- Renamed `fieldarrays` to `StructArrays.components` [#167](https://github.com/JuliaArrays/StructArrays.jl/pull/167)
+- `getproperty` is no longer used to access fields of a struct. It is replaced by `StructArrays.component(x, i)` [#167](https://github.com/JuliaArrays/StructArrays.jl/pull/167). This is only relevant for structs with custom layout.
+- Inner constructors are bypassed on `getindex` [#145](https://github.com/JuliaArrays/StructArrays.jl/pull/136)
+- Broadcast on `StructArray`s now returns a `StructArray` [#136](https://github.com/JuliaArrays/StructArrays.jl/pull/136)
+
 ## Version 0.4.0
 
 ### Breaking
 
 - `fieldarrays` now returns a tuple of arrays for a `StructArray{<:Tuple}`
 - `push!` now only works if the `StructArray` and the element have the same propertynames
-- the special constructor `StructArray(first_col => last_col)` is no longer supported
+- The special constructor `StructArray(first_col => last_col)` is no longer supported
 
 ## Version 0.2.0
 
@@ -19,4 +28,3 @@
 
 - Added `collect_structarray` function to collect an iterable of structs into a `StructArray` without having to allocate an array of structs
 - `StructArray{T}(undef, dims)` and `StructArray(v::AbstractArray)` now support an `unwrap` keyword argument to specify on which types to do recursive unnesting of array of structs to struct of arrays
-

Project.toml

@@ -18,7 +18,8 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 PooledArrays = "2dfb63ee-cc39-5dd5-95bd-886bf059d720"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+TypedTables = "9d95f2ec-7b3d-5a63-8d20-e2491e220bb9"
 WeakRefStrings = "ea10d353-3f73-51f8-a26c-33c1cb351aa5"
 
 [targets]
-test = ["Test", "OffsetArrays", "PooledArrays", "WeakRefStrings", "Documenter"]
+test = ["Test", "OffsetArrays", "PooledArrays", "TypedTables", "WeakRefStrings", "Documenter"]

README.md

@@ -30,7 +30,7 @@ julia> s.re
  0.680079  0.92407
  0.874437  0.929336
 
-julia> fieldarrays(s) # obtain all field arrays as a named tuple
+julia> StructArrays.components(s) # obtain all field arrays as a named tuple
 (re = [0.680079 0.92407; 0.874437 0.929336], im = [0.625239 0.267358; 0.737254 0.804478])
 ```
 
@@ -183,7 +183,9 @@ julia> map(t -> t.b ^ t.a, LazyRows(t))
 
 ## Advanced: structures with non-standard data layout
 
-StructArrays support structures with non-standard data layout (where `getproperty` has been overloaded or where the constructors are non-standard). The user is required to provide an overloaded `staticschema` for their type (to give the names and types of the properties of a given type) as well as a `createinstance` method. Here is an example of a type `MyType` that has as properties either its field `data` or properties of its field `rest` (which is a named tuple):
+StructArrays support structures with custom data layout. The user is required to overload `staticschema` in order to define the custom layout, `component` to access fields of the custom layout, and `createinstance(T, fields...)` to create an instance of type `T` from its custom fields `fields`. In other word, given `x::T`, `createinstance(T, (component(x, f) for f in fieldnames(staticschema(T)))...)` should successfully return an instance of type `T`.
+
+Here is an example of a type `MyType` that has as custom fields either its field `data` or fields of its field `rest` (which is a named tuple):
 
 ```julia
 using StructArrays
@@ -195,17 +197,17 @@ end
 
 MyType(x; kwargs...) = MyType(x, values(kwargs))
 
-Base.getproperty(b::MyType, s::Symbol) = s == :data ? getfield(b, 1) : getproperty(getfield(b, 2), s)
-Base.propertynames(b::MyType) = (:data, propertynames(getfield(b, 2))...)
-
-# explicitly give the "schema" of the object to StructArrays
 function StructArrays.staticschema(::Type{MyType{T, NamedTuple{names, types}}}) where {T, names, types}
-    NamedTuple{(:data, names...), Base.tuple_type_cons(T, types)}
+    return NamedTuple{(:data, names...), Base.tuple_type_cons(T, types)}
+end
+
+function StructArrays.component(m::MyType, key::Symbol)
+    return key === :data ? getfield(m, 1) : getfield(getfield(m, 2), key)
 end
 
 # generate an instance of MyType type
 function StructArrays.createinstance(::Type{MyType{T, NT}}, x, args...) where {T, NT}
-    MyType(x, NT(args))
+    return MyType(x, NT(args))
 end
 
 s = [MyType(rand(), a=1, b=2) for i in 1:10]

docs/Project.toml

@@ -1,3 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 PooledArrays = "2dfb63ee-cc39-5dd5-95bd-886bf059d720"
+
+[compat]
+PooledArrays = "1"

docs/src/index.md

@@ -23,7 +23,7 @@ collect_structarray
 # Accessors
 
 ```@docs
-fieldarrays
+StructArrays.components
 ```
 
 # Lazy iteration
@@ -38,7 +38,13 @@ LazyRows
 ```@docs
 StructArrays.append!!
 StructArrays.replace_storage
+```
+
+# Interface
+
+```@docs
 StructArrays.staticschema
+StructArrays.component
 StructArrays.createinstance
 ```
 

src/StructArrays.jl

@@ -3,7 +3,7 @@ module StructArrays
 using Base: tuple_type_cons, tuple_type_head, tuple_type_tail, tail
 
 export StructArray, StructVector, LazyRow, LazyRows
-export collect_structarray, fieldarrays
+export collect_structarray
 export replace_storage
 
 include("interface.jl")
@@ -18,10 +18,10 @@ include("tables.jl")
 import DataAPI: refarray, refvalue
 using DataAPI: defaultarray
 
-refarray(s::StructArray) = StructArray(map(refarray, fieldarrays(s)))
+refarray(s::StructArray) = StructArray(map(refarray, components(s)))
 
 function refvalue(s::StructArray{T}, v::Tup) where {T}
-    createinstance(T, map(refvalue, fieldarrays(s), v)...)
+    createinstance(T, map(refvalue, components(s), v)...)
 end
 
 # Use Adapt allows for automatic conversion of CPU to GPU StructArrays

src/collect.jl

@@ -113,7 +113,7 @@ function _widenstructarray(dest::StructArray, i, ::Type{T}) where {T}
     sch = hasfields(T) ? staticschema(T) : nothing
     sch !== nothing && fieldnames(sch) == propertynames(dest) || return _widenarray(dest, i, T)
     types = ntuple(x -> fieldtype(sch, x), fieldcount(sch))
-    cols = Tuple(fieldarrays(dest))
+    cols = Tuple(components(dest))
     newcols = map((a, b) -> _widenstructarray(a, i, b), cols, types)
     return StructArray{T}(newcols)
 end

src/interface.jl

@@ -1,6 +1,14 @@
 const Tup = Union{Tuple, NamedTuple}
 const EmptyTup = Union{Tuple{}, NamedTuple{(), Tuple{}}}
 
+"""
+    StructArrayys.component(x, i)
+
+Default to `getfield`. It should be overloaded for custom types with a custom
+schema. See [`StructArrays.staticschema`](@ref).
+"""
+component(x, i) = getfield(x, i)
+
 """
     StructArrays.staticschema(T)
 
@@ -9,8 +17,9 @@ The default schema for an element type `T`. A schema is a `Tuple` or
 this will have fields with the same names and types as `T`.
 
 This can be overloaded for custom types if required, in which case
-[`StructArrays.createinstance`](@ref) should also be defined.
-
+[`StructArrays.component`](@ref) and [`StructArrays.createinstance`](@ref)
+should also be defined.
+    
 ```julia-repl
 julia> StructArrays.staticschema(Complex{Float64})
 NamedTuple{(:re, :im),Tuple{Float64,Float64}}

src/lazy.jl

@@ -45,13 +45,14 @@ Base.propertynames(c::LazyRow) = propertynames(getfield(c, 1))
 function Base.show(io::IO, c::LazyRow)
     print(io, "LazyRow")
     columns, index = getfield(c, 1), getfield(c, 2)
-    tup = StructArray(fieldarrays(columns))[index]
+    tup = StructArray(components(columns))[index]
     show(io, tup)
 end
 
+@inline Base.@propagate_inbounds component(l::LazyRow, key) = getproperty(l, key)
+
 staticschema(::Type{<:LazyRow{T}}) where {T} = staticschema(T)
 buildfromschema(f, ::Type{<:LazyRow{T}}) where {T} = buildfromschema(f, T)
-
 iscompatible(::Type{<:LazyRow{R}}, ::Type{S}) where {R, S<:StructArray} = iscompatible(R, S)
 
 (s::ArrayInitializer)(::Type{<:LazyRow{T}}, d) where {T} = buildfromschema(typ -> s(typ, d), T)
@@ -74,11 +75,16 @@ struct LazyRows{T, N, C, I} <: AbstractArray{LazyRow{T, N, C, I}, N}
     columns::StructArray{T, N, C, I}
 end
 Base.parent(v::LazyRows) = getfield(v, 1)
-fieldarrays(v::LazyRows) = fieldarrays(parent(v))
+components(v::LazyRows) = components(parent(v))
+
+component(v::LazyRows, key) = component(parent(v), key)
+
+staticschema(::Type{LazyRows{T, N, C, I}}) where {T, N, C, I} = staticschema(C)
+createinstance(::Type{<:LazyRows{T}}, args...) where {T} = LazyRows(StructArray{T}(args))
 
-Base.getproperty(s::LazyRows, key::Symbol) = getproperty(parent(s), key)
-Base.getproperty(s::LazyRows, key::Int) = getproperty(parent(s), key)
-Base.propertynames(c::LazyRows) = propertynames(parent(c))
+Base.getproperty(v::LazyRows, key::Symbol) = component(v, key)
+Base.getproperty(v::LazyRows, key::Int) = component(v, key)
+Base.propertynames(v::LazyRows) = propertynames(parent(v))
 
 Base.size(v::LazyRows) = size(parent(v))
 Base.getindex(v::LazyRows{<:Any, <:Any, <:Any, Int}, i::Int) = LazyRow(parent(v), i)
@@ -91,6 +97,6 @@ end
 
 function Base.showarg(io::IO, s::LazyRows{T}, toplevel) where T
     print(io, "LazyRows")
-    showfields(io, Tuple(fieldarrays(s)))
+    showfields(io, Tuple(components(s)))
     toplevel && print(io, " with eltype LazyRow{", T, "}")
 end