gui: Fix behavior of print preview in psppire-output-window.
[pspp] / src / data / caseproto.h
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 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 #ifndef DATA_CASEPROTO_H
18 #define DATA_CASEPROTO_H 1
19
20 #include <assert.h>
21 #include <stdbool.h>
22 #include <stddef.h>
23 #include <stdlib.h>
24
25 #include "data/value.h"
26 #include "libpspp/cast.h"
27 #include "libpspp/compiler.h"
28
29 /* Case prototype.
30
31    A case prototype specifies the number and type of the values
32    in a case.  It is essentially an array of integers, where the
33    array index is an index into a case and each element
34    represents the width of a value in a case.  Valid widths are:
35
36        * 0, indicating a numeric value.
37
38        * A positive integer between 1 and 32767, indicating the
39          size in bytes of a string value.
40
41        * -1, indicating that the value at this index in the case
42          is not used at all.  (This is rarely useful.)
43
44    Case prototypes are reference counted.  A newly created case
45    prototype has a single owner (the code that created it),
46    represented by an initial reference count of 1.  Other code
47    that receives the case prototype may keep a virtual copy of it
48    by calling caseproto_ref, which increments the case
49    prototype's reference count.  When this is done, the case
50    prototype becomes shared between its original owner and each
51    piece of code that incremented the reference count.
52
53    Functions that modifying case prototypes automatically unshare
54    them as necessary.  All of these functions potentially move
55    the caseproto around in memory even when the case prototype is
56    not shared.  Thus it is very important that every caller of a
57    function that modifies a case prototype thereafter uses the returned
58    caseproto instead of the one passed in as an argument.
59
60    Only the case prototype code should refer to caseproto members
61    directly.  Other code should use the provided helper
62    functions. */
63 struct caseproto
64   {
65     size_t ref_cnt;             /* Reference count. */
66
67     /* Tracking of long string widths.  Lazily maintained: when
68        'long_strings' is null and 'n_long_strings' is nonzero,
69        the former must be regenerated. */
70     size_t *long_strings;       /* Array of indexes of long string widths. */
71     size_t n_long_strings;      /* Number of long string widths. */
72
73     /* Widths. */
74     size_t n_widths;            /* Number of widths. */
75     size_t allocated_widths;    /* Space allocated for 'widths' array. */
76     short int widths[1];        /* Width of each case value. */
77   };
78
79 struct pool;
80
81 /* Creation and destruction. */
82 struct caseproto *caseproto_create (void) MALLOC_LIKE;
83 static inline struct caseproto *caseproto_ref (const struct caseproto *);
84 struct caseproto *caseproto_ref_pool (const struct caseproto *, struct pool *);
85 static inline void caseproto_unref (struct caseproto *);
86
87 /* Inspecting stored widths.  */
88 static inline int caseproto_get_width (const struct caseproto *, size_t idx);
89 static inline size_t caseproto_get_n_widths (const struct caseproto *);
90
91 /* Adding and removing widths. */
92 struct caseproto *caseproto_reserve (struct caseproto *, size_t n_widths)
93   WARN_UNUSED_RESULT;
94 struct caseproto *caseproto_add_width (struct caseproto *, int width)
95   WARN_UNUSED_RESULT;
96 struct caseproto *caseproto_set_width (struct caseproto *,
97                                        size_t idx, int width)
98   WARN_UNUSED_RESULT;
99 struct caseproto *caseproto_insert_width (struct caseproto *,
100                                           size_t before, int width)
101   WARN_UNUSED_RESULT;
102 struct caseproto *caseproto_remove_widths (struct caseproto *,
103                                            size_t idx, size_t cnt)
104   WARN_UNUSED_RESULT;
105 struct caseproto *caseproto_move_widths (struct caseproto *,
106                                          size_t old_start, size_t new_start,
107                                          size_t cnt)
108   WARN_UNUSED_RESULT;
109
110 /* Working with "union value" arrays. */
111 bool caseproto_needs_init_values (const struct caseproto *);
112 void caseproto_init_values (const struct caseproto *, union value[]);
113 bool caseproto_try_init_values (const struct caseproto *, union value[]);
114 void caseproto_reinit_values (const struct caseproto *old,
115                               const struct caseproto *new, union value[]);
116 void caseproto_destroy_values (const struct caseproto *, union value[]);
117
118 void caseproto_copy (const struct caseproto *, size_t idx, size_t count,
119                      union value *dst, const union value *src);
120
121 /* Inspecting the cache of long string widths.
122
123    (These functions are useful for allocating cases, which
124    requires allocating a block memory for each long string value
125    in the case.) */
126 static inline size_t caseproto_get_n_long_strings (const struct caseproto *);
127 static inline size_t caseproto_get_long_string_idx (const struct caseproto *,
128                                                     size_t idx1);
129
130 /* For use in assertions. */
131 bool caseproto_range_is_valid (const struct caseproto *,
132                                size_t ofs, size_t count);
133 bool caseproto_is_conformable (const struct caseproto *a,
134                                const struct caseproto *b);
135 bool caseproto_equal (const struct caseproto *a, size_t a_start,
136                       const struct caseproto *b, size_t b_start,
137                       size_t n);
138 \f
139 /* Creation and destruction. */
140
141 void caseproto_free__ (struct caseproto *);
142
143 /* Increments case prototype PROTO's reference count and returns
144    PROTO.  Afterward, PROTO is shared among its reference count
145    holders. */
146 static inline struct caseproto *
147 caseproto_ref (const struct caseproto *proto_)
148 {
149   struct caseproto *proto = CONST_CAST (struct caseproto *, proto_);
150   proto->ref_cnt++;
151   return proto;
152 }
153
154 /* Decrements case prototype PROTO's reference count.  Frees
155    PROTO if its reference count drops to 0.
156
157    If PROTO is a null pointer, this function has no effect. */
158 static inline void
159 caseproto_unref (struct caseproto *proto)
160 {
161   if (proto != NULL && !--proto->ref_cnt)
162     caseproto_free__ (proto);
163 }
164 \f
165 /* Inspecting stored widths.  */
166
167 /* Returns case prototype PROTO's width with the given IDX.  IDX
168    must be less than caseproto_get_n_widths(PROTO). */
169 static inline int
170 caseproto_get_width (const struct caseproto *proto, size_t idx)
171 {
172   assert (idx < proto->n_widths);
173   return proto->widths[idx];
174 }
175
176 /* Returns the number of widths in case prototype PROTO. */
177 static inline size_t
178 caseproto_get_n_widths (const struct caseproto *proto)
179 {
180   return proto->n_widths;
181 }
182 \f
183 /* Inspecting the cache of long string widths. */
184
185 void caseproto_refresh_long_string_cache__ (const struct caseproto *);
186
187 /* Returns the number of long string widths in PROTO; that is,
188    the number of widths in PROTO that are greater than to
189    MAX_SHORT_STRING. */
190 static inline size_t
191 caseproto_get_n_long_strings (const struct caseproto *proto)
192 {
193   return proto->n_long_strings;
194 }
195
196 /* Given long string width IDX1, returns a value IDX2 for which
197    caseproto_get_width(PROTO, IDX2) will return a value greater
198    than MAX_SHORT_STRING.  IDX1 must be less than
199    caseproto_get_n_long_strings(PROTO), and IDX2 will be less
200    than caseproto_get_n_widths(PROTO). */
201 static inline size_t
202 caseproto_get_long_string_idx (const struct caseproto *proto, size_t idx1)
203 {
204   if (proto->long_strings == NULL)
205     caseproto_refresh_long_string_cache__ (proto);
206
207   assert (idx1 < proto->n_long_strings);
208   return proto->long_strings[idx1];
209 }
210
211 #endif /* data/caseproto.h */