From ffeaea37d221191bb8bc8de2f553d5b2b3d21140 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Sun, 17 Nov 2024 12:23:09 +0000 Subject: [PATCH] build based on 07e7462 --- dev/advanced/index.html | 2 +- dev/counterintuitive/index.html | 2 +- dev/examples/index.html | 2 +- dev/index.html | 2 +- dev/reference/index.html | 24 ++++++++++++------------ dev/search/index.html | 2 +- 6 files changed, 17 insertions(+), 17 deletions(-) diff --git a/dev/advanced/index.html b/dev/advanced/index.html index ae5d19f..2783f77 100644 --- a/dev/advanced/index.html +++ b/dev/advanced/index.html @@ -67,4 +67,4 @@ threads = 1024 blocks = cld(length(dd),threads) -@cuda threads=threads blocks=blocks kernel!(de, dd) +@cuda threads=threads blocks=blocks kernel!(de, dd) diff --git a/dev/counterintuitive/index.html b/dev/counterintuitive/index.html index eedd747..2148d75 100644 --- a/dev/counterintuitive/index.html +++ b/dev/counterintuitive/index.html @@ -135,4 +135,4 @@ [1, 2] [1, 2] [1, 2] - [1, 2]

Because setting x[1] .= 1 creates a Bar struct first, broadcasted assignment modifies this new materialized struct rather than the StructArray x. Note, however, that x[1] = x[1] .= 1 works, since it assigns the modified materialized struct to the first entry of x.

Mutability

The component arrays of a StructArray can be modified in-place mutable even if the struct element type of the overall array is immutable. A StructArray with immutable elements will in many cases behave identically to (but be more efficient than) a StructArray with mutable elements.

+ [1, 2]

Because setting x[1] .= 1 creates a Bar struct first, broadcasted assignment modifies this new materialized struct rather than the StructArray x. Note, however, that x[1] = x[1] .= 1 works, since it assigns the modified materialized struct to the first entry of x.

Mutability

The component arrays of a StructArray can be modified in-place mutable even if the struct element type of the overall array is immutable. A StructArray with immutable elements will in many cases behave identically to (but be more efficient than) a StructArray with mutable elements.

diff --git a/dev/examples/index.html b/dev/examples/index.html index 2355928..d245be6 100644 --- a/dev/examples/index.html +++ b/dev/examples/index.html @@ -63,4 +63,4 @@ [:, :, 2] = 5 7 - 6 8 + 6 8 diff --git a/dev/index.html b/dev/index.html index 0f37f1a..d82a0d5 100644 --- a/dev/index.html +++ b/dev/index.html @@ -125,4 +125,4 @@ Foo(11, "a") Foo(22, "b") Foo(44, "d") - Foo(55, "e") + Foo(55, "e") diff --git a/dev/reference/index.html b/dev/reference/index.html index 0c77237..2c064ea 100644 --- a/dev/reference/index.html +++ b/dev/reference/index.html @@ -1,5 +1,5 @@ -Index · StructArrays
Edit on GitHub

StructArrays.jl

Type

StructArrays.StructArray — Type
StructArray{T,N,C,I} <: AbstractArray{T, N}

A type that stores an N-dimensional array of structures of type T as a structure of arrays.

  • getindex and setindex! are overloaded to get/set values of type T.
  • getproperty is overloaded to return individual field arrays.

Fields

  • components: a NamedTuple or Tuple of the arrays used by each field. These can be accessed by components(x).
source

Constructors

StructArrays.StructArray — Method
StructArray{T}((components...)::Union{Tuple, NamedTuple})
+Index · StructArrays
Edit on GitHub
StructArrays.jl
Type
StructArrays.StructArray — Type
StructArray{T,N,C,I} <: AbstractArray{T, N}
A type that stores an N-dimensional array of structures of type T as a structure of arrays.
  • getindex and setindex! are overloaded to get/set values of type T.
  • getproperty is overloaded to return individual field arrays.
Fields
  • components: a NamedTuple or Tuple of the arrays used by each field. These can be accessed by components(x).
source
Constructors
StructArrays.StructArray — Method
StructArray{T}((components...)::Union{Tuple, NamedTuple})
 StructArray{T}(name1=component1, name2=component2, ...)
Construct a StructArray of element type T from the specified field arrays.
StructArray((components...)::Union{Tuple, NamedTuple})
 StructArray(name1=component1, name2=component2, ...)
Construct a StructArray with a Tuple or NamedTuple element type from the specified field arrays.
Examples
julia> StructArray{ComplexF64}(([1.0, 2.0], [3.0, 4.0]))
 2-element StructArray(::Array{Float64,1}, ::Array{Float64,1}) with eltype Complex{Float64}:
