pintos-os.org Git - pspp/blob - src/data/casereader-provider.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 /* Definitions needed to implement a new type of casereader.
  18    Code that only uses casereaders does not need this header.
  19
  20    Two functions to create casereaders are supplied:
  21
  22         - casereader_create_sequential, to create a casereader
  23           for a data source that is naturally sequential.  The
  24           casereader layer will automatically, as needed,
  25           simulate the ability to access cases randomly.
  26
  27         - casereader_create_random, to create a casereader for a
  28           data source that supports random access to cases.  (This
  29           function is in fact implemented as a set of wrappers
  30           around casereader_create_sequential.)
  31
  32    Which function is used has no effect on the set of operations
  33    that may be performed on the resulting casereader, only on how
  34    the casereader is implemented internally. */
  35
  36 #ifndef DATA_CASEREADER_PROVIDER_H
  37 #define DATA_CASEREADER_PROVIDER_H 1
  38
  39 #include <data/casereader.h>
  40
  41 /* Casereader class for sequential data sources. */
  42 struct casereader_class
  43   {
  44     /* Mandatory.
  45
  46        Reads the next case from READER into case C, which the
  47        casereader must create and which the client is responsible
  48        for destroying.  If successful, returns true and advances
  49        READER to the next case, so that the next call to this
  50        function will read the next case.  The case just read will
  51        never be read again by a call to this function for READER.
  52
  53        At end of file or upon an I/O error, returns false.  After
  54        false is returned once, this function will not be called
  55        again for the given READER.
  56
  57        If an I/O error occurs, this function should call
  58        casereader_force_error on READER. */
  59     bool (*read) (struct casereader *reader, void *aux, struct ccase *c);
  60
  61     /* Mandatory.
  62
  63        Destroys READER.
  64
  65        If an I/O error is detected during destruction, this
  66        function should call casereader_force_error on READER. */
  67     void (*destroy) (struct casereader *reader, void *aux);
  68
  69     /* Optional: if convenient and efficiently implementable,
  70        supply this function as an optimization for use by
  71        casereader_clone.  (But it might be easier to use the
  72        random-access casereader wrapper instead.)
  73
  74        Creates and returns a clone of READER.  The clone must
  75        read the same case data in the same sequence as READER,
  76        starting from the same position.  The only allowable
  77        exception to this rule is that I/O errors may force the
  78        clone or the original casereader to stop reading after
  79        differing numbers of cases.
  80
  81        The clone should have a clone of READER's taint object,
  82        accomplished by passing casereader_get_taint (READER) to
  83        casereader_create. */
  84     struct casereader *(*clone) (struct casereader *reader, void *aux);
  85
  86     /* Optional: if convenient and efficiently implementable,
  87        supply as an optimization for use by casereader_peek.
  88        (But it might be easier to use the random-access
  89        casereader wrapper instead.)
  90
  91        Reads the case at 0-based offset IDX from the beginning of
  92        READER into case C, which the casereader must create and
  93        which the client is responsible for destroying.
  94
  95        At end of file or upon an I/O error, returns false.  If
  96        this function returns false, then it will never be called
  97        again for an equal or greater value of IDX, and the "read"
  98        member function will never be called to advance as far as
  99        IDX cases further into the casereader.  That is, returning
 100        false indicates that the casereader has fewer than IDX
 101        cases left.
 102
 103        If an I/O error occurs, this function should call
 104        casereader_force_error on READER. */
 105     bool (*peek) (struct casereader *reader, void *aux, casenumber idx,
 106                   struct ccase *c);
 107   };
 108
 109 struct casereader *
 110 casereader_create_sequential (const struct taint *,
 111                               size_t value_cnt, casenumber case_cnt,
 112                               const struct casereader_class *, void *);
 113 \f
 114 /* Casereader class for random-access data sources. */
 115 struct casereader_random_class
 116   {
 117     /* Mandatory.
 118
 119        Reads the case at 0-based offset IDX from the beginning of
 120        READER into case C, which the casereader must create and
 121        which the client is responsible for destroying.
 122
 123        At end of file or upon an I/O error, returns false.  If
 124        this function returns false, then it will never be called
 125        again for an equal or greater value of IDX, and the "read"
 126        member function will never be called to advance as far as
 127        IDX cases further into the casereader.  That is, returning
 128        false indicates that the casereader has fewer than IDX
 129        cases.
 130
 131        If an I/O error occurs, this function should call
 132        casereader_force_error on READER. */
 133     bool (*read) (struct casereader *reader, void *aux, casenumber idx,
 134                   struct ccase *c);
 135
 136     /* Mandatory.
 137
 138        Destroys READER.
 139
 140        If an I/O error is detected during destruction, this
 141        function should call casereader_force_error on READER. */
 142     void (*destroy) (struct casereader *reader, void *aux);
 143
 144     /* Mandatory.
 145
 146        A call to this function tells the callee that the CNT
 147        cases at the beginning of READER will never be read again.
 148        The casereader implementation should free any resources
 149        associated with those cases.  After this function returns,
 150        the IDX argument in future calls to the "read" function
 151        will be relative to remaining cases. */
 152     void (*advance) (struct casereader *reader, void *aux, casenumber cnt);
 153   };
 154
 155 struct casereader *
 156 casereader_create_random (size_t value_cnt, casenumber case_cnt,
 157                           const struct casereader_random_class *, void *aux);
 158
 159 #endif /* data/casereader-provider.h */