new examples

docs/src/arrays.md

@@ -1,5 +1,10 @@
 # Array Types
 
+```@meta
+DocTestSetup = :(using SuiteSparseGraphBLAS, SparseArrays)
+DocTestFilters = [r"memory: \d+ bytes"]
+```
+
 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:
 
 ```
@@ -33,17 +38,38 @@ Users should rarely need to directly interact with the underlying storage format
 ### Construction
 
 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); fill = 0.0)
-x = GBMatrix(
-    rand(1:50_000, 5000), rand(1:500_000, 5000), 1, 500_000, 500_000
-)
+```jldoctest mat
+julia> x = GBMatrix{Bool}(20_000_000, 50_000)
+20000000x50000 GraphBLAS bool matrix, hypersparse by row, ints: 32/32/32
+  no entries, memory: 256 bytes
+
+julia> x = GBMatrix([[1,2] [3,4]])
+2x2 GraphBLAS int64_t matrix, full by col
+  4 entries, memory: 272 bytes
+
+    (1,1)   1
+    (2,1)   2
+    (1,2)   3
+    (2,2)   4
+
+julia> x = GBMatrix(sparse([1, 2, 3], [3, 1, 2], [1.0, 2.0, 3.0]); fill = 0.0)
+3x3 GraphBLAS double matrix, bitmap by col
+  3 entries, memory: 321 bytes
+
+    (2,1)    2
+    (3,2)    3
+    (1,3)    1
+
+julia> x = GBMatrix(
+           [1, 20_000, 400_000], [7, 30_000, 500_000], 1, 500_000, 500_000
+       )
+500000x500000 GraphBLAS int64_t matrix, hypersparse by row, ints: 32/32/32
+  3 entries, memory: 288 bytes
+  iso value:   1
+
+    (1,7)   1
+    (20000,30000)   1
+    (400000,500000)   1
 ```
 
 ```@docs
@@ -56,10 +82,26 @@ A `GBVector` is the one-dimensional equivalent of the `GBMatrix`, and internally
 
 ### Construction 
 
-```@repl mat
-v = GBVector{ComplexF32}(100)
-v = GBMatrix(rand(ComplexF64, 3); fill = nothing)
-v = GBVector(sprand(Bool, 100_000_000, 0.001))
+```jldoctest mat
+julia> v = GBVector{ComplexF32}(100)
+100x1 GraphBLAS float complex matrix, sparse by col, ints: 32/32/32
+  no entries, memory: 248 bytes
+
+julia> v = GBMatrix(ComplexF64[1, 2im, 3 + 4im]; fill = nothing)
+3x1 GraphBLAS double complex matrix, full by col
+  3 entries, memory: 288 bytes
+
+    (1,1)    1 + 0i
+    (2,1)    0 + 2i
+    (3,1)    3 + 4i
+
+julia> v = GBVector(sparsevec([1, 50_000_000, 100_000_000], true, 100_000_000))
+100000000x1 GraphBLAS bool matrix, sparse by col, ints: 64/64/64
+  3 entries, memory: 283 bytes
+
+    (1,1)   1
+    (50000000,1)   1
+    (100000000,1)   1
 ```
 
 ```@docs
@@ -81,15 +123,87 @@ The usual AbstractArray and SparseArray indexing capabilities are available. Inc
 
     However, many functions outside of GraphBLAS will throw an error if they receive `nothing` from an indexing operation. To accomodate these functions the user may set the fill value for an `AbstractGBArray` on construction and with [`setfill`](@ref) and [`setfill!`](@ref).
 
