Fix GCC 4.3 warning about uninitialized structure member.
[pspp] / 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 */