src/data/sparse-cases.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 2007 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 array of cases.
  18
  19    Implements a 2-d sparse array in which each row represents a
  20    case, each column represents a variable, and each intersection
  21    contains a `union value'.  Data in the array may be accessed
  22    randomly by column and row.  When the number of cases stored
  23    in the array is small, the data is stored in memory in memory;
  24    when it is large, the data is stored in a temporary file.
  25
  26    The sparse_cases_write_columns function provides a somewhat
  27    unusual ability: to write a given value to every row in a
  28    column or set of columns.  This overwrites any values
  29    previously written into those columns.  For rows that have
  30    never been written, this function sets "default" values that
  31    later writes can override.
  32
  33    The array keeps track of which row have been written.  If
  34    sparse_cases_write_columns has been used, reading from a row
  35    that has never been written yields the default values;
  36    otherwise, reading from such a row in an error.  It is
  37    permissible to write to only some columns in a row and leave
  38    the rest of the row's data undefined (or, if
  39    sparse_cases_write_columns has been used, at the default
  40    values).  The array does not keep track of which columns in a
  41    row have never been written, but reading values that have
  42    never been written or set as defaults yields undefined
  43    behavior. */
  44
  45 #ifndef DATA_SPARSE_CASES_H
  46 #define DATA_SPARSE_CASES_H 1
  47
  48 #include <stddef.h>
  49 #include <stdbool.h>
  50 #include <data/case.h>
  51
  52 struct sparse_cases *sparse_cases_create (size_t value_cnt);
  53 struct sparse_cases *sparse_cases_clone (const struct sparse_cases *);
  54 void sparse_cases_destroy (struct sparse_cases *);
  55
  56 size_t sparse_cases_get_value_cnt (const struct sparse_cases *);
  57
  58 bool sparse_cases_contains_row (const struct sparse_cases *, casenumber row);
  59 bool sparse_cases_read (struct sparse_cases *, casenumber row, size_t column,
  60                         union value[], size_t value_cnt);
  61 bool sparse_cases_write (struct sparse_cases *, casenumber row, size_t column,
  62                          const union value[], size_t value_cnt);
  63 bool sparse_cases_write_columns (struct sparse_cases *, size_t start_column,
  64                                  const union value[], size_t value_cnt);
  65
  66 #endif /* data/sparse-cases.h */