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 */