early changes to arrays docs, reduce extract/getindex/setindex/assign verbosity in code

Author: rayegun

docs/Project.toml

@@ -1,4 +1,4 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316"
-SuiteSparseGraphBLAS = "c2e53296-7b14-11e9-1210-bddfa8111e1d"
+SuiteSparseGraphBLAS = "c2e53296-7b14-11e9-1210-bddfa8111e1d"

docs/src/arrays.md

@@ -1,39 +1,52 @@
 # Array Types
 
-There are two primary datastructures in in `SuiteSparseGraphBLAS.jl`: the `GBVector` and `GBMatrix`.
+There are two primary array types in SuiteSparseGraphBLAS.jl: [`GBVector`](@ref) and [`GBMatrix`](@ref), as well as a few specialized versions of those array types. The full type hierarchy is:
 
-Both types currently implement most of the `AbstractArray` interface and part of the `SparseArrays`
-interface. 
+```
+AbstractGBArray{T, N, F} <: AbstractSparseArray{T, N}
+ ├ N = 2 ─ AbstractGBMatrix{T, F} 
+ │   ├─ GBMatrix{T, F}
+ │   └─ OrientedGBMatrix{T, F, O}
+ └ N = 1 ─ AbstractGBVector{T, F}
+     └─ GBVector{T, F}
+```
+
+The `T` parameter is the element type of the array, `N` is the dimensionality, `F` is the type of the fill value (often `Nothing` or `T`). The [`OrientedGBMatrix`](@ref) restricts the orientation to the parameter `O` which is either `ByRow()` or `ByCol()`. 
 
-## Matrix Construction
+All of these types attempt to implement most of the `AbstractArray` interface, and the relevant parts of the `SparseArrays` interface.
+
+## GBMatrix
+
+There are several methods to construct GBArrays. Shown here are empty construction, conversion from a dense matrix and a sparse matrix, and coordinate form with uniform or *iso* coefficients. 
 ```@setup mat
 using SuiteSparseGraphBLAS
 using SparseArrays
 ```
 ```@repl mat
 x = GBMatrix{Bool}(20_000_000, 50_000)
 x = GBMatrix([[1,2] [3,4]])
-x = GBMatrix(sprand(100, 100, 0.5))
-x = GBMatrix(rand(1:50_000, 5000), rand(1:500_000, 5000), 1; ncols = 500_000, nrows = 500_000)
+x = GBMatrix(sprand(100, 100, 0.5); fill = 0.0)
+x = GBMatrix(
+    rand(1:50_000, 5000), rand(1:500_000, 5000), 1; 
+    ncols = 500_000, nrows = 500_000
+)
 ```
 
 ```@docs
 GBMatrix
 SuiteSparseGraphBLAS.GBMatrix(::Matrix)
-SuiteSparseGraphBLAS.GBMatrix(::SparseMatrixCSC)
 ```
-Conversion back to matrices, sparse or dense, is also supported.
-## Vector Construction
+
+## GBVector
 ```@repl mat
 v = GBVector{ComplexF32}(100)
-v = GBMatrix(rand(ComplexF64, 3))
+v = GBMatrix(rand(ComplexF64, 3); fill = nothing)
 v = GBVector(sprand(Bool, 100_000_000, 0.001))
 ```
 
 ```@docs
 GBVector
 SuiteSparseGraphBLAS.GBVector(::Vector)
-SuiteSparseGraphBLAS.GBVector(::AbstractVector{<:Integer}, ::AbstractVector)
 ```
 
 # Indexing

src/abstractgbarray.jl

