gui: Allow File|Open to select an encoding for system files.
[pspp] / src / output / table.h
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 1997, 1998, 1999, 2000, 2009 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 OUTPUT_TABLE_H
18 #define OUTPUT_TABLE_H 1
19
20 /* Tables.
21
22 .  A table is a rectangular grid of cells.  Cells can be joined to form larger
23    cells.  Rows and columns can be separated by rules of various types.  Rows
24    at the top and bottom of a table and columns at the left and right edges of
25    a table can be designated as headers, which means that if the table must be
26    broken across more than one page, those rows or columns are repeated on each
27    page.
28
29    Every table is an instance of a particular table class that is responsible
30    for keeping track of cell data.  By far the most common table class is
31    struct tab_table (see output/tab.h).  This header also declares some other
32    kinds of table classes, near the end of the file.
33
34    A table is not itself an output_item, and thus a table cannot by itself be
35    used for output, but they can be embedded inside struct table_item (see
36    table-item.h) for that purpose. */
37
38 #include <stdbool.h>
39 #include <stddef.h>
40
41 struct casereader;
42 struct fmt_spec;
43 struct variable;
44
45 /* Properties of a table cell. */
46 enum
47   {
48     TAB_NONE = 0,
49
50     /* Alignment of cell contents. */
51     TAB_RIGHT      = 0 << 0,    /* Right justify. */
52     TAB_LEFT       = 1 << 0,    /* Left justify. */
53     TAB_CENTER     = 2 << 0,    /* Centered. */
54     TAB_ALIGNMENT  = 3 << 0,    /* Alignment mask. */
55
56     /* These flags may be combined with any alignment. */
57     TAB_EMPH       = 1 << 2,    /* Emphasize cell contents. */
58     TAB_FIX        = 1 << 3,    /* Use fixed font. */
59
60     /* Bits with values (1 << TAB_FIRST_AVAILABLE) and higher are
61        not used, so they are available for subclasses to use as
62        they wish. */
63     TAB_FIRST_AVAILABLE = 4
64   };
65
66 /* Styles for the rules around table cells. */
67 enum
68   {
69     TAL_0,                      /* No line. */
70     TAL_GAP,                    /* Spacing but no line. */
71     TAL_1,                      /* Single line. */
72     TAL_2,                      /* Double line. */
73     N_LINES
74   };
75
76 /* Given line styles A and B (each one of the TAL_* enumeration constants
77    above), returns a line style that "combines" them, that is, that gives a
78    reasonable line style choice for a rule for different reasons should have
79    both styles A and B.
80
81    Used especially for pasting tables together (see table_paste()). */
82 static inline int table_rule_combine (int a, int b)
83 {
84   return a > b ? a : b;
85 }
86
87 /* A table axis.
88
89    Many table-related declarations use 2-element arrays in place of "x" and "y"
90    variables.  This reduces code duplication significantly, because much table
91    code has treat rows and columns the same way.
92
93    A lot of code that uses these enumerations assumes that the two values are 0
94    and 1, so don't change them to other values. */
95 enum table_axis
96   {
97     TABLE_HORZ,
98     TABLE_VERT,
99     TABLE_N_AXES
100   };
101
102 /* A table. */
103 struct table
104   {
105     const struct table_class *klass;
106
107     /* Table size.
108
109        n[TABLE_HORZ]: Number of columns.
110        n[TABLE_VERT]: Number of rows. */
111     int n[TABLE_N_AXES];
112
113     /* Table headers.
114
115        Rows at the top and bottom of a table and columns at the left and right
116        edges of a table can be designated as headers.  If the table must be
117        broken across more than one page for output, headers rows and columns
118        are repeated on each page.
119
120        h[TABLE_HORZ][0]: Left header columns.
121        h[TABLE_HORZ][1]: Right header columns.
122        h[TABLE_VERT][0]: Top header rows.
123        h[TABLE_VERT][1]: Bottom header rows. */
124     int h[TABLE_N_AXES][2];
125
126     /* Reference count.  A table may be shared between multiple owners,
127        indicated by a reference count greater than 1.  When this is the case,
128        the table must not be modified. */
129     int ref_cnt;
130   };
131
132 /* Reference counting. */
133 struct table *table_ref (const struct table *);
134 void table_unref (struct table *);
135 bool table_is_shared (const struct table *);
136 struct table *table_unshare (struct table *);
137
138 /* Returns the number of columns or rows, respectively, in T. */
139 static inline int table_nc (const struct table *t)
140         { return t->n[TABLE_HORZ]; }
141 static inline int table_nr (const struct table *t)
142         { return t->n[TABLE_VERT]; }
143
144 /* Returns the number of left, right, top, or bottom headers, respectively, in
145    T.  */
146 static inline int table_hl (const struct table *t)
147         { return t->h[TABLE_HORZ][0]; }
148 static inline int table_hr (const struct table *t)
149         { return t->h[TABLE_HORZ][1]; }
150 static inline int table_ht (const struct table *t)
151         { return t->h[TABLE_VERT][0]; }
152 static inline int table_hb (const struct table *t)
153         { return t->h[TABLE_VERT][1]; }
154
155 /* Set headers. */
156 void table_set_hl (struct table *, int hl);
157 void table_set_hr (struct table *, int hr);
158 void table_set_ht (struct table *, int ht);
159 void table_set_hb (struct table *, int hb);
160 \f
161 /* Table classes. */
162
163 /* Simple kinds of tables. */
164 struct table *table_from_string (unsigned int options, const char *);
165 struct table *table_from_variables (unsigned int options,
166                                     struct variable **, size_t);
167 struct table *table_from_casereader (const struct casereader *,
168                                      size_t column,
169                                      const char *heading,
170                                      const struct fmt_spec *);
171
172 /* Combining tables. */
173 struct table *table_paste (struct table *, struct table *,
174                            enum table_axis orientation);
175 struct table *table_hpaste (struct table *left, struct table *right);
176 struct table *table_vpaste (struct table *top, struct table *bottom);
177
178 /* Taking subsets of tables. */
179 struct table *table_select (struct table *, int rect[TABLE_N_AXES][2]);
180 struct table *table_select_slice (struct table *, enum table_axis,
181                                   int z0, int z1, bool add_headers);
182 struct table *table_select_columns (struct table *,
183                                     int x0, int x1, bool add_headers);
184 struct table *table_select_rows (struct table *,
185                                  int y0, int y1, bool add_headers);
186
187 /* Miscellaneous table operations. */
188 struct table *table_transpose (struct table *);
189
190 #endif /* output/table.h */