1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 2007, 2009, 2010, 2011, 2013 Free Software Foundation, Inc.
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.
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.
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/>. */
17 /* Casereader client interface.
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.
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
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.
37 - casereader_clone: Makes a copy of a casereader. May be
38 used to read one or a set of cases from a casereader
41 - casereader_destroy: Destroys a casereader.
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. */
51 #ifndef DATA_CASEREADER_H
52 #define DATA_CASEREADER_H 1
54 #include "libpspp/compiler.h"
55 #include "data/case.h"
56 #include "data/missing-values.h"
63 struct ccase *casereader_read (struct casereader *);
64 bool casereader_destroy (struct casereader *);
66 struct casereader *casereader_clone (const struct casereader *);
67 struct casereader *casereader_rename (struct casereader *);
68 void casereader_swap (struct casereader *, struct casereader *);
70 struct ccase *casereader_peek (struct casereader *, casenumber);
71 bool casereader_is_empty (struct casereader *);
73 bool casereader_error (const struct casereader *);
74 void casereader_force_error (struct casereader *);
75 const struct taint *casereader_get_taint (const struct casereader *);
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 *);
82 casenumber casereader_advance (struct casereader *, casenumber);
83 void casereader_transfer (struct casereader *, struct casewriter *);
85 struct pxd_object *casereader_save (const struct casereader *, struct pxd *);
86 struct casereader *casereader_load (struct pxd_object *, const struct pxd *);
88 struct casereader *casereader_create_empty (const struct caseproto *);
91 casereader_create_filter_func (struct casereader *,
92 bool (*include) (const struct ccase *,
94 bool (*destroy) (void *aux),
96 struct casewriter *exclude);
98 casereader_create_filter_weight (struct casereader *,
99 const struct dictionary *dict,
100 bool *warn_on_invalid,
101 struct casewriter *exclude);
103 casereader_create_filter_missing (struct casereader *,
104 const struct variable *const*vars, size_t var_cnt,
106 casenumber *n_missing,
107 struct casewriter *exclude);
110 casereader_create_counter (struct casereader *, casenumber *counter,
111 casenumber initial_value);
114 casereader_create_translator (struct casereader *,
115 const struct caseproto *output_proto,
116 struct ccase *(*translate) (struct ccase *,
118 bool (*destroy) (void *aux),
122 casereader_translate_stateless (struct casereader *,
123 const struct caseproto *output_proto,
124 struct ccase *(*translate) (struct ccase *,
127 bool (*destroy) (void *aux),
130 struct casereader *casereader_project (struct casereader *,
131 const struct subcase *);
132 struct casereader *casereader_project_1 (struct casereader *, int column);
133 struct casereader *casereader_select (struct casereader *,
134 casenumber first, casenumber last,
137 /* A function which creates a numberic value from an existing case */
138 typedef double new_value_func (const struct ccase *, casenumber, void *);
141 casereader_create_append_numeric (struct casereader *subreader,
142 new_value_func func, void *aux,
143 void (*destroy) (void *aux));
146 casereader_create_arithmetic_sequence (struct casereader *,
147 double first, double increment);
152 RANK_ERR_NEGATIVE_WEIGHT = 0x01,
153 RANK_ERR_UNSORTED = 0x02
157 typedef void distinct_func (double v, casenumber n, double w, void *aux);
160 casereader_create_append_rank (struct casereader *,
161 const struct variable *v, const struct variable *w,
162 enum rank_error *err,
163 distinct_func *distinct_callback, void *aux);
166 casereader_create_distinct (struct casereader *input,
167 const struct variable *key,
168 const struct variable *weight);
171 #endif /* data/casereader.h */