pintos-os.org Git - pspp/blob - src/data/casereader.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 2007, 2009, 2010, 2011, 2013 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 /* Casereader client interface.
  18
  19    A casereader abstracts interfaces through which cases may be
  20    read.  A casereader may be a front-end for a system file, a
  21    portable file, a dataset, or anything else on which a
  22    casereader interface has been overlaid.  Casereader layering,
  23    in which a casereader acts as a filter or translator on top of
  24    another casereader, is also supported.
  25
  26    There is no central interface for obtaining casereaders: a
  27    casereader for reading a system file is obtained from the
  28    system file reading module, and so on.  Once a casereader has
  29    been obtained, by whatever means, the interface to it is
  30    uniform.  The most important functions for casereader usage
  31    are:
  32
  33      - casereader_read: Reads a case from the casereader.  The
  34        case is consumed and cannot be read again.  The caller is
  35        responsible for destroying the case.
  36
  37      - casereader_clone: Makes a copy of a casereader.  May be
  38        used to read one or a set of cases from a casereader
  39        repeatedly.
  40
  41      - casereader_destroy: Destroys a casereader.
  42
  43    Casereaders can encounter error conditions, such as I/O
  44    errors, as they read cases.  Error conditions prevent any more
  45    cases from being read from the casereader.  Error conditions
  46    are reported by casereader_error.  Error condition may be
  47    propagated to or from a casereader with taint_propagate using
  48    the casereader's taint object, which may be obtained with
  49    casereader_get_taint. */
  50
  51 #ifndef DATA_CASEREADER_H
  52 #define DATA_CASEREADER_H 1
  53
  54 #include "libpspp/compiler.h"
  55 #include "data/case.h"
  56 #include "data/missing-values.h"
  57
  58 struct dictionary;
  59 struct casereader;
  60 struct casewriter;
  61 struct subcase;
  62
  63 struct ccase *casereader_read (struct casereader *);
  64 bool casereader_destroy (struct casereader *);
  65
  66 struct casereader *casereader_clone (const struct casereader *);
  67 struct casereader *casereader_rename (struct casereader *);
  68 void casereader_swap (struct casereader *, struct casereader *);
  69
  70 struct ccase *casereader_peek (struct casereader *, casenumber);
  71 bool casereader_is_empty (struct casereader *);
  72
  73 bool casereader_error (const struct casereader *);
  74 void casereader_force_error (struct casereader *);
  75 const struct taint *casereader_get_taint (const struct casereader *);
  76
  77 casenumber casereader_get_case_cnt (struct casereader *);
  78 casenumber casereader_count_cases (const struct casereader *);
  79 void casereader_truncate (struct casereader *, casenumber);
  80 const struct caseproto *casereader_get_proto (const struct casereader *);
  81
  82 casenumber casereader_advance (struct casereader *, casenumber);
  83 void casereader_transfer (struct casereader *, struct casewriter *);
  84
  85 struct pxd_object *casereader_save (const struct casereader *, struct pxd *);
  86 struct casereader *casereader_load (struct pxd_object *, const struct pxd *);
  87 \f
  88 struct casereader *casereader_create_empty (const struct caseproto *);
  89
  90 struct casereader *
  91 casereader_create_filter_func (struct casereader *,
  92                                bool (*include) (const struct ccase *,
  93                                                 void *aux),
  94                                bool (*destroy) (void *aux),
  95                                void *aux,
  96                                struct casewriter *exclude);
  97 struct casereader *
  98 casereader_create_filter_weight (struct casereader *,
  99                                  const struct dictionary *dict,
 100                                  bool *warn_on_invalid,
 101                                  struct casewriter *exclude);
 102 struct casereader *
 103 casereader_create_filter_missing (struct casereader *,
 104                                   const struct variable *const*vars, size_t var_cnt,
 105                                   enum mv_class,
 106                                   casenumber *n_missing,
 107                                   struct casewriter *exclude);
 108
 109 struct casereader *
 110 casereader_create_counter (struct casereader *, casenumber *counter,
 111                            casenumber initial_value);
 112
 113 struct casereader *
 114 casereader_create_translator (struct casereader *,
 115                               const struct caseproto *output_proto,
 116                               struct ccase *(*translate) (struct ccase *,
 117                                                           void *aux),
 118                               bool (*destroy) (void *aux),
 119                               void *aux);
 120
 121 struct casereader *
 122 casereader_translate_stateless (struct casereader *,
 123                                 const struct caseproto *output_proto,
 124                                 struct ccase *(*translate) (struct ccase *,
 125                                                             casenumber idx,
 126                                                             const void *aux),
 127                                 bool (*destroy) (void *aux),
 128                                 void *aux);
 129
 130 struct casereader *casereader_project (struct casereader *,
 131                                        const struct subcase *);
 132 struct casereader *casereader_project_1 (struct casereader *, int column);
 133 struct casereader *casereader_select (struct casereader *,
 134                                       casenumber first, casenumber last,
 135                                       casenumber by);
 136
 137 /* A function which creates a numberic value from an existing case */
 138 typedef double new_value_func (const struct ccase *, casenumber, void *);
 139
 140 struct casereader *
 141 casereader_create_append_numeric (struct casereader *subreader,
 142                                   new_value_func func, void *aux,
 143                                   void (*destroy) (void *aux));
 144
 145 struct casereader *
 146 casereader_create_arithmetic_sequence (struct casereader *,
 147                                        double first, double increment);
 148
 149 enum rank_error
 150   {
 151     RANK_ERR_NONE = 0,
 152     RANK_ERR_NEGATIVE_WEIGHT = 0x01,
 153     RANK_ERR_UNSORTED = 0x02
 154   };
 155
 156
 157 typedef void distinct_func (double v, casenumber n, double w, void *aux);
 158
 159 struct casereader *
 160 casereader_create_append_rank (struct casereader *,
 161                                const struct variable *v, const struct variable *w,
 162                                enum rank_error *err,
 163                                distinct_func *distinct_callback, void *aux);
 164
 165 struct casereader *
 166 casereader_create_distinct (struct casereader *input,
 167                             const struct variable *key,
 168                             const struct variable *weight);
 169
 170
 171 #endif /* data/casereader.h */