gui: Fix behavior of print preview in psppire-output-window.
[pspp] / src / data / casereader-provider.h
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 2007, 2009, 2011 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 */