src/data/casereader-provider.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 2007, 2009 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.  If successful, returns
  47        the case and advances READER, so that the next call to
  48        this function will read the following case.  The case just
  49        read will never be read again by a call to this function
  50        for READER.
  51
  52        If a case is successfully returned, the client is
  53        responsible for calling case_unref upon it when it is no
  54        longer needed.
  55
  56        At end of file or upon an I/O error, returns a null
  57        pointer.  After null is returned once, this function will
  58        not be called again for the given READER.
  59
  60        If an I/O error occurs, this function should call
  61        casereader_force_error on READER. */
  62     struct ccase *(*read) (struct casereader *reader, void *aux);
  63
  64     /* Mandatory.
  65
  66        Destroys READER.
  67
  68        If an I/O error is detected during destruction, this
  69        function should call casereader_force_error on READER. */
  70     void (*destroy) (struct casereader *reader, void *aux);
  71
  72     /* Optional: if convenient and efficiently implementable,
  73        supply this function as an optimization for use by
  74        casereader_clone.  (But it might be easier to use the
  75        random-access casereader wrapper instead.)
  76
  77        Creates and returns a clone of READER.  The clone must
  78        read the same case data in the same sequence as READER,
  79        starting from the same position.  The only allowable
  80        exception to this rule is that I/O errors may force the
  81        clone or the original casereader to stop reading after
  82        differing numbers of cases.
  83
  84        The clone should have a clone of READER's taint object,
  85        accomplished by passing casereader_get_taint (READER) to
  86        casereader_create. */
  87     struct casereader *(*clone) (struct casereader *reader, void *aux);
  88
  89     /* Optional: if convenient and efficiently implementable,
  90        supply as an optimization for use by casereader_peek.
  91        (But it might be easier to use the random-access
  92        casereader wrapper instead.)
  93
  94        Reads and returns the case at 0-based offset IDX from the
  95        beginning of READER.  If a case is successfully returned,
  96        the client is responsible for calling case_unref upon it
  97        when it is no longer needed.
  98
  99        At end of file or upon an I/O error, returns a null
 100        pointer.  If this function returns null, then it will
 101        never be called again for an equal or greater value of
 102        IDX, and the "read" member function will never be called
 103        to advance as far as IDX cases further into the
 104        casereader.  That is, returning null indicates that the
 105        casereader has fewer than IDX cases left.
 106
 107        If an I/O error occurs, this function should call
 108        casereader_force_error on READER. */
 109     struct ccase *(*peek) (struct casereader *reader, void *aux,
 110                            casenumber idx);
 111   };
 112
 113 struct casereader *
 114 casereader_create_sequential (const struct taint *,
 115                               const struct caseproto *, casenumber case_cnt,
 116                               const struct casereader_class *, void *);
 117
 118 void *casereader_dynamic_cast (struct casereader *, const struct casereader_class *);
 119 \f
 120 /* Casereader class for random-access data sources. */
 121 struct casereader_random_class
 122   {
 123     /* Mandatory.
 124
 125        Reads the case at 0-based offset IDX from the beginning of
 126        READER.  If a case is successfully returned, the client is
 127        responsible for calling case_unref upon it when it is no
 128        longer needed.
 129
 130        At end of file or upon an I/O error, returns a null
 131        pointer.  If this function returns null, then it will
 132        never be called again for an equal or greater value of
 133        IDX, and the "read" member function will never be called
 134        to advance as far as IDX cases further into the
 135        casereader.  That is, returning null indicates that the
 136        casereader has fewer than IDX cases.
 137
 138        If an I/O error occurs, this function should call
 139        casereader_force_error on READER. */
 140     struct ccase *(*read) (struct casereader *reader, void *aux,
 141                            casenumber idx);
 142
 143     /* Mandatory.
 144
 145        Destroys READER.
 146
 147        If an I/O error is detected during destruction, this
 148        function should call casereader_force_error on READER. */
 149     void (*destroy) (struct casereader *reader, void *aux);
 150
 151     /* Mandatory.
 152
 153        A call to this function tells the callee that the CNT
 154        cases at the beginning of READER will never be read again.
 155        The casereader implementation should free any resources
 156        associated with those cases.  After this function returns,
 157        the IDX argument in future calls to the "read" function
 158        will be relative to remaining cases. */
 159     void (*advance) (struct casereader *reader, void *aux, casenumber cnt);
 160   };
 161
 162 struct casereader *
 163 casereader_create_random (const struct caseproto *, casenumber case_cnt,
 164                           const struct casereader_random_class *, void *aux);
 165
 166 #endif /* data/casereader-provider.h */