@@ -241,6 +241,7 @@ function subassign!(C::AbstractGBArray, x, I, J;
     _subassign(C, x, I, ni, J, nj, mask, getaccum(accum, eltype(C)), desc)
     increment!(I)
     increment!(J)
+    return C
 end
 
 function subassign!(C::AbstractGBArray, x::AbstractArray, I, J;
@@ -294,39 +295,22 @@ end
 function assign!(C::AbstractGBArray, x, I, J;
     mask = nothing, accum = nothing, desc = nothing
 )
+    I, ni = idx(I)
+    J, nj = idx(J)
     I = decrement!(I)
     J = decrement!(J)
     desc = _handledescriptor(desc)
     _assign(gbpointer(C), x, I, ni, J, nj, mask, getaccum(accum, eltype(C)), desc)
     increment!(I)
     increment!(J)
-end
-
-# setindex! uses subassign rather than assign.
-function Base.setindex!(
-    C::AbstractGBMatrix, A, ::Colon, J;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    subassign!(C, A, ALL, J; mask, accum, desc)
-end
-function Base.setindex!(
-    C::AbstractGBMatrix, A, I, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    subassign!(C, A, I, ALL; mask, accum, desc)
-end
-function Base.setindex!(
-    C::AbstractGBMatrix, A, ::Colon, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    subassign!(C, A, ALL, ALL; mask, accum, desc)
+    return C
 end
 
 function Base.setindex!(
     C::AbstractGBMatrix,
     A,
-    I::Union{Vector, UnitRange, StepRange, Number},
-    J::Union{Vector, UnitRange, StepRange, Number};
+    I::Union{Vector, UnitRange, StepRange, Number, Colon},
+    J::Union{Vector, UnitRange, StepRange, Number, Colon};
     mask = nothing,
     accum = nothing,
     desc = nothing
@@ -504,13 +488,6 @@ function assign!(w::AbstractGBVector{T, F}, u, I; mask = nothing, accum = nothin
     return assign!(GBMatrix{T, F}(w.p, w.fill), u, I, UInt64[1]; mask, accum, desc)
 end
 
-function Base.setindex!(
-    u::AbstractGBVector, x, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    subassign!(u, x, ALL; mask, accum, desc)
-    return nothing
-end
 # silly overload to help a bit with broadcasting.
 function Base.setindex!(
     u::AbstractGBVector, x, I::Union{Vector, UnitRange, StepRange, Colon}, ::Colon;
@@ -519,7 +496,7 @@ function Base.setindex!(
     Base.setindex!(u, x, I; mask, accum, desc)
 end
 function Base.setindex!(
-    u::AbstractGBVector, x, I::Union{Vector, UnitRange, StepRange};
+    u::AbstractGBVector, x, I::Union{Vector, UnitRange, StepRange, Colon};
     mask = nothing, accum = nothing, desc = nothing
 )
     subassign!(u, x, I; mask, accum, desc)
@@ -531,20 +508,7 @@ function Base.show(io::IO, ::MIME"text/plain", A::AbstractGBArray) #fallback pri
 end
 
 function Base.getindex(
-    A::AbstractGBMatrix, i, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract(A, i, ALL; mask, accum, desc)
-end
-function Base.getindex(
-    A::AbstractGBMatrix, ::Colon, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract(A, ALL, ALL; mask, accum, desc)
-end
-
-function Base.getindex(
-    A::AbstractGBMatrix, i::Union{Vector, UnitRange, StepRange, Number}, j::Union{Vector, UnitRange, StepRange, Number};
+    A::AbstractGBMatrix, i::Union{Vector, UnitRange, StepRange, Number, Colon}, j::Union{Vector, UnitRange, StepRange, Number, Colon};
     mask = nothing, accum = nothing, desc = nothing
 )
     return extract(A, i, j; mask, accum, desc)

src/import.jl

@@ -63,7 +63,7 @@ end
 
 Create a GBMatrix from a SparseArrays.SparseMatrixCSC `S`.
 
-Note, that unlike other methods of construction, the resulting matrix will be held by column.
+Note, that unlike most other methods of construction, the resulting matrix will be held by column.
 Use `gbset(A, :format, :byrow)` to switch to row orientation.
 """
 function GBMatrix(S::SparseMatrixCSC{T}; fill::F = nothing) where {T, F}
@@ -187,6 +187,8 @@ end
     GBMatrix(M::Matrix)
 
 Create a GBMatrix from a Julia dense matrix.
+Note, that unlike other methods of construction, the resulting matrix will be held by column.
+Use `gbset(A, :format, :byrow)` to switch to row orientation.
 """
 function GBMatrix(M::Union{AbstractVector{T}, AbstractMatrix{T}}; fill::F = nothing) where {T, F}
     if M isa AbstractVector && !(M isa Vector)

src/indexutils.jl

@@ -7,6 +7,9 @@ scalar index like [`extractElement`].
 """
 function idx(I)
     # TODO. Do better here, and minimize manual idx management in rest of library.
+    if I isa Colon
+        I = ALL
+    end
     if I == ALL
         return I, 0 #ni doesn't matter if I=ALL
     elseif I isa UnitRange

src/matrix.jl

@@ -19,7 +19,7 @@ GBMatrix{T}(size::Tuple{Base.OneTo, Base.OneTo}; fill = nothing) where {T} =
     GBMatrix{T}(size[1].stop, size[2].stop; fill)
 
 """
-    GBMatrix(I, J, X; combine = +, nrows = maximum(I), ncols = maximum(J))
+    GBMatrix(I, J, X; combine = +, nrows = maximum(I), ncols = maximum(J); fill = nothing)
 
 Create an nrows x ncols GBMatrix M such that M[I[k], J[k]] = X[k]. The combine function defaults
 to `|` for booleans and `+` for nonbooleans.
@@ -38,7 +38,7 @@ end
 
 #iso constructors
 """
-    GBMatrix(I, J, x; nrows = maximum(I), ncols = maximum(J))
+    GBMatrix(I, J, x; nrows = maximum(I), ncols = maximum(J); fill = nothing)
 
 Create an nrows x ncols GBMatrix M such that M[I[k], J[k]] = x.
 The resulting matrix is "iso-valued" such that it only stores `x` once rather than once for

src/operations/extract.jl

@@ -4,6 +4,8 @@
 Determine the size of the output for an operation like extract or range-based indexing.
 """
 function _outlength(A, I, J)
+    I isa Colon && (I = ALL)
+    J isa Colon && (J = ALL)
     if I == ALL
         Ilen = size(A, 1)
     else
@@ -18,6 +20,7 @@ function _outlength(A, I, J)
 end
 
 function _outlength(u, I)
+    I isa Colon && (I = ALL)
     if I == ALL
         wlen = size(u)
     else
@@ -70,28 +73,6 @@ function extract!(
     J isa Vector && increment!(J)
     return C
 end
-
-function extract!(
-    C::AbstractGBMatrix, A::GBMatOrTranspose, ::Colon, J;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract!(C, A, ALL, J; mask, accum, desc)
-end
-
-function extract!(
-    C::AbstractGBMatrix, A::GBMatOrTranspose, I, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract!(C, A, I, ALL; mask, accum, desc)
-end
-
-function extract!(
-    C::AbstractGBMatrix, A::GBMatOrTranspose, ::Colon, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract!(C, A, ALL, ALL; mask, accum, desc)
-end
-
 """
     extract(A::GBMatOrTranspose, I, J; kwargs...)::GBMatrix
     extract(A::GBVector, I; kwargs...)::GBVector
@@ -126,34 +107,6 @@ function extract(
     return extract!(C, A, I, J; mask, accum, desc)
 end
 
-function extract(
-    A::GBMatOrTranspose, ::Colon, J;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract(A, ALL, J; mask, accum, desc)
-end
-
-function extract(
-    A::GBMatOrTranspose, I, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract(A, I, ALL; mask, accum, desc)
-end
-
-function extract(
-    A::GBMatOrTranspose, ::Colon, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract(A, ALL, ALL; mask, accum, desc)
-end
-
-function Base.getindex(
-    A::GBMatOrTranspose, ::Colon, j;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract(A, ALL, j; mask, accum, desc)
-end
-
 function extract!(
     w::AbstractGBVector, u::AbstractGBVector, I;
     mask = nothing, accum = nothing, desc = nothing
@@ -167,22 +120,11 @@ function extract!(
     return w
 end
 
-function extract!(
-    w::GBVector, u::GBVector, ::Colon;
-    mask = nothing, accum = nothing, desc = nothing
-)
-    return extract!(w, u, ALL; mask, accum, desc)
-end
-
 function extract(
     u::GBVector, I;
     mask = nothing, accum = nothing, desc = nothing
 )
     wlen = _outlength(u, I)
     w = similar(u, wlen)
     return extract!(w, u, I; mask, accum, desc)
-end
-
-function extract(u::GBVector, ::Colon; mask = nothing, accum = nothing, desc = nothing)
-    extract(u, ALL; mask, accum, desc)
-end
+end

src/print.jl

@@ -38,7 +38,7 @@ function gxbstring(x, name = "", level::LibGraphBLAS.GxB_Print_Level = LibGraphB
         seekstart(f)
         x = read(f, String)
         close(cf)
-        x
+        lstrip(x)
     end
     return str
 end

src/types.jl

@@ -249,10 +249,11 @@ mutable struct GBScalar{T}
 end
 
 """
-    GBVector{T} <: AbstractSparseArray{T, UInt64, 1}
+    GBVector{T, F} <: AbstractSparseArray{T, UInt64, 1}
 
-One-dimensional GraphBLAS array with elements of type T. Internal representation is
-specified as opaque, but may be either a dense array, bitmap array, or
+One-dimensional GraphBLAS array with elements of type T. `F` is the type of the fill-value, 
+which is typically `Nothing` or `T`. 
+Internal representation is specified as opaque, but may be either a dense vector, bitmap vector, or 
 compressed sparse vector.
 
 See also: [`GBMatrix`](@ref).
@@ -263,11 +264,12 @@ mutable struct GBVector{T, F} <: AbstractGBVector{T, F}
 end
 
 """
-    GBMatrix{T} <: AbstractSparseArray{T, UInt64, 2}
+    GBMatrix{T, F} <: AbstractSparseArray{T, UInt64, 2}
 
-Two-dimensional GraphBLAS array with elements of type T. Internal representation is
-specified as opaque, but in this implementation is stored as one of the following in either
-row or column orientation:
+Two-dimensional GraphBLAS array with elements of type `T`. `F` is the type of the fill-value, 
+which is typically `Nothing` or `T`. 
+Internal representation is specified as opaque, but in this implementation is stored as one of 
+the following in either row or column orientation:
 
     1. Dense
     2. Bitmap

src/vector.jl

@@ -19,7 +19,7 @@ GBVector{T}(nrows::Base.OneTo; fill = nothing) where {T} =
 GBVector{T}(nrows::Tuple{Base.OneTo,}; fill = nothing) where {T} = GBVector{T}(first(nrows); fill)
 
 """
-    GBVector(I::AbstractVector, X::AbstractVector{T})
+    GBVector(I::AbstractVector, X::AbstractVector{T}; fill = nothing)
 
 Create a GBVector from a vector of indices `I` and a vector of values `X`.
 """
@@ -33,7 +33,7 @@ end
 
 #iso valued constructors.
 """
-    GBVector(I, x; nrows = maximum(I))
+    GBVector(I, x; nrows = maximum(I) fill = nothing)
 
 Create an `n` length GBVector `v` such that `M[I[k]] = x`.
 The resulting vector is "iso-valued" such that it only stores `x` once rather than once for
@@ -47,7 +47,7 @@ function GBVector(I::AbstractVector{U}, x::T;
 end
 
 """
-    GBVector(n, x)
+    GBVector(n, x; fill = nothing)
 
 Create an `n` length dense GBVector `v` such that M[I[k]] = x.
 The resulting vector is "iso-valued" such that it only stores `x` once rather than once for