-```@repl mat
-A = GBMatrix([1,1,2,2,3,4,4,5,6,7,7,7], [2,4,5,7,6,1,3,6,3,3,4,5], [1:12...])
-SparseMatrixCSC(A)
-A[4]
-A[1,2]
-A[[1,3,5,7], :]
-A[1:2:7, :]
-A[:,:]
-A[:, 5]
+```jldoctest mat
+julia> A = GBMatrix([1,1,2,2,3,4,4,5,6,7,7,7], [2,4,5,7,6,1,3,6,3,3,4,5], [1:12...])
+7x7 GraphBLAS int64_t matrix, bitmap by row
+  12 entries, memory: 681 bytes
+
+    (1,2)   1
+    (1,4)   2
+    (2,5)   3
+    (2,7)   4
+    (3,6)   5
+    (4,1)   6
+    (4,3)   7
+    (5,6)   8
+    (6,3)   9
+    (7,3)   10
+    (7,4)   11
+    (7,5)   12
+
+julia> SparseMatrixCSC(A)
+7×7 SparseMatrixCSC{Int64, Int64} with 12 stored entries:
+ ⋅  1   ⋅   2   ⋅  ⋅  ⋅
+ ⋅  ⋅   ⋅   ⋅   3  ⋅  4
+ ⋅  ⋅   ⋅   ⋅   ⋅  5  ⋅
+ 6  ⋅   7   ⋅   ⋅  ⋅  ⋅
+ ⋅  ⋅   ⋅   ⋅   ⋅  8  ⋅
+ ⋅  ⋅   9   ⋅   ⋅  ⋅  ⋅
+ ⋅  ⋅  10  11  12  ⋅  ⋅
+
+julia> A[4]
+6
+
+julia> A[1,2]
+1
+
+julia> A[[1,3,5,7], :]
+4x7 GraphBLAS int64_t matrix, bitmap by row
+  7 entries, memory: 492 bytes
+
+    (1,2)   1
+    (1,4)   2
+    (2,6)   5
+    (3,6)   8
+    (4,3)   10
+    (4,4)   11
+    (4,5)   12
+
+julia> A[1:2:7, :]
+4x7 GraphBLAS int64_t matrix, bitmap by row
+  7 entries, memory: 492 bytes
+
+    (1,2)   1
+    (1,4)   2
+    (2,6)   5
+    (3,6)   8
+    (4,3)   10
+    (4,4)   11
+    (4,5)   12
+
+julia> A[:,:]
+7x7 GraphBLAS int64_t matrix, bitmap by row
+  12 entries, memory: 681 bytes
+
+    (1,2)   1
+    (1,4)   2
+    (2,5)   3
+    (2,7)   4
+    (3,6)   5
+    (4,1)   6
+    (4,3)   7
+    (5,6)   8
+    (6,3)   9
+    (7,3)   10
+    (7,4)   11
+    (7,5)   12
+
+julia> A[:, 5]
+7x1 GraphBLAS int64_t matrix, bitmap by col
+  2 entries, memory: 304 bytes
+
+    (2,1)   3
+    (7,1)   12
 ```
 
 The functionality illustrated above extends to `GBVector` as well.

docs/src/binaryops.md

@@ -1,35 +1,94 @@
 # Binary Operators
 
+```@meta
+DocTestSetup = :(using SuiteSparseGraphBLAS)
+DocTestFilters = [r"memory: \d+ bytes", r"Ptr{.*}\(0x[0-9a-f]+\)"]
+```
+
 Binary operators are defined on three domains $D_1 \times D_2 \rightarrow D_3$.
 However, the vast majority of binary operators are defined on a single domain.
 
 `BinaryOp`s are in almost every GraphBLAS operation. They are the primary `op` argument for [`emul`](@ref), [`eadd`](@ref), and [`apply`](@ref). `BinaryOp`s which are also monoids may be used in [`reduce`](@ref). And every GraphBLAS operation which takes an `accum` keyword argument accepts a `BinaryOp`.
 
 In almost all cases you should pass Julia functions, which will be mapped to built-in operators, or used to create a new user-defined operator.
 
-```@repl
-using SuiteSparseGraphBLAS
+```jldoctest
+julia> x = GBMatrix([[1,2] [3,4]])
+2x2 GraphBLAS int64_t matrix, full by col
+  4 entries, memory: 272 bytes
+
+    (1,1)   1
+    (2,1)   2
+    (1,2)   3
+    (2,2)   4
+
+julia> x .+ x
+2x2 GraphBLAS int64_t matrix, full by row
+  4 entries, memory: 272 bytes
+
+    (1,1)   2
+    (1,2)   6
+    (2,1)   4
+    (2,2)   8
+
+julia> eadd(x, x, +)
+2x2 GraphBLAS int64_t matrix, full by row
+  4 entries, memory: 272 bytes
+
+    (1,1)   2
+    (1,2)   6
+    (2,1)   4
+    (2,2)   8
+
+julia> x .^ x
+2x2 GraphBLAS int64_t matrix, full by row
+  4 entries, memory: 272 bytes
+
+    (1,1)   1
+    (1,2)   27
+    (2,1)   4
+    (2,2)   256
+
+julia> emul(x, x, ^)
+2x2 GraphBLAS int64_t matrix, full by row
+  4 entries, memory: 272 bytes
+
+    (1,1)   1
+    (1,2)   27
+    (2,1)   4
+    (2,2)   256
 
-x = GBMatrix([[1,2] [3,4]])
+julia> x2 = Float64.(x)
+2x2 GraphBLAS double matrix, full by col
+  4 entries, memory: 272 bytes
 
-x .+ x
-eadd(x, x, +)
+    (1,1)    1
+    (2,1)    2
+    (1,2)    3
+    (2,2)    4
 
-x .^ x
-emul(x, x, ^)
+julia> eadd!(x2, x, x, +; accum=/)
+2x2 GraphBLAS double matrix, full by col
+  4 entries, memory: 272 bytes
 
-x2 = Float64.(x)
-eadd!(x2, x, x, +; accum=/)
+    (1,1)    0.5
+    (2,1)    0.5
+    (1,2)    0.5
+    (2,2)    0.5
 ```
 
 Internally functions are lowered like this:
 
-```@repl
-using SuiteSparseGraphBLAS
+```jldoctest
+julia> typedop = binaryop(+, Int64, Int64)
+SuiteSparseGraphBLAS.TypedBinaryOperator{typeof(+), Int64, Int64, Int64}(true, true, "GrB_PLUS_INT64", Ptr{SuiteSparseGraphBLAS.LibGraphBLAS.GB_BinaryOp_opaque}(0x0000736051461e20), +, nothing)
 
-typedop = binaryop(+, Int64, Int64)
+julia> eadd(GBVector([1,2]), GBVector([3,4]), typedop)
+2x1 GraphBLAS int64_t matrix, full by col
+  2 entries, memory: 256 bytes
 
-eadd(GBVector([1,2]), GBVector([3,4]), typedop)
+    (1,1)   4
+    (2,1)   6
 ```
 
 ## Built-Ins