StaticArraysCore transition (#1045)

mateuszbaran · thchr · web-flow · commit 29a76ec7fdd6 · 2022-06-24T14:45:26.000+02:00
* StaticArraysCore transition

* update error test

* add StaticArraysCore docstrings to documentation

* move StaticArraysCore re-exports

* add StaticArraysCore to docs project dependencies

* mention StaticArraysCore.jl in README

* Update README.md

Co-authored-by: Thomas Christensen &lt;tchr@mit.edu&gt;

Co-authored-by: Thomas Christensen &lt;tchr@mit.edu&gt;
diff --git a/Project.toml b/Project.toml
@@ -1,14 +1,16 @@
 name = "StaticArrays"
 uuid = "90137ffa-7385-5640-81b9-e52037218182"
-version = "1.4.7"
+version = "1.5.0"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+StaticArraysCore = "1e83bf80-4336-4d27-bf5d-d5a4f845583c"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [compat]
 julia = "1.6"
+StaticArraysCore = "1"
 
 [extras]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
diff --git a/README.md b/README.md
@@ -23,6 +23,15 @@ Further, the abstract `FieldVector` can be used to make fast `StaticVector`s
 out of any uniform Julia "struct".
 Full documentation can be found [here](https://JuliaArrays.github.io/StaticArrays.jl/stable/).
 
+Most of the primary array types exported by StaticArrays.jl are defined in the small interface
+package [StaticArraysCore.jl](https://github.com/JuliaArrays/StaticArraysCore.jl). This includes
+e.g., the definitions of the abstract type `StaticArray` and the concrete types `SArray`,
+`MArray`, and `SizedArray` (as well as their dimension-specific aliases).
+This enables downstream packages to implement new methods for these types without depending
+on (and hence loading) the entirety of StaticArrays.jl, and thereby to avoid incurring the full
+load-time of StaticArrays.jl (which is on the order of 0.6 s for StaticArrays.jl v1.4 on Julia
+v1.7).
+
 ## Speed
 
 The speed of *small* `SVector`s, `SMatrix`s and `SArray`s is often > 10 × faster
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+StaticArraysCore = "1e83bf80-4336-4d27-bf5d-d5a4f845583c"
 
 [compat]
 Documenter = "~0.27"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,11 +1,12 @@
 using Documenter
 using StaticArrays
+using StaticArraysCore
 
 # Setup for doctests in docstrings
 DocMeta.setdocmeta!(StaticArrays, :DocTestSetup, :(using LinearAlgebra, StaticArrays))
 
 makedocs(;
-    modules = [StaticArrays],
+    modules = [StaticArrays, StaticArraysCore],
     format = Documenter.HTML(
         canonical = "https://JuliaArrays.github.io/StaticArrays.jl/stable/",
         assets = ["assets/favicon.ico"],
diff --git a/docs/src/pages/api.md b/docs/src/pages/api.md
@@ -356,5 +356,5 @@ faster!
 Pages   = ["api.md"]
 ```
 ```@autodocs
-Modules = [StaticArrays]
+Modules = [StaticArrays, StaticArraysCore]
 ```
diff --git a/src/MArray.jl b/src/MArray.jl
@@ -1,42 +1,3 @@
-"""
-    MArray{S, T, N, L}(undef)
-    MArray{S, T, N, L}(x::NTuple{L})
-    MArray{S, T, N, L}(x1, x2, x3, ...)
-
-
-Construct a statically-sized, mutable array `MArray`. The data may optionally be
-provided upon construction and can be mutated later. The `S` parameter is a Tuple-type
-specifying the dimensions, or size, of the array - such as `Tuple{3,4,5}` for a 3×4×5-sized
-array. The `N` parameter is the dimension of the array; the `L` parameter is the `length`
-of the array and is always equal to `prod(S)`. Constructors may drop the `L`, `N` and `T`
-parameters if they are inferrable from the input (e.g. `L` is always inferrable from `S`).
-
-    MArray{S}(a::Array)
-
-Construct a statically-sized, mutable array of dimensions `S` (expressed as a `Tuple{...}`)
-using the data from `a`. The `S` parameter is mandatory since the size of `a` is unknown to
-the compiler (the element type may optionally also be specified).
-"""
-mutable struct MArray{S <: Tuple, T, N, L} <: StaticArray{S, T, N}
-    data::NTuple{L,T}
-
-    function MArray{S,T,N,L}(x::NTuple{L,T}) where {S<:Tuple,T,N,L}
-        check_array_parameters(S, T, Val{N}, Val{L})
-        new{S,T,N,L}(x)
-    end
-
-    function MArray{S,T,N,L}(x::NTuple{L,Any}) where {S<:Tuple,T,N,L}
-        check_array_parameters(S, T, Val{N}, Val{L})
-        new{S,T,N,L}(convert_ntuple(T, x))
-    end
-
-    function MArray{S,T,N,L}(::UndefInitializer) where {S<:Tuple,T,N,L}
-        check_array_parameters(S, T, Val{N}, Val{L})
-        new{S,T,N,L}()
-    end
-end
-
-@inline MArray{S,T,N}(x::Tuple) where {S<:Tuple,T,N} = MArray{S,T,N,tuple_prod(S)}(x)
 
 @generated function (::Type{MArray{S,T,N}})(::UndefInitializer) where {S,T,N}
     return quote
diff --git a/src/MMatrix.jl b/src/MMatrix.jl
@@ -1,21 +1,3 @@
-"""
-    MMatrix{S1, S2, T, L}(undef)
-    MMatrix{S1, S2, T, L}(x::NTuple{L, T})
-    MMatrix{S1, S2, T, L}(x1, x2, x3, ...)
-
-Construct a statically-sized, mutable matrix `MMatrix`. The data may optionally
-be provided upon construction and can be mutated later. The `L` parameter is the
-`length` of the array and is always equal to `S1 * S2`. Constructors may drop
-the `L`, `T` and even `S2` parameters if they are inferrable from the input
-(e.g. `L` is always inferrable from `S1` and `S2`).
-
-    MMatrix{S1, S2}(mat::Matrix)
-
-Construct a statically-sized, mutable matrix of dimensions `S1 × S2` using the data from
-`mat`. The parameters `S1` and `S2` are mandatory since the size of `mat` is
-unknown to the compiler (the element type may optionally also be specified).
-"""
-const MMatrix{S1, S2, T, L} = MArray{Tuple{S1, S2}, T, 2, L}
 
 @generated function (::Type{MMatrix{S1,S2,T}})(::UndefInitializer) where {S1,S2,T}
     return quote
diff --git a/src/MVector.jl b/src/MVector.jl
@@ -1,20 +1,3 @@
-"""
-    MVector{S,T}(undef)
-    MVector{S,T}(x::NTuple{S, T})
-    MVector{S,T}(x1, x2, x3, ...)
-
-Construct a statically-sized, mutable vector `MVector`. Data may optionally be
-provided upon construction, and can be mutated later. Constructors may drop the
-`T` and `S` parameters if they are inferrable from the input (e.g.
-`MVector(1,2,3)` constructs an `MVector{3, Int}`).
-
-    MVector{S}(vec::Vector)
-
-Construct a statically-sized, mutable vector of length `S` using the data from
-`vec`. The parameter `S` is mandatory since the length of `vec` is unknown to the
-compiler (the element type may optionally also be specified).
-"""
-const MVector{S, T} = MArray{Tuple{S}, T, 1, S}
 
 # Some more advanced constructor-like functions
 @inline zeros(::Type{MVector{N}}) where {N} = zeros(MVector{N,Float64})
diff --git a/src/SArray.jl b/src/SArray.jl
@@ -1,35 +1,3 @@
-"""
-    SArray{S, T, N, L}(x::NTuple{L})
-    SArray{S, T, N, L}(x1, x2, x3, ...)
-
-Construct a statically-sized array `SArray`. Since this type is immutable, the data must be
-provided upon construction and cannot be mutated later. The `S` parameter is a Tuple-type
-specifying the dimensions, or size, of the array - such as `Tuple{3,4,5}` for a 3×4×5-sized
-array. The `N` parameter is the dimension of the array; the `L` parameter is the `length`
-of the array and is always equal to `prod(S)`. Constructors may drop the `L`, `N` and `T`
-parameters if they are inferrable from the input (e.g. `L` is always inferrable from `S`).
-
-    SArray{S}(a::Array)
-
-Construct a statically-sized array of dimensions `S` (expressed as a `Tuple{...}`) using
-the data from `a`. The `S` parameter is mandatory since the size of `a` is unknown to the
-compiler (the element type may optionally also be specified).
-"""
-struct SArray{S <: Tuple, T, N, L} <: StaticArray{S, T, N}
-    data::NTuple{L,T}
-
-    function SArray{S, T, N, L}(x::NTuple{L,T}) where {S<:Tuple, T, N, L}
-        check_array_parameters(S, T, Val{N}, Val{L})
-        new{S, T, N, L}(x)
-    end
-
-    function SArray{S, T, N, L}(x::NTuple{L,Any}) where {S<:Tuple, T, N, L}
-        check_array_parameters(S, T, Val{N}, Val{L})
-        new{S, T, N, L}(convert_ntuple(T, x))
-    end
-end
-
-@inline SArray{S,T,N}(x::Tuple) where {S<:Tuple,T,N} = SArray{S,T,N,tuple_prod(S)}(x)
 
 @noinline function generator_too_short_error(inds::CartesianIndices, i::CartesianIndex)
     error("Generator produced too few elements: Expected exactly $(shape_string(inds)) elements, but generator stopped at $(shape_string(i))")
diff --git a/src/SMatrix.jl b/src/SMatrix.jl
@@ -1,20 +1,3 @@
-"""
-    SMatrix{S1, S2, T, L}(x::NTuple{L, T})
-    SMatrix{S1, S2, T, L}(x1, x2, x3, ...)
-
-Construct a statically-sized matrix `SMatrix`. Since this type is immutable,
-the data must be provided upon construction and cannot be mutated later. The
-`L` parameter is the `length` of the array and is always equal to `S1 * S2`.
-Constructors may drop the `L`, `T` and even `S2` parameters if they are inferrable
-from the input (e.g. `L` is always inferrable from `S1` and `S2`).
-
-    SMatrix{S1, S2}(mat::Matrix)
-
-Construct a statically-sized matrix of dimensions `S1 × S2` using the data from
-`mat`. The parameters `S1` and `S2` are mandatory since the size of `mat` is
-unknown to the compiler (the element type may optionally also be specified).
-"""
-const SMatrix{S1, S2, T, L} = SArray{Tuple{S1, S2}, T, 2, L}
 
 # Some more advanced constructor-like functions
 @inline one(::Type{SMatrix{N}}) where {N} = one(SMatrix{N,N})
diff --git a/src/SVector.jl b/src/SVector.jl
@@ -1,19 +1,3 @@
-"""
-    SVector{S, T}(x::NTuple{S, T})
-    SVector{S, T}(x1, x2, x3, ...)
-
-Construct a statically-sized vector `SVector`. Since this type is immutable,
-the data must be provided upon construction and cannot be mutated later.
-Constructors may drop the `T` and `S` parameters if they are inferrable from the
-input (e.g. `SVector(1,2,3)` constructs an `SVector{3, Int}`).
-
-    SVector{S}(vec::Vector)
-
-Construct a statically-sized vector of length `S` using the data from `vec`.
-The parameter `S` is mandatory since the length of `vec` is unknown to the
-compiler (the element type may optionally also be specified).
-"""
-const SVector{S, T} = SArray{Tuple{S}, T, 1, S}
 
 # Some more advanced constructor-like functions
 @inline zeros(::Type{SVector{N}}) where {N} = zeros(SVector{N,Float64})
diff --git a/src/SizedArray.jl b/src/SizedArray.jl
@@ -1,36 +1,3 @@
-require_one_based_indexing(A...) = !Base.has_offset_axes(A...) ||
-    throw(ArgumentError("offset arrays are not supported but got an array with index other than 1"))
-
-"""
-    SizedArray{Tuple{dims...}}(array)
-
-Wraps an `AbstractArray` with a static size, so to take advantage of the (faster)
-methods defined by the static array package. The size is checked once upon
-construction to determine if the number of elements (`length`) match, but the
-array may be reshaped.
-
-The aliases `SizedVector{N}` and `SizedMatrix{N,M}` are provided as more
-convenient names for one and two dimensional `SizedArray`s. For example, to
-wrap a 2x3 array `a` in a `SizedArray`, use `SizedMatrix{2,3}(a)`.
-"""
-struct SizedArray{S<:Tuple,T,N,M,TData<:AbstractArray{T,M}} <: StaticArray{S,T,N}
-    data::TData
-
-    function SizedArray{S,T,N,M,TData}(a::TData) where {S<:Tuple,T,N,M,TData<:AbstractArray{T,M}}
-        require_one_based_indexing(a)
-        if size(a) != size_to_tuple(S) && size(a) != (tuple_prod(S),)
-            throw(DimensionMismatch("Dimensions $(size(a)) don't match static size $S"))
-        end
-        return new{S,T,N,M,TData}(a)
-    end
-
-    function SizedArray{S,T,N,1,TData}(::UndefInitializer) where {S<:Tuple,T,N,TData<:AbstractArray{T,1}}
-        return new{S,T,N,1,TData}(TData(undef, tuple_prod(S)))
-    end
-    function SizedArray{S,T,N,N,TData}(::UndefInitializer) where {S<:Tuple,T,N,TData<:AbstractArray{T,N}}
-        return new{S,T,N,N,TData}(TData(undef, size_to_tuple(S)...))
-    end
-end
 
 @inline function SizedArray{S,T,N,M}(a::AbstractArray) where {S<:Tuple,T,N,M}
     if eltype(a) == T && (M == 1 || M == ndims(a))
@@ -130,10 +97,6 @@ Base.parent(sa::SizedArray) = sa.data
 Base.unsafe_convert(::Type{Ptr{T}}, sa::SizedArray) where {T} = Base.unsafe_convert(Ptr{T}, sa.data)
 Base.elsize(::Type{SizedArray{S,T,M,N,A}}) where {S,T,M,N,A} = Base.elsize(A)
 
-const SizedVector{S,T} = SizedArray{Tuple{S},T,1,1}
-
-const SizedMatrix{S1,S2,T} = SizedArray{Tuple{S1,S2},T,2}
-
 Base.dataids(sa::SizedArray) = Base.dataids(sa.data)
 
 function promote_rule(
diff --git a/src/StaticArrays.jl b/src/StaticArrays.jl
@@ -21,12 +21,28 @@ import LinearAlgebra: transpose, adjoint, dot, eigvals, eigen, lyap, tr,
                       normalize!, Eigen, det, logdet, logabsdet, cross, diff, qr, \
 using LinearAlgebra: checksquare
 
-export SOneTo
+# StaticArraysCore imports
+# there is intentionally no "using StaticArraysCore" to not take all symbols exported
+# from StaticArraysCore to make transitioning definitions to StaticArraysCore easier.
+using StaticArraysCore: StaticArraysCore, StaticArray, StaticScalar, StaticVector,
+                        StaticMatrix, StaticVecOrMat, tuple_length, tuple_prod,
+                        tuple_minimum, size_to_tuple, require_one_based_indexing
+import StaticArraysCore: SArray, SVector, SMatrix
+import StaticArraysCore: MArray, MVector, MMatrix
+import StaticArraysCore: SizedArray, SizedVector, SizedMatrix
+import StaticArraysCore: check_array_parameters, convert_ntuple
+
+# end of StaticArraysCore imports
+# StaticArraysCore exports
 export StaticScalar, StaticArray, StaticVector, StaticMatrix
 export Scalar, SArray, SVector, SMatrix
 export MArray, MVector, MMatrix
-export FieldVector, FieldMatrix, FieldArray
 export SizedArray, SizedVector, SizedMatrix
+# end of StaticArraysCore exports
+
+export SOneTo
+export Scalar
+export FieldVector, FieldMatrix, FieldArray
 export SDiagonal
 export SHermitianCompact
 
@@ -41,41 +57,6 @@ export push, pop, pushfirst, popfirst, insert, deleteat, setindex
 
 include("SOneTo.jl")
 
-"""
-    abstract type StaticArray{S, T, N} <: AbstractArray{T, N} end
-    StaticScalar{T}     = StaticArray{Tuple{}, T, 0}
-    StaticVector{N,T}   = StaticArray{Tuple{N}, T, 1}
-    StaticMatrix{N,M,T} = StaticArray{Tuple{N,M}, T, 2}
-
-`StaticArray`s are Julia arrays with fixed, known size.
-
-## Dev docs
-
-They must define the following methods:
- - Constructors that accept a flat tuple of data.
- - `getindex()` with an integer (linear indexing) (preferably `@inline` with `@boundscheck`).
- - `Tuple()`, returning the data in a flat Tuple.
-
-It may be useful to implement:
-
-- `similar_type(::Type{MyStaticArray}, ::Type{NewElType}, ::Size{NewSize})`, returning a
-  type (or type constructor) that accepts a flat tuple of data.
-
-For mutable containers you may also need to define the following:
-
- - `setindex!` for a single element (linear indexing).
- - `similar(::Type{MyStaticArray}, ::Type{NewElType}, ::Size{NewSize})`.
- - In some cases, a zero-parameter constructor, `MyStaticArray{...}()` for unintialized data
-   is assumed to exist.
-
-(see also `SVector`, `SMatrix`, `SArray`, `MVector`, `MMatrix`, `MArray`, `SizedArray`, `FieldVector`, `FieldMatrix` and `FieldArray`)
-"""
-abstract type StaticArray{S <: Tuple, T, N} <: AbstractArray{T, N} end
-const StaticScalar{T} = StaticArray{Tuple{}, T, 0}
-const StaticVector{N, T} = StaticArray{Tuple{N}, T, 1}
-const StaticMatrix{N, M, T} = StaticArray{Tuple{N, M}, T, 2}
-const StaticVecOrMat{T} = Union{StaticVector{<:Any, T}, StaticMatrix{<:Any, <:Any, T}}
-
 # Being a member of StaticMatrixLike, StaticVecOrMatLike, or StaticArrayLike implies that Size(A)
 # returns a static Size instance (none of the dimensions are Dynamic). The converse may not be true.
 # These are akin to aliases like StridedArray and in similarly bad taste, but the current approach
diff --git a/src/util.jl b/src/util.jl
diff --git a/test/core.jl b/test/core.jl
