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 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 */ 167