1 /* PSPP - a program for statistical analysis. 2 Copyright (C) 2007, 2009, 2010, 2011, 2013 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 /* Casereader client interface. 18 19 A casereader abstracts interfaces through which cases may be 20 read. A casereader may be a front-end for a system file, a 21 portable file, a dataset, or anything else on which a 22 casereader interface has been overlaid. Casereader layering, 23 in which a casereader acts as a filter or translator on top of 24 another casereader, is also supported. 25 26 There is no central interface for obtaining casereaders: a 27 casereader for reading a system file is obtained from the 28 system file reading module, and so on. Once a casereader has 29 been obtained, by whatever means, the interface to it is 30 uniform. The most important functions for casereader usage 31 are: 32 33 - casereader_read: Reads a case from the casereader. The 34 case is consumed and cannot be read again. The caller is 35 responsible for destroying the case. 36 37 - casereader_clone: Makes a copy of a casereader. May be 38 used to read one or a set of cases from a casereader 39 repeatedly. 40 41 - casereader_destroy: Destroys a casereader. 42 43 Casereaders can encounter error conditions, such as I/O 44 errors, as they read cases. Error conditions prevent any more 45 cases from being read from the casereader. Error conditions 46 are reported by casereader_error. Error condition may be 47 propagated to or from a casereader with taint_propagate using 48 the casereader's taint object, which may be obtained with 49 casereader_get_taint. */ 50 51 #ifndef DATA_CASEREADER_H 52 #define DATA_CASEREADER_H 1 53 54 #include "libpspp/compiler.h" 55 #include "data/case.h" 56 #include "data/missing-values.h" 57 58 struct dictionary; 59 struct casereader; 60 struct casewriter; 61 struct subcase; 62 63 struct ccase *casereader_read (struct casereader *); 64 bool casereader_destroy (struct casereader *); 65 66 struct casereader *casereader_clone (const struct casereader *); 67 struct casereader *casereader_rename (struct casereader *); 68 void casereader_swap (struct casereader *, struct casereader *); 69 70 struct ccase *casereader_peek (struct casereader *, casenumber); 71 bool casereader_is_empty (struct casereader *); 72 73 bool casereader_error (const struct casereader *); 74 void casereader_force_error (struct casereader *); 75 const struct taint *casereader_get_taint (const struct casereader *); 76 77 casenumber casereader_get_case_cnt (struct casereader *); 78 casenumber casereader_count_cases (const struct casereader *); 79 void casereader_truncate (struct casereader *, casenumber); 80 const struct caseproto *casereader_get_proto (const struct casereader *); 81 82 casenumber casereader_advance (struct casereader *, casenumber); 83 void casereader_transfer (struct casereader *, struct casewriter *); 84 85 struct casereader *casereader_create_empty (const struct caseproto *); 86 87 struct casereader * 88 casereader_create_filter_func (struct casereader *, 89 bool (*include) (const struct ccase *, 90 void *aux), 91 bool (*destroy) (void *aux), 92 void *aux, 93 struct casewriter *exclude); 94 struct casereader * 95 casereader_create_filter_weight (struct casereader *, 96 const struct dictionary *dict, 97 bool *warn_on_invalid, 98 struct casewriter *exclude); 99 struct casereader * 100 casereader_create_filter_missing (struct casereader *, 101 const struct variable *const*vars, size_t var_cnt, 102 enum mv_class, 103 casenumber *n_missing, 104 struct casewriter *exclude); 105 106 struct casereader * 107 casereader_create_counter (struct casereader *, casenumber *counter, 108 casenumber initial_value); 109 110 struct casereader * 111 casereader_create_translator (struct casereader *, 112 const struct caseproto *output_proto, 113 struct ccase *(*translate) (struct ccase *, 114 void *aux), 115 bool (*destroy) (void *aux), 116 void *aux); 117 118 struct casereader * 119 casereader_translate_stateless (struct casereader *, 120 const struct caseproto *output_proto, 121 struct ccase *(*translate) (struct ccase *, 122 casenumber idx, 123 const void *aux), 124 bool (*destroy) (void *aux), 125 void *aux); 126 127 struct casereader *casereader_project (struct casereader *, 128 const struct subcase *); 129 struct casereader *casereader_project_1 (struct casereader *, int column); 130 struct casereader *casereader_select (struct casereader *, 131 casenumber first, casenumber last, 132 casenumber by); 133 134 /* A function which creates a numberic value from an existing case */ 135 typedef double new_value_func (const struct ccase *, casenumber, void *); 136 137 struct casereader * 138 casereader_create_append_numeric (struct casereader *subreader, 139 new_value_func func, void *aux, 140 void (*destroy) (void *aux)); 141 142 struct casereader * 143 casereader_create_arithmetic_sequence (struct casereader *, 144 double first, double increment); 145 146 enum rank_error 147 { 148 RANK_ERR_NONE = 0, 149 RANK_ERR_NEGATIVE_WEIGHT = 0x01, 150 RANK_ERR_UNSORTED = 0x02 151 }; 152 153 154 typedef void distinct_func (double v, casenumber n, double w, void *aux); 155 156 struct casereader * 157 casereader_create_append_rank (struct casereader *, 158 const struct variable *v, const struct variable *w, 159 enum rank_error *err, 160 distinct_func *distinct_callback, void *aux); 161 162 struct casereader * 163 casereader_create_distinct (struct casereader *input, 164 const struct variable *key, 165 const struct variable *weight); 166 167 168 #endif /* data/casereader.h */ 169