@@ -20,7 +20,7 @@
 julia> StructArray(a=zeros(2,2), b=ones(2,2))
 2×2 StructArray(::Array{Float64,2}, ::Array{Float64,2}) with eltype NamedTuple{(:a, :b),Tuple{Float64,Float64}}:
  (a = 0.0, b = 1.0)  (a = 0.0, b = 1.0)
- (a = 0.0, b = 1.0)  (a = 0.0, b = 1.0)
source
StructArrays.StructArray — Method
StructArray{T}(A::AbstractArray; dims, unwrap=FT->FT!=eltype(A))
Construct a StructArray from slices of A along dims.
The unwrap keyword argument is a function that determines whether to recursively convert fields of type FT to StructArrays.
julia> X = [1.0 2.0; 3.0 4.0]
+ (a = 0.0, b = 1.0)  (a = 0.0, b = 1.0)
source
StructArrays.StructArray — Method
StructArray{T}(A::AbstractArray; dims, unwrap=FT->FT!=eltype(A))
Construct a StructArray from slices of A along dims.
The unwrap keyword argument is a function that determines whether to recursively convert fields of type FT to StructArrays.
julia> X = [1.0 2.0; 3.0 4.0]
 2×2 Array{Float64,2}:
  1.0  2.0
  3.0  4.0
@@ -36,10 +36,10 @@
  3.0 + 4.0im
By default, fields will be unwrapped until they match the element type of the array:
julia> StructArray{Tuple{Float64,Complex{Float64}}}(rand(3,2); dims=1)
 2-element StructArray(view(::Array{Float64,2}, 1, :), StructArray(view(::Array{Float64,2}, 2, :), view(::Array{Float64,2}, 3, :))) with eltype Tuple{Float64,Complex{Float64}}:
  (0.004767505234193781, 0.27949621887414566 + 0.9039320635041561im)
- (0.41853472213051335, 0.5760165160827859 + 0.9782723869433818im)
source
StructArrays.StructArray — Method
StructArray{T}(undef, dims; unwrap=T->false)
Construct an uninitialized StructArray with element type T, with Array field arrays.
The unwrap keyword argument is a function that determines whether to recursively convert arrays of element type T to StructArrays.
Examples
julia> StructArray{ComplexF64}(undef, (2,3))
+ (0.41853472213051335, 0.5760165160827859 + 0.9782723869433818im)
source
StructArrays.StructArray — Method
StructArray{T}(undef, dims; unwrap=T->false)
Construct an uninitialized StructArray with element type T, with Array field arrays.
The unwrap keyword argument is a function that determines whether to recursively convert arrays of element type T to StructArrays.
Examples
julia> StructArray{ComplexF64}(undef, (2,3))
 2×3 StructArray(::Array{Float64,2}, ::Array{Float64,2}) with eltype Complex{Float64}:
   2.3166e-314+2.38405e-314im  2.39849e-314+2.38405e-314im  2.41529e-314+2.38405e-314im
- 2.31596e-314+2.41529e-314im  2.31596e-314+2.41529e-314im  2.31596e-314+NaN*im
source
StructArrays.StructArray — Method
StructArray(A; unwrap = T->false)
Construct a StructArray from an existing multidimensional array or iterator A.
The unwrap keyword argument is a function that determines whether to recursively convert arrays of element type T to StructArrays.
Examples
Basic usage
julia> A = rand(ComplexF32, 2,2)
+ 2.31596e-314+2.41529e-314im  2.31596e-314+2.41529e-314im  2.31596e-314+NaN*im
source
StructArrays.StructArray — Method
StructArray(A; unwrap = T->false)
Construct a StructArray from an existing multidimensional array or iterator A.
The unwrap keyword argument is a function that determines whether to recursively convert arrays of element type T to StructArrays.
Examples
Basic usage
julia> A = rand(ComplexF32, 2,2)
 2×2 Array{Complex{Float32},2}:
  0.694399+0.94999im  0.422804+0.891131im
  0.101001+0.33644im  0.632468+0.811319im
@@ -55,10 +55,10 @@
 3×3 StructArray(::Array{Int64,2}, StructArray(::Array{Int64,2}, ::Array{Int64,2})) with eltype Tuple{Int64,Complex{Int64}}:
  (1, 1+2im)  (1, 1+3im)  (1, 1+4im)
  (1, 2+2im)  (1, 2+3im)  (1, 2+4im)
