src/data/casereader.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 /* Casereader client interface.
  20
  21    A casereader abstracts interfaces through which cases may be
  22    read.  A casereader may be a front-end for a system file, a
  23    portable file, the active file in a data set, or anything else
  24    on which a casereader interface has been overlaid.  Casereader
  25    layering, in which a casereader acts as a filter or translator
  26    on top of another casereader, is also supported.
  27
  28    There is no central interface for obtaining casereaders: a
  29    casereader for reading a system file is obtained from the
  30    system file reading module, and so on.  Once a casereader has
  31    been obtained, by whatever means, the interface to it is
  32    uniform.  The most important functions for casereader usage
  33    are:
  34
  35      - casereader_read: Reads a case from the casereader.  The
  36        case is consumed and cannot be read again.  The caller is
  37        responsible for destroying the case.
  38
  39      - casereader_clone: Makes a copy of a casereader.  May be
  40        used to read one or a set of cases from a casereader
  41        repeatedly.
  42
  43      - casereader_destroy: Destroys a casereader.
  44
  45    Casereaders can encounter error conditions, such as I/O
  46    errors, as they read cases.  Error conditions prevent any more
  47    cases from being read from the casereader.  Error conditions
  48    are reported by casereader_error.  Error condition may be
  49    propagated to or from a casereader with taint_propagate using
  50    the casereader's taint object, which may be obtained with
  51    casereader_get_taint. */
  52
  53 #ifndef DATA_CASEREADER_H
  54 #define DATA_CASEREADER_H 1
  55
  56 #include <libpspp/compiler.h>
  57 #include <data/case.h>
  58 #include <data/missing-values.h>
  59
  60 struct dictionary;
  61 struct casereader;
  62 struct casewriter;
  63
  64 bool casereader_read (struct casereader *, struct ccase *);
  65 bool casereader_destroy (struct casereader *);
  66
  67 struct casereader *casereader_clone (const struct casereader *);
  68 void casereader_split (struct casereader *,
  69                        struct casereader **, struct casereader **);
  70 struct casereader *casereader_rename (struct casereader *);
  71 void casereader_swap (struct casereader *, struct casereader *);
  72
  73 bool casereader_peek (struct casereader *, casenumber, struct ccase *)
  74      WARN_UNUSED_RESULT;
  75
  76 bool casereader_error (const struct casereader *);
  77 void casereader_force_error (struct casereader *);
  78 const struct taint *casereader_get_taint (const struct casereader *);
  79
  80 casenumber casereader_get_case_cnt (struct casereader *);
  81 casenumber casereader_count_cases (struct casereader *);
  82 size_t casereader_get_value_cnt (struct casereader *);
  83
  84 void casereader_transfer (struct casereader *, struct casewriter *);
  85 \f
  86 struct casereader *
  87 casereader_create_filter_func (struct casereader *,
  88                                bool (*include) (const struct ccase *,
  89                                                 void *aux),
  90                                bool (*destroy) (void *aux),
  91                                void *aux,
  92                                struct casewriter *exclude);
  93 struct casereader *
  94 casereader_create_filter_weight (struct casereader *,
  95                                  const struct dictionary *dict,
  96                                  bool *warn_on_invalid,
  97                                  struct casewriter *exclude);
  98 struct casereader *
  99 casereader_create_filter_missing (struct casereader *,
 100                                   const struct variable **vars, size_t var_cnt,
 101                                   enum mv_class,
 102                                   struct casewriter *exclude);
 103
 104 struct casereader *
 105 casereader_create_counter (struct casereader *, casenumber *counter,
 106                            casenumber initial_value);
 107
 108 struct casereader *
 109 casereader_create_translator (struct casereader *, size_t output_value_cnt,
 110                               void (*translate) (const struct ccase *input,
 111                                                  struct ccase *output,
 112                                                  void *aux),
 113                               bool (*destroy) (void *aux),
 114                               void *aux);
 115
 116 #endif /* data/casereader.h */