Skip to content

Commit 565495b

Browse files
abhinavmehndirattaabhinavmehndiratta
committed
add examples in documentation for basic matrix methods
1 parent 4135675 commit 565495b

File tree

1 file changed

+252
-0
lines changed

1 file changed

+252
-0
lines changed

‎src/Object_Methods/Matrix_Methods.jl

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,20 @@
22
GrB_Matrix_new(A, type, nrows, ncols)
33
44
Create a new matrix with specified domain and dimensions.
5+
6+
# Examples
7+
```jldoctest
8+
julia> using SuiteSparseGraphBLAS
9+
10+
julia> GrB_init(GrB_NONBLOCKING)
11+
GrB_SUCCESS::GrB_Info = 0
12+
13+
julia> MAT = GrB_Matrix()
14+
GrB_Matrix
15+
16+
julia> GrB_Matrix_new(MAT, GrB_INT8, 4, 4)
17+
GrB_SUCCESS::GrB_Info = 0
18+
```
519
"""
620
function GrB_Matrix_new(A::GrB_Matrix, type::GrB_Type, nrows::T, ncols::T) where T <: GrB_Index
721
A_ptr = pointer_from_objref(A)
@@ -20,6 +34,44 @@ end
2034
GrB_Matrix_build(C, I, J, X, nvals, dup)
2135
2236
Store elements from tuples into a vector.
37+
38+
# Examples
39+
```jldoctest
40+
julia> using SuiteSparseGraphBLAS
41+
42+
julia> GrB_init(GrB_NONBLOCKING)
43+
GrB_SUCCESS::GrB_Info = 0
44+
45+
julia> MAT = GrB_Matrix()
46+
GrB_Matrix
47+
48+
julia> GrB_Matrix_new(MAT, GrB_INT8, 4, 4)
49+
GrB_SUCCESS::GrB_Info = 0
50+
51+
julia> I = [1, 2, 2, 2, 3]; J = [1, 2, 1, 3, 3]; X = Int8[2, 3, 4, 5, 6]; n = 5;
52+
53+
julia> GrB_Matrix_build(MAT, I, J, X, n, GrB_FIRST_INT8)
54+
GrB_SUCCESS::GrB_Info = 0
55+
56+
julia> @GxB_Matrix_fprint(MAT, GxB_COMPLETE)
57+
58+
GraphBLAS matrix: MAT
59+
nrows: 4 ncols: 4 max # entries: 5
60+
format: standard CSR vlen: 4 nvec_nonempty: 3 nvec: 4 plen: 4 vdim: 4
61+
hyper_ratio 0.0625
62+
GraphBLAS type: int8_t size: 1
63+
number of entries: 5
64+
row: 1 : 1 entries [0:0]
65+
column 1: int8 2
66+
row: 2 : 3 entries [1:3]
67+
column 1: int8 4
68+
column 2: int8 3
69+
column 3: int8 5
70+
row: 3 : 1 entries [4:4]
71+
column 3: int8 6
72+
73+
74+
```
2375
"""
2476
function GrB_Matrix_build(C::GrB_Matrix, I::Vector{U}, J::Vector{U}, X::Vector{T}, nvals::U, dup::GrB_BinaryOp) where{U <: GrB_Index, T <: valid_types}
2577
I_ptr = pointer(I)
@@ -41,6 +93,23 @@ end
4193
4294
Return the number of rows in a matrix if successful.
4395
Else return value of type GrB Info.
96+
97+
# Examples
98+
```jldoctest
99+
julia> using SuiteSparseGraphBLAS
100+
101+
julia> GrB_init(GrB_NONBLOCKING)
102+
GrB_SUCCESS::GrB_Info = 0
103+
104+
julia> MAT = GrB_Matrix()
105+
GrB_Matrix
106+
107+
julia> GrB_Matrix_new(MAT, GrB_INT8, 4, 4)
108+
GrB_SUCCESS::GrB_Info = 0
109+
110+
julia> GrB_Matrix_nrows(MAT)
111+
4
112+
```
44113
"""
45114
function GrB_Matrix_nrows(A::GrB_Matrix)
46115
nrows = Ref(UInt64(0))
@@ -61,6 +130,23 @@ end
61130
62131
Return the number of columns in a matrix if successful.
63132
Else return value of type GrB Info.
133+
134+
# Examples
135+
```jldoctest
136+
julia> using SuiteSparseGraphBLAS
137+
138+
julia> GrB_init(GrB_NONBLOCKING)
139+
GrB_SUCCESS::GrB_Info = 0
140+
141+
julia> MAT = GrB_Matrix()
142+
GrB_Matrix
143+
144+
julia> GrB_Matrix_new(MAT, GrB_INT8, 4, 4)
145+
GrB_SUCCESS::GrB_Info = 0
146+
147+
julia> GrB_Matrix_ncols(MAT)
148+
4
149+
```
64150
"""
65151
function GrB_Matrix_ncols(A::GrB_Matrix)
66152
ncols = Ref(UInt64(0))
@@ -81,6 +167,28 @@ end
81167
82168
Return the number of stored elements in a matrix if successful.
83169
Else return value of type GrB Info.
170+
171+
# Examples
172+
```jldoctest
173+
julia> using SuiteSparseGraphBLAS
174+
175+
julia> GrB_init(GrB_NONBLOCKING)
176+
GrB_SUCCESS::GrB_Info = 0
177+
178+
julia> MAT = GrB_Matrix()
179+
GrB_Matrix
180+
181+
julia> GrB_Matrix_new(MAT, GrB_INT8, 4, 4)
182+
GrB_SUCCESS::GrB_Info = 0
183+
184+
julia> I = [1, 2, 2, 2, 3]; J = [1, 2, 1, 3, 3]; X = Int8[2, 3, 4, 5, 6]; n = 5;
185+
186+
julia> GrB_Matrix_build(MAT, I, J, X, n, GrB_FIRST_INT8)
187+
GrB_SUCCESS::GrB_Info = 0
188+
189+
julia> GrB_Matrix_nvals(MAT)
190+
5
191+
```
84192
"""
85193
function GrB_Matrix_nvals(A::GrB_Matrix)
86194
nvals = Ref(UInt64(0))
@@ -100,6 +208,49 @@ end
100208
GrB_Matrix_dup(C, A)
101209
102210
Create a new matrix with the same domain, dimensions, and contents as another matrix.
211+
212+
# Examples
213+
```jldoctest
214+
julia> using SuiteSparseGraphBLAS
215+
216+
julia> GrB_init(GrB_NONBLOCKING)
217+
GrB_SUCCESS::GrB_Info = 0
218+
219+
julia> MAT = GrB_Matrix()
220+
GrB_Matrix
221+
222+
julia> GrB_Matrix_new(MAT, GrB_INT8, 4, 4)
223+
GrB_SUCCESS::GrB_Info = 0
224+
225+
julia> I = [1, 2, 2, 2, 3]; J = [1, 2, 1, 3, 3]; X = Int8[2, 3, 4, 5, 6]; n = 5;
226+
227+
julia> GrB_Matrix_build(MAT, I, J, X, n, GrB_FIRST_INT8)
228+
GrB_SUCCESS::GrB_Info = 0
229+
230+
julia> B = GrB_Matrix()
231+
GrB_Matrix
232+
233+
julia> GrB_Matrix_dup(B, MAT)
234+
GrB_SUCCESS::GrB_Info = 0
235+
236+
julia> @GxB_Matrix_fprint(B, GxB_SHORT)
237+
238+
GraphBLAS matrix: B
239+
nrows: 4 ncols: 4 max # entries: 5
240+
format: standard CSR vlen: 4 nvec_nonempty: 3 nvec: 4 plen: 4 vdim: 4
241+
hyper_ratio 0.0625
242+
GraphBLAS type: int8_t size: 1
243+
number of entries: 5
244+
row: 1 : 1 entries [0:0]
245+
column 1: int8 2
246+
row: 2 : 3 entries [1:3]
247+
column 1: int8 4
248+
column 2: int8 3
249+
column 3: int8 5
250+
row: 3 : 1 entries [4:4]
251+
column 3: int8 6
252+
253+
```
103254
"""
104255
function GrB_Matrix_dup(C::GrB_Matrix, A::GrB_Matrix)
105256
C_ptr = pointer_from_objref(C)
@@ -118,6 +269,34 @@ end
118269
GrB_Matrix_clear(A)
119270
120271
Remove all elements from a matrix.
272+
273+
# Examples
274+
```jldoctest
275+
julia> using SuiteSparseGraphBLAS
276+
277+
julia> GrB_init(GrB_NONBLOCKING)
278+
GrB_SUCCESS::GrB_Info = 0
279+
280+
julia> MAT = GrB_Matrix()
281+
GrB_Matrix
282+
283+
julia> GrB_Matrix_new(MAT, GrB_INT8, 4, 4)
284+
GrB_SUCCESS::GrB_Info = 0
285+
286+
julia> I = [1, 2, 2, 2, 3]; J = [1, 2, 1, 3, 3]; X = Int8[2, 3, 4, 5, 6]; n = 5;
287+
288+
julia> GrB_Matrix_build(MAT, I, J, X, n, GrB_FIRST_INT8)
289+
GrB_SUCCESS::GrB_Info = 0
290+
291+
julia> GrB_Matrix_nvals(MAT)
292+
5
293+
294+
julia> GrB_Matrix_clear(MAT)
295+
GrB_SUCCESS::GrB_Info = 0
296+
297+
julia> GrB_Matrix_nvals(MAT)
298+
0
299+
```
121300
"""
122301
function GrB_Matrix_clear(A::GrB_Matrix)
123302
return GrB_Info(
@@ -134,6 +313,35 @@ end
134313
GrB_Matrix_setElement(C, X, I, J)
135314
136315
Set one element of a matrix to a given value, C[I][J] = X.
316+
317+
# Examples
318+
```jldoctest
319+
julia> using SuiteSparseGraphBLAS
320+
321+
julia> GrB_init(GrB_NONBLOCKING)
322+
GrB_SUCCESS::GrB_Info = 0
323+
324+
julia> MAT = GrB_Matrix()
325+
GrB_Matrix
326+
327+
julia> GrB_Matrix_new(MAT, GrB_INT8, 4, 4)
328+
GrB_SUCCESS::GrB_Info = 0
329+
330+
julia> I = [1, 2, 2, 2, 3]; J = [1, 2, 1, 3, 3]; X = Int8[2, 3, 4, 5, 6]; n = 5;
331+
332+
333+
julia> GrB_Matrix_build(MAT, I, J, X, n, GrB_FIRST_INT8)
334+
GrB_SUCCESS::GrB_Info = 0
335+
336+
julia> GrB_Matrix_extractElement(MAT, 1, 1)
337+
2
338+
339+
julia> GrB_Matrix_setElement(MAT, Int8(7), 1, 1)
340+
GrB_SUCCESS::GrB_Info = 0
341+
342+
julia> GrB_Matrix_extractElement(MAT, 1, 1)
343+
7
344+
```
137345
"""
138346
function GrB_Matrix_setElement(C::GrB_Matrix, X::T, I::U, J::U) where {U <: GrB_Index, T <: valid_int_types}
139347
fn_name = "GrB_Matrix_setElement_" * get_suffix(T)
@@ -176,6 +384,28 @@ end
176384
177385
Return element of a vector at a given index (A[row_index][col_index]) if successful.
178386
Else return value of type GrB Info.
387+
388+
# Examples
389+
```jldoctest
390+
julia> using SuiteSparseGraphBLAS
391+
392+
julia> GrB_init(GrB_NONBLOCKING)
393+
GrB_SUCCESS::GrB_Info = 0
394+
395+
julia> MAT = GrB_Matrix()
396+
GrB_Matrix
397+
398+
julia> GrB_Matrix_new(MAT, GrB_INT8, 4, 4)
399+
GrB_SUCCESS::GrB_Info = 0
400+
401+
julia> I = [1, 2, 2, 2, 3]; J = [1, 2, 1, 3, 3]; X = Int8[2, 3, 4, 5, 6]; n = 5;
402+
403+
julia> GrB_Matrix_build(MAT, I, J, X, n, GrB_FIRST_INT8)
404+
GrB_SUCCESS::GrB_Info = 0
405+
406+
julia> GrB_Matrix_extractElement(MAT, 1, 1)
407+
2
408+
```
179409
"""
180410
function GrB_Matrix_extractElement(A::GrB_Matrix, row_index::U, col_index::U) where U <: GrB_Index
181411
res, A_type = GxB_Matrix_type(A)
@@ -200,6 +430,28 @@ end
200430
GrB_Matrix_extractTuples(A)
201431
202432
Return tuples stored in a matrix.
433+
434+
# Examples
435+
```jldoctest
436+
julia> using SuiteSparseGraphBLAS
437+
438+
julia> GrB_init(GrB_NONBLOCKING)
439+
GrB_SUCCESS::GrB_Info = 0
440+
441+
julia> MAT = GrB_Matrix()
442+
GrB_Matrix
443+
444+
julia> GrB_Matrix_new(MAT, GrB_INT8, 4, 4)
445+
GrB_SUCCESS::GrB_Info = 0
446+
447+
julia> I = [1, 2, 2, 2, 3]; J = [1, 2, 1, 3, 3]; X = Int8[2, 3, 4, 5, 6]; n = 5;
448+
449+
julia> GrB_Matrix_build(MAT, I, J, X, n, GrB_FIRST_INT8)
450+
GrB_SUCCESS::GrB_Info = 0
451+
452+
julia> GrB_Matrix_extractTuples(MAT)
453+
([1, 2, 2, 2, 3], [1, 1, 2, 3, 3], Int8[2, 4, 3, 5, 6])
454+
```
203455
"""
204456
function GrB_Matrix_extractTuples(A::GrB_Matrix)
205457
res, A_type = GxB_Matrix_type(A)

0 commit comments

Comments
 (0)