- (1, 3+2im)  (1, 3+3im)  (1, 3+4im)
source
StructArrays.collect_structarray — Function
collect_structarray(itr; initializer = default_initializer)
Collects itr into a StructArray. The user can optionally pass a initializer, that is to say a function (S, d) -> v that associates to a type and a size an array of eltype S and size d. By default initializer returns a StructArray of Array but custom array types may be used.
source
Accessors
StructArrays.components — Function
components(s::StructArray)
Return the field arrays corresponding to the various entry of the struct as a NamedTuple, or a Tuple if the struct has no names.
Examples
julia> s = StructArray(rand(ComplexF64, 4));
+ (1, 3+2im)  (1, 3+3im)  (1, 3+4im)
source
StructArrays.collect_structarray — Function
collect_structarray(itr; initializer = default_initializer)
Collects itr into a StructArray. The user can optionally pass a initializer, that is to say a function (S, d) -> v that associates to a type and a size an array of eltype S and size d. By default initializer returns a StructArray of Array but custom array types may be used.
source
Accessors
StructArrays.components — Function
components(s::StructArray)
Return the field arrays corresponding to the various entry of the struct as a NamedTuple, or a Tuple if the struct has no names.
Examples
julia> s = StructArray(rand(ComplexF64, 4));
 
 julia> components(s)
-(re = [0.396526, 0.486036, 0.459595, 0.0323561], im = [0.147702, 0.81043, 0.00993469, 0.487091])
source
Lazy iteration
StructArrays.LazyRow — Type
LazyRow(s::StructArray, i)
A lazy representation of s[i]. LazyRow(s, i) does not materialize the ith row but returns a lazy wrapper around it on which getproperty does the correct thing. This is useful when the row has many fields only some of which are necessary. It also allows changing columns in place.
See LazyRows to get an iterator of LazyRows.
Examples
julia> t = StructArray((a = [1, 2], b = ["x", "y"]));
+(re = [0.396526, 0.486036, 0.459595, 0.0323561], im = [0.147702, 0.81043, 0.00993469, 0.487091])
source
Lazy iteration
StructArrays.LazyRow — Type
LazyRow(s::StructArray, i)
A lazy representation of s[i]. LazyRow(s, i) does not materialize the ith row but returns a lazy wrapper around it on which getproperty does the correct thing. This is useful when the row has many fields only some of which are necessary. It also allows changing columns in place.
See LazyRows to get an iterator of LazyRows.
Examples
julia> t = StructArray((a = [1, 2], b = ["x", "y"]));
 
 julia> LazyRow(t, 2).a
 2
@@ -69,10 +69,10 @@
 julia> t
 2-element StructArray(::Array{Int64,1}, ::Array{String,1}) with eltype NamedTuple{(:a, :b),Tuple{Int64,String}}:
  (a = 1, b = "x")
- (a = 123, b = "y")
source
StructArrays.LazyRows — Type
LazyRows(s::StructArray)
An iterator of LazyRows of s.
Examples
julia> map(t -> t.b ^ t.a, LazyRows(t))
 2-element Array{String,1}:
  "x"
- "yy"
source
Advanced APIs
StructArrays.append!! — Function
dest = StructArrays.append!!(dest, itr)
Try to append itr into a vector dest, widening the element type of dest if it cannot hold the elements of itr. That is to say,
vcat(dest, StructVector(itr)) == append!!(dest, itr)
holds. Note that the dest argument may or may not be the same object as the returned value.
The state of dest is unpredictable after append!! is called (e.g., it may contain some, none or all the elements from itr).
source
StructArrays.replace_storage — Function
StructArrays.replace_storage(f, s::StructArray)
Change storage type for components: each array v is replaced by f(v). f(v) is expected to have the same eltype and size as v.
Examples
If PooledArrays is loaded, we can pool all columns of non isbitstype:
julia> using StructArrays, PooledArrays
+ "yy"
source
Advanced APIs
StructArrays.append!! — Function
dest = StructArrays.append!!(dest, itr)
Try to append itr into a vector dest, widening the element type of dest if it cannot hold the elements of itr. That is to say,
vcat(dest, StructVector(itr)) == append!!(dest, itr)
holds. Note that the dest argument may or may not be the same object as the returned value.
The state of dest is unpredictable after append!! is called (e.g., it may contain some, none or all the elements from itr).
source
StructArrays.replace_storage — Function
StructArrays.replace_storage(f, s::StructArray)
Change storage type for components: each array v is replaced by f(v). f(v) is expected to have the same eltype and size as v.
Examples
If PooledArrays is loaded, we can pool all columns of non isbitstype:
julia> using StructArrays, PooledArrays
 
 julia> s = StructArray(a=1:3, b = fill("string", 3));
 
@@ -82,7 +82,7 @@
 3-element StructArray(::UnitRange{Int64}, ::PooledVector{String, UInt32, Vector{UInt32}}) with eltype @NamedTuple{a::Int64, b::String}:
  (a = 1, b = "string")
  (a = 2, b = "string")
