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