csvbinmatrix 0.8.0

Binary matrix Compressed Sparse Vector
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

# Input Output Operations

This module defines the input and output operations for [`CSVBinaryMatrix`].

[`CSVBinaryMatrix`]: crate::matrix::CSVBinaryMatrix

For the following we consider this matrix:

```rust
use csvbinmatrix::prelude::CSVBinaryMatrix;

CSVBinaryMatrix::try_from(&[
    [0, 0, 0],
    [0, 0, 1],
    [0, 1, 1],
    [1, 1, 1],
]).unwrap();
```

## Write to a file without consuming the matrix

```rust
# use csvbinmatrix::prelude::CSVBinaryMatrix;
#
# let matrix = CSVBinaryMatrix::try_from(&[
#     [0, 0, 0],
#     [0, 0, 1],
#     [0, 1, 1],
#     [1, 1, 1],
# ]).unwrap();
#
match matrix.to_file("mymatrix.csvbm") {
    Ok(_) => println!("[INFO] File created"),
    Err(e) => println!("[ERROR] creating file fails: {e}"),
}
# std::fs::remove_file("mymatrix.csvbm").unwrap_or(());

// You can still use `matrix`
assert_eq!(matrix.number_of_ones(), 6);
```

## Efficiently write and read a file with consuming the matrix

```rust
use csvbinmatrix::prelude::CSVBinaryMatrix;
#
# let matrix = CSVBinaryMatrix::try_from(&[
#     [0, 0, 0],
#     [0, 0, 1],
#     [0, 1, 1],
#     [1, 1, 1],
# ]).unwrap();
#

let expected_matrix_from_file = matrix.clone();

match matrix.into_file("mymatrix.csvbm") {
    Ok(_) => println!("[INFO] File created"),
    Err(e) => println!("[ERROR] creating file fails: {e}"),
}

// `matrix` is consumed so you cannot use it anymore.

let matrix_from_file = match CSVBinaryMatrix::try_from_file("mymatrix.csvbm") {
    Ok(m) => m,
    Err(e) => panic!("[ERROR] reading file fails: {e}"),
};

assert_eq!(matrix_from_file, expected_matrix_from_file);
# std::fs::remove_file("mymatrix.csvbm").unwrap_or(());
```

## The CSVBM file format for CSV binary matrices

A conventional CSVBM file has the `.csvbm` extension.

The CSVBM format is as follows:

```text
number_of_rows number_of_columns number_of_ones is_reversed
distance_1
distance_2
...
distance_number_of_ones

```

Where:

* `number_of_rows` is the number of rows of the matrix.
* `number_of_columns` is the number of columns of the matrix.
* `number_of_ones` is the number of ones in the matrix.
* `is_reversed` is a 0-1 boolean value indicating whether the matrix is reversed or not.

Depending on the method you use to store the matrix into a file, the meaning of the distances differs.

* If `is_reversed` is `0`:
  * `distance_i` is the distance between the i-th and the (i+1)-th ones.
  * `distance_1` is the distance between the first cell and the first one.
* Otherwise, `is_reversed` is `1`:
  * `distance_i` is the distance between the (i+1)-th and the i-th one.
  * `distance_1` is the distance between the last cell and the last one.

### Example

For the matrix:

```text
1 1 1
1 0 0
0 1 0
```

The CSVBM file can either be:

```text
3 3 5 0
0
1
1
1
4

```

or (note the `is_reversed` bool set to `1`):

```text
3 3 5 1
1
4
1
1
1

```