gui: Fix behavior of print preview in psppire-output-window.
[pspp] / src / data / casereader.h
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 2007, 2009, 2010, 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 /* 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 void casereader_split (struct casereader *,
68                        struct casereader **, struct casereader **);
69 struct casereader *casereader_rename (struct casereader *);
70 void casereader_swap (struct casereader *, struct casereader *);
71
72 struct ccase *casereader_peek (struct casereader *, casenumber);
73 bool casereader_is_empty (struct casereader *);
74
75 bool casereader_error (const struct casereader *);
76 void casereader_force_error (struct casereader *);
77 const struct taint *casereader_get_taint (const struct casereader *);
78
79 casenumber casereader_get_case_cnt (struct casereader *);
80 casenumber casereader_count_cases (const struct casereader *);
81 void casereader_truncate (struct casereader *, casenumber);
82 const struct caseproto *casereader_get_proto (const struct casereader *);
83
84 casenumber casereader_advance (struct casereader *, casenumber);
85 void casereader_transfer (struct casereader *, struct casewriter *);
86 \f
87 struct casereader *casereader_create_empty (const struct caseproto *);
88
89 struct casereader *
90 casereader_create_filter_func (struct casereader *,
91                                bool (*include) (const struct ccase *,
92                                                 void *aux),
93                                bool (*destroy) (void *aux),
94                                void *aux,
95                                struct casewriter *exclude);
96 struct casereader *
97 casereader_create_filter_weight (struct casereader *,
98                                  const struct dictionary *dict,
99                                  bool *warn_on_invalid,
100                                  struct casewriter *exclude);
101 struct casereader *
102 casereader_create_filter_missing (struct casereader *,
103                                   const struct variable *const*vars, size_t var_cnt,
104                                   enum mv_class,
105                                   casenumber *n_missing,
106                                   struct casewriter *exclude);
107
108 struct casereader *
109 casereader_create_counter (struct casereader *, casenumber *counter,
110                            casenumber initial_value);
111
112 struct casereader *
113 casereader_create_translator (struct casereader *,
114                               const struct caseproto *output_proto,
115                               struct ccase *(*translate) (struct ccase *,
116                                                           void *aux),
117                               bool (*destroy) (void *aux),
118                               void *aux);
119
120 struct casereader *
121 casereader_translate_stateless (struct casereader *,
122                                 const struct caseproto *output_proto,
123                                 struct ccase *(*translate) (struct ccase *,
124                                                             casenumber idx,
125                                                             const void *aux),
126                                 bool (*destroy) (void *aux),
127                                 void *aux);
128
129 struct casereader *casereader_project (struct casereader *,
130                                        const struct subcase *);
131 struct casereader *casereader_project_1 (struct casereader *, int column);
132 struct casereader *casereader_select (struct casereader *,
133                                       casenumber first, casenumber last,
134                                       casenumber by);
135
136 /* A function which creates a numberic value from an existing case */
137 typedef double new_value_func (const struct ccase *, casenumber, void *);
138
139 struct casereader *
140 casereader_create_append_numeric (struct casereader *subreader,
141                                   new_value_func func, void *aux,
142                                   void (*destroy) (void *aux));
143
144 struct casereader *
145 casereader_create_arithmetic_sequence (struct casereader *,
146                                        double first, double increment);
147
148 enum rank_error
149   {
150     RANK_ERR_NONE = 0,
151     RANK_ERR_NEGATIVE_WEIGHT = 0x01,
152     RANK_ERR_UNSORTED = 0x02
153   };
154
155
156 typedef void distinct_func (double v, casenumber n, double w, void *aux);
157
158 struct casereader *
159 casereader_create_append_rank (struct casereader *,
160                                const struct variable *v, const struct variable *w,
161                                enum rank_error *err,
162                                distinct_func *distinct_callback, void *aux);
163
164 struct casereader *
165 casereader_create_distinct (struct casereader *input,
166                             const struct variable *key,
167                             const struct variable *weight);
168
169
170 #endif /* data/casereader.h */