remove potentially colliding exports, improve safety of as, mul => * overload

Author: rayegun

benchmarks/benchmarks.jl

@@ -98,9 +98,9 @@ function AxB_allbyrow(S, G, nthreads, sizerhs)
         gbset(:nthreads, n)
         #print burble for checking
         gbset(:burble, true)
-        mul(G, m2)
+        *(G, m2)
         gbset(:burble, false)
-        B = @benchmark mul($G, $m2)
+        B = @benchmark *($G, $m2)
         show(stdout, MIME("text/plain"), B)
         tratio = ratio(median(A), median(B))
         color = tratio.time >= 1.0 ? :green : :red
@@ -129,9 +129,9 @@ function AxB_ColxRow(S, G, nthreads, sizerhs)
         gbset(:nthreads, n)
         #print burble for checking
         gbset(:burble, true)
-        mul(G, m2)
+        *(G, m2)
         gbset(:burble, false)
-        B = @benchmark mul($G, $m2)
+        B = @benchmark *($G, $m2)
         show(stdout, MIME("text/plain"), B)
         tratio = ratio(median(A), median(B))
         color = tratio.time >= 1.0 ? :green : :red

benchmarks/benchmarks2.jl

@@ -58,7 +58,7 @@ function mxm(A::SuiteSparseGraphBLAS.GBArray, B::SuiteSparseGraphBLAS.GBArray; a
     if !accumdenseoutput
         printstyled(stdout, "\nC::GBArray = A::GBArray($Ao, $(size(A))) * B::GBArray($Bo, $(size(B)))\n")
         flush(stdout)
-        result = @gbbench mul(A, B)
+        result = @gbbench *(A, B)
     else
         printstyled(stdout, "\nC::GBArray += A::GBArray($Ao, $(size(A))) * B::GBArray($Bo, $(size(B)))\n")
         C = GBMatrix(zeros(eltype(A), size(A, 1), size(B, 2)))

docs/src/index.md

@@ -100,7 +100,7 @@ GraphBLAS operations are, where possible, methods of existing Julia functions li
 
 | GraphBLAS           | Operation                                                        | Julia                                      |
 |:--------------------|:----------------------------------------:                        |----------:                                 |
-|`mxm`, `mxv`, `vxm`  |``\bf C \langle M \rangle = C \odot AB``                          |`mul[!]` or `*`                             |
+|`mxm`, `mxv`, `vxm`  |``\bf C \langle M \rangle = C \odot AB``                          |`mul!` or `*`                             |
 |`eWiseMult`          |``\bf C \langle M \rangle = C \odot (A \otimes B)``               |`emul[!]` or `.` broadcasting               |
 |`eWiseAdd`           |``\bf C \langle M \rangle = C \odot (A \oplus  B)``               |`eadd[!]`                                   |
 |`extract`            |``\bf C \langle M \rangle = C \odot A(I,J)``                      |`extract[!]`, `getindex`       |
@@ -138,7 +138,7 @@ map(sin, A)
 Broadcasting functionality is also supported, `A .^ A` will lower to `emul(A, A, ^)`, and `sin.(A)` will lower to `map(sin, A)`.
 
 Matrix multiplication, which accepts a semiring, can be called with either `*(max, +)(A, B)` or
-`mul(A, B, (max, +))`.
+`*(A, B, (max, +))`.
 
 We can also use functions that are not already built into SuiteSparseGraphBLAS.jl:
 
@@ -168,15 +168,16 @@ Input `A` must be a square, symmetric matrix with any element type.
 We'll test it using the matrix from the GBArray section above, which has two triangles in its undirected form.
 
 ```@repl intro
+using SuiteSparseGraphBLAS: pair
 function cohen(A)
   U = select(triu, A)
   L = select(tril, A)
-  return reduce(+, mul(L, U, (+, pair); mask=A)) ÷ 2
+  return reduce(+, *(L, U, (+, pair); mask=A)) ÷ 2
 end
 
 function sandia(A)
   L = select(tril, A)
-  return reduce(+, mul(L, L, (+, pair); mask=L))
+  return reduce(+, *(L, L, (+, pair); mask=L))
 end
 
 M = eadd(A, A', +) #Make undirected/symmetric

docs/src/monoids.md

@@ -1,11 +1,11 @@
 # Monoids
 
 A monoid is made up of a set or domain $T$ and a binary operator $z = f(x, y)$ operating on the same domain, $T \times T \rightarrow T$.
-This binary operator must be associative, that is $f(a, f(b, c)) = f(f(a, b), c)$ is always true. Associativity is important for operations like `reduce` and the multiplication step of `mul`.
+This binary operator must be associative, that is $f(a, f(b, c)) = f(f(a, b), c)$ is always true. Associativity is important for operations like `reduce` and the multiplication step of `mul!`.
 
 The operator is also be equipped with an identity such that $f(x, 0) = f(0, x) = x$. Some monoids are equipped with a terminal or annihilator such that $z = f(z, x) \forall x$.
 
-Monoids are used primarily in the `reduce`(@ref) operation. Their other use is as a component of semirings in the [`mul`](@ref) operation.
+Monoids are used primarily in the `reduce`(@ref) operation. Their other use is as a component of semirings in the [`mul!`](@ref) operation.
 
 ## Built-Ins
 

docs/src/operations.md

@@ -5,7 +5,7 @@ GraphBLAS operations cover most of the typical linear algebra operations on arra
 ## Correspondence of GraphBLAS C functions and Julia functions
 | GraphBLAS           | Operation                                                        | Julia                                      |
 |:--------------------|:---------------------------------------------------------------: |----------------------------------------:   |
-|`mxm`, `mxv`, `vxm`  |``\bf C \langle M \rangle = C \odot AB``                          |`mul[!]` or `*`                             |
+|`mxm`, `mxv`, `vxm`  |``\bf C \langle M \rangle = C \odot AB``                          |`mul!` or `*`                             |
 |`eWiseMult`          |``\bf C \langle M \rangle = C \odot (A \otimes B)``               |`emul[!]` or `.` broadcasting               |
 |`eWiseAdd`           |``\bf C \langle M \rangle = C \odot (A \oplus  B)``               |`eadd[!]`                                   |
 |`extract`            |``\bf C \langle M \rangle = C \odot A(I,J)``                      |`extract[!]`, `getindex`                    |
@@ -73,7 +73,7 @@ The mask may also be complemented. These options are controlled by the `desc` ar
 All non-mutating operations below support a mutating form by adding an output array as the first argument as well as the `!` function suffix. 
 
 ```@docs
-mul
+*
 emul
 emul!
 eadd

docs/src/operators.md

@@ -14,7 +14,7 @@ For operations with a clear default operator they appear as the last positional
 - [`emul(A, B, op::Union{BinaryOp, Function})`](@ref emul)
 - [`eadd(A, B, op::Union{BinaryOp, Function})`](@ref eadd)
 - [`kron(A, B, op::Union{BinaryOp, Function})`](@ref kron)
-- [`mul(A, B, op::Union{Semiring, Tuple{Function, Function}})`](@ref mul)
+- [`*(A, B, op::Union{Semiring, Tuple{Function, Function}})`](@ref *)
 
 For other operations without a clear default operator they appear as the first argument:
 

docs/src/semirings.md

@@ -8,10 +8,10 @@ The second, $\otimes$ or "multiply", is a binary operator defined on $D_1 \times
 
 A semiring is denoted by a tuple $(D_1, D_2, D_3, \oplus, \otimes, \mathbb{0})$. However in the vast majority of cases $D_1 = D_2 = D_3$ so this is often shortened to $(\oplus, \otimes)$.
 
-Semirings are used in a single GraphBLAS operation, [`mul[!]`](@ref mul).
+Semirings are used in a single GraphBLAS operation, [`mul!`](@ref).
 
 ## Passing to Functions
 
-`mul[!]` is the only function which accepts semirings, and the best method to do so is a tuple of binary functions like `mul(A, B, (max, +))`. An operator form is also available as `*(min, +)(A, B)`.
+`mul!` and `*` are the only functions which accept semirings, and the best method to do so is a tuple of binary functions like `*(A, B, (max, +))`. An operator form is also available as `*(min, +)(A, B)`.
 
 Semiring objects may be constructed in a similar fashion: `Semiring(max, +)`.

docs/src/utilities.md

@@ -6,5 +6,5 @@ mask!
 gbset
 Descriptor
 SuiteSparseGraphBLAS.set_lib!
-clear!
+empty!
 ```

examples/triangle_centrality.jl

@@ -1,14 +1,15 @@
 using SuiteSparseGraphBLAS
+using SuiteSparseGraphBLAS: pair
 function triangle_centrality1(A)
-    T = mul(A, A', (+, *), mask=A)
+    T = *(A, A', (+, *), mask=A)
     y = reduce(+, T, dims=2)
     k = reduce(+, y)
-    return (3 * mul(A, y) - 2 * mul(T, y) .+ y) ./ k
+    return (3 * *(A, y) - 2 * *(T, y) .+ y) ./ k
 end
 
 function triangle_centrality(A)
-    T = mul(A, A', (+, pair), mask=A, Descriptor(structural_mask=true))
+    T = *(A, A', (+, pair), mask=A, Descriptor(structural_mask=true))
     y = reduce(+, T, dims=2)
     k = reduce(+, y)
-    return (3.0 * mul(A, y) .- (2.0 * mul(T, y, (+, second))) .+ y) ./ k
+    return (3.0 * *(A, y) .- (2.0 * *(T, y, (+, second))) .+ y) ./ k
 end

src/SuiteSparseGraphBLAS.jl

@@ -114,15 +114,17 @@ export lgamma, gamma, erf, erfc #reexport of SpecialFunctions.
 #UnaryOps not found in Julia/stdlibs.
 export frexpe, frexpx, positioni, positionj
 #BinaryOps not found in Julia/stdlibs.
-export second, rminus, pair, ∨, ∧, lxor, fmod, firsti,
-    firstj, secondi, secondj
+export firsti, firstj, secondi, secondj
+# unexported but important BinaryOps:
+# export second, rminus, pair, ∨, ∧, lxor, fmod
+
 #SelectOps not found in Julia/stdlibs
 export offdiag
 
-export clear!, extract, extract!, subassign!, assign!, hvcat! #array functions
+export extract, extract!, subassign!, assign!, hvcat! #array functions
 
 #operations
-export mul, select, select!, eadd, eadd!, emul, emul!, map, map!, gbtranspose, gbtranspose!,
+export select, select!, eadd, eadd!, emul, emul!, gbtranspose, gbtranspose!,
 gbrand, eunion, eunion!, mask, mask!, apply, apply!, setfill, setfill!
 # Reexports from LinAlg
 export diag, diagm, mul!, kron, kron!, transpose, reduce, tril, triu