Autorecode: Add the /GROUP subcommand
[pspp] / src / libpspp / sparse-xarray.h
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 2007, 2009 Free Software Foundation, Inc.
3
4    This program is free software: you can redistribute it and/or modify
5    it under the terms of the GNU General Public License as published by
6    the Free Software Foundation, either version 3 of the License, or
7    (at your option) any later version.
8
9    This program is distributed in the hope that it will be useful,
10    but WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12    GNU General Public License for more details.
13
14    You should have received a copy of the GNU General Public License
15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
16
17 /* Sparse 2-d array.
18
19    Implements a sparse array, in particular a sparse array of
20    byte arrays.  Each row is either present or absent, and each
21    row that is present consists of a fixed number of bytes
22    (columns).  Data in the array may be accessed randomly by
23    column and row.  When the number of rows stored in the array
24    is small, the data is stored in memory; when it is large, the
25    data is stored in a temporary file.
26
27    The sparse_xarray_write_columns function provides a somewhat
28    unusual ability: to write a given value to every row in a
29    column or set of columns.  This overwrites any values
30    previously written into those columns.  For rows that have
31    never been written, this function sets "default" values that
32    later writes can override.  The default values are initially
33    all zero bytes.
34
35    The array keeps track of which row have been written.  Reading
36    from a row that has never been written yields the default
37    values.  It is permissible to write to only some columns in a
38    row and leave the rest of the row's data at the default
39    values. */
40
41 #ifndef LIBPSPP_SPARSE_XARRAY_H
42 #define LIBPSPP_SPARSE_XARRAY_H 1
43
44 #include <stddef.h>
45 #include <stdbool.h>
46
47 struct sparse_xarray *sparse_xarray_create (size_t n_columns,
48                                             size_t max_memory_rows);
49 struct sparse_xarray *sparse_xarray_clone (const struct sparse_xarray *);
50 void sparse_xarray_destroy (struct sparse_xarray *);
51
52 size_t sparse_xarray_get_n_columns (const struct sparse_xarray *);
53 size_t sparse_xarray_get_n_rows (const struct sparse_xarray *);
54
55 bool sparse_xarray_contains_row (const struct sparse_xarray *,
56                                  unsigned long int row);
57 bool sparse_xarray_read (const struct sparse_xarray *, unsigned long int row,
58                          size_t start, size_t n, void *);
59 bool sparse_xarray_write (struct sparse_xarray *, unsigned long int row,
60                           size_t start, size_t n, const void *);
61 bool sparse_xarray_write_columns (struct sparse_xarray *, size_t start,
62                                   size_t n, const void *);
63 bool sparse_xarray_copy (const struct sparse_xarray *src,
64                          struct sparse_xarray *dst,
65                          bool (*cb) (const void *src, void *dst, void *aux),
66                          void *aux);
67
68 /* For testing purposes only. */
69 unsigned int sparse_xarray_model_checker_hash (const struct sparse_xarray *,
70                                                unsigned int basis);
71
72 #endif /* libpspp/sparse-libpspp.h */