- (a = 3, b = "string")
source
Interface
StructArrays.staticschema — Function
StructArrays.staticschema(T)
The default schema for an element type T. A schema is a Tuple or NamedTuple type containing the necessary fields to construct T. By default, 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.component and StructArrays.createinstance should also be defined.
julia> StructArrays.staticschema(Complex{Float64})
-NamedTuple{(:re, :im),Tuple{Float64,Float64}}
source
StructArrays.createinstance — Function
StructArrays.createinstance(T, args...)
Construct an instance of type T from its backing representation. args here are the elements of the Tuple or NamedTuple type specified staticschema(T).
julia> StructArrays.createinstance(Complex{Float64}, (re=1.0, im=2.0)...)
-1.0 + 2.0im
source
Internals
StructArrays.get_ith — Function
StructArrays.get_ith(cols::Union{Tuple,NamedTuple}, I...)
Form a Tuple of the Ith index of each element of cols, i.e. is equivalent to
map(c -> c[I...], Tuple(cols))
source
StructArrays.map_params — Function
StructArrays.map_params(f, T)
Apply f to each field type of Tuple or NamedTuple type T, returning a new Tuple or NamedTuple object.
julia> StructArrays.map_params(T -> Complex{T}, Tuple{Int32,Float64})
-(Complex{Int32}, Complex{Float64})
source
StructArrays.buildfromschema — Function
StructArrays.buildfromschema(initializer, T[, S])
Construct a StructArray{T} with a function initializer, using a schema S.
initializer(T) is a function applied to each field type of S, and should return an AbstractArray{S}
S is a Tuple or NamedTuple type. The default value is staticschema(T).
source
StructArrays.bypass_constructor — Function
StructArrays.bypass_constructor(T, args)
Create an instance of type T from a tuple of field values args, bypassing possible internal constructors. T should be a concrete type.
source
StructArrays.iscompatible — Function
StructArrays.iscompatible(::Type{S}, ::Type{V}) where {S, V<:AbstractArray}
Check whether element type S can be pushed to a container of type V.
source
StructArrays.maybe_convert_elt — Function
StructArrays.maybe_convert_elt(T, x)
Element conversion before assignment in a StructArray. By default, this calls convert(T, x); however, you can specialize it for other types.
source
StructArrays.findconsistentvalue — Function
findconsistentvalue(f, componenents::Union{Tuple, NamedTuple})
Compute the unique value that f takes on each component ∈ componenents. If not all values are equal, return nothing. Otherwise, return the unique value.
source

+ (a = 3, b = "string")
source

Interface

StructArrays.staticschema — Function
StructArrays.staticschema(T)

The default schema for an element type T. A schema is a Tuple or NamedTuple type containing the necessary fields to construct T. By default, 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.component and StructArrays.createinstance should also be defined.

julia> StructArrays.staticschema(Complex{Float64})
+NamedTuple{(:re, :im),Tuple{Float64,Float64}}
source
StructArrays.createinstance — Function
StructArrays.createinstance(T, args...)

Construct an instance of type T from its backing representation. args here are the elements of the Tuple or NamedTuple type specified staticschema(T).

julia> StructArrays.createinstance(Complex{Float64}, (re=1.0, im=2.0)...)
+1.0 + 2.0im
source

Internals

StructArrays.get_ith — Function
StructArrays.get_ith(cols::Union{Tuple,NamedTuple}, I...)

Form a Tuple of the Ith index of each element of cols, i.e. is equivalent to

map(c -> c[I...], Tuple(cols))
source
StructArrays.map_params — Function
StructArrays.map_params(f, T)

Apply f to each field type of Tuple or NamedTuple type T, returning a new Tuple or NamedTuple object.

julia> StructArrays.map_params(T -> Complex{T}, Tuple{Int32,Float64})
+(Complex{Int32}, Complex{Float64})
source
StructArrays.buildfromschema — Function
StructArrays.buildfromschema(initializer, T[, S])

Construct a StructArray{T} with a function initializer, using a schema S.

initializer(T) is a function applied to each field type of S, and should return an AbstractArray{S}

S is a Tuple or NamedTuple type. The default value is staticschema(T).

source
StructArrays.bypass_constructor — Function
StructArrays.bypass_constructor(T, args)

Create an instance of type T from a tuple of field values args, bypassing possible internal constructors. T should be a concrete type.

source
StructArrays.iscompatible — Function
StructArrays.iscompatible(::Type{S}, ::Type{V}) where {S, V<:AbstractArray}

Check whether element type S can be pushed to a container of type V.

source
StructArrays.maybe_convert_elt — Function
StructArrays.maybe_convert_elt(T, x)

Element conversion before assignment in a StructArray. By default, this calls convert(T, x); however, you can specialize it for other types.

source
StructArrays.findconsistentvalue — Function
findconsistentvalue(f, componenents::Union{Tuple, NamedTuple})

Compute the unique value that f takes on each component ∈ componenents. If not all values are equal, return nothing. Otherwise, return the unique value.

source
diff --git a/dev/search/index.html b/dev/search/index.html index 60aee87..4557e4a 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · StructArrays

Loading search...

    +Search · StructArrays

    Loading search...