src/data/sparse-cases.h

   1 /* PSPP - computes sample statistics.
   2    Copyright (C) 2007 Free Software Foundation, Inc.
   3
   4    This program is free software; you can redistribute it and/or
   5    modify it under the terms of the GNU General Public License as
   6    published by the Free Software Foundation; either version 2 of the
   7    License, or (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful, but
  10    WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12    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, write to the Free Software
  16    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  17    02110-1301, USA. */
  18
  19 /* Sparse array of cases.
  20
  21    Implements a 2-d sparse array in which each row represents a
  22    case, each column represents a variable, and each intersection
  23    contains a `union value'.  Data in the array may be accessed
  24    randomly by column and row.  When the number of cases stored
  25    in the array is small, the data is stored in memory in memory;
  26    when it is large, the data is stored in a temporary file.
  27
  28    The sparse_cases_write_columns function provides a somewhat
  29    unusual ability: to write a given value to every row in a
  30    column or set of columns.  This overwrites any values
  31    previously written into those columns.  For rows that have
  32    never been written, this function sets "default" values that
  33    later writes can override.
  34
  35    The array keeps track of which row have been written.  If
  36    sparse_cases_write_columns has been used, reading from a row
  37    that has never been written yields the default values;
  38    otherwise, reading from such a row in an error.  It is
  39    permissible to write to only some columns in a row and leave
  40    the rest of the row's data undefined (or, if
  41    sparse_cases_write_columns has been used, at the default
  42    values).  The array does not keep track of which columns in a
  43    row have never been written, but reading values that have
  44    never been written or set as defaults yields undefined
  45    behavior. */
  46
  47 #ifndef DATA_SPARSE_CASES_H
  48 #define DATA_SPARSE_CASES_H 1
  49
  50 #include <stddef.h>
  51 #include <stdbool.h>
  52 #include <data/case.h>
  53
  54 struct sparse_cases *sparse_cases_create (size_t value_cnt);
  55 struct sparse_cases *sparse_cases_clone (const struct sparse_cases *);
  56 void sparse_cases_destroy (struct sparse_cases *);
  57
  58 size_t sparse_cases_get_value_cnt (const struct sparse_cases *);
  59
  60 bool sparse_cases_contains_row (const struct sparse_cases *, casenumber row);
  61 bool sparse_cases_read (struct sparse_cases *, casenumber row, size_t column,
  62                         union value[], size_t value_cnt);
  63 bool sparse_cases_write (struct sparse_cases *, casenumber row, size_t column,
  64                          const union value[], size_t value_cnt);
  65 bool sparse_cases_write_columns (struct sparse_cases *, size_t start_column,
  66                                  const union value[], size_t value_cnt);
  67
  68 #endif /* data/sparse-cases.h */