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
 114 void *casereader_dynamic_cast (struct casereader *, const struct casereader_class *);
 115 \f
 116 /* Casereader class for random-access data sources. */
 117 struct casereader_random_class
 118   {
 119     /* Mandatory.
 120
 121        Reads the case at 0-based offset IDX from the beginning of
 122        READER into case C, which the casereader must create and
 123        which the client is responsible for destroying.
 124
 125        At end of file or upon an I/O error, returns false.  If
 126        this function returns false, then it will never be called
 127        again for an equal or greater value of IDX, and the "read"
 128        member function will never be called to advance as far as
 129        IDX cases further into the casereader.  That is, returning
 130        false indicates that the casereader has fewer than IDX
 131        cases.
 132
 133        If an I/O error occurs, this function should call
 134        casereader_force_error on READER. */
 135     bool (*read) (struct casereader *reader, void *aux, casenumber idx,
 136                   struct ccase *c);
 137
 138     /* Mandatory.
 139
 140        Destroys READER.
 141
 142        If an I/O error is detected during destruction, this
 143        function should call casereader_force_error on READER. */
 144     void (*destroy) (struct casereader *reader, void *aux);
 145
 146     /* Mandatory.
 147
 148        A call to this function tells the callee that the CNT
 149        cases at the beginning of READER will never be read again.
 150        The casereader implementation should free any resources
 151        associated with those cases.  After this function returns,
 152        the IDX argument in future calls to the "read" function
 153        will be relative to remaining cases. */
 154     void (*advance) (struct casereader *reader, void *aux, casenumber cnt);
 155   };
 156
 157 struct casereader *
 158 casereader_create_random (size_t value_cnt, casenumber case_cnt,
 159                           const struct casereader_random_class *, void *aux);
 160
 161 #endif /* data/casereader-provider.h */