pintos-os.org Git - pspp/blob - src/output/table.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997, 1998, 1999, 2000, 2009, 2013, 2014 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 table_item;
  44 struct variable;
  45
  46 /* Properties of a table cell. */
  47 enum
  48   {
  49     TAB_NONE = 0,
  50
  51     /* Horizontal alignment of cell contents. */
  52     TAB_RIGHT      = 0 << 0,
  53     TAB_LEFT       = 1 << 0,
  54     TAB_CENTER     = 2 << 0,
  55     TAB_HALIGN     = 3 << 0,    /* Alignment mask. */
  56
  57     /* Vertical alignment of cell contents. */
  58     TAB_TOP        = 0 << 2,
  59     TAB_MIDDLE     = 1 << 2,
  60     TAB_BOTTOM     = 2 << 2,
  61     TAB_VALIGN     = 3 << 2,    /* Alignment mask. */
  62
  63     /* These flags may be combined with any alignment. */
  64     TAB_EMPH       = 1 << 4,    /* Emphasize cell contents. */
  65     TAB_FIX        = 1 << 5,    /* Use fixed font. */
  66
  67     /* Bits with values (1 << TAB_FIRST_AVAILABLE) and higher are
  68        not used, so they are available for subclasses to use as
  69        they wish. */
  70     TAB_FIRST_AVAILABLE = 6
  71   };
  72
  73 /* Styles for the rules around table cells. */
  74 enum
  75   {
  76     TAL_NONE,                   /* No spacing. */
  77 #define TAL_0 TAL_NONE
  78     TAL_SOLID,
  79 #define TAL_1 TAL_SOLID
  80     TAL_DASHED,
  81     TAL_THICK,
  82     TAL_THIN,
  83     TAL_DOUBLE,
  84 #define TAL_2 TAL_DOUBLE
  85     N_LINES
  86   };
  87
  88 /* Given line styles A and B (each one of the TAL_* enumeration constants
  89    above), returns a line style that "combines" them, that is, that gives a
  90    reasonable line style choice for a rule for different reasons should have
  91    both styles A and B.
  92
  93    Used especially for pasting tables together (see table_paste()). */
  94 static inline int table_rule_combine (int a, int b)
  95 {
  96   return a > b ? a : b;
  97 }
  98
  99 /* A table axis.
 100
 101    Many table-related declarations use 2-element arrays in place of "x" and "y"
 102    variables.  This reduces code duplication significantly, because much table
 103    code has treat rows and columns the same way.
 104
 105    A lot of code that uses these enumerations assumes that the two values are 0
 106    and 1, so don't change them to other values. */
 107 enum table_axis
 108   {
 109     TABLE_HORZ,
 110     TABLE_VERT,
 111     TABLE_N_AXES
 112   };
 113
 114 /* A table. */
 115 struct table
 116   {
 117     const struct table_class *klass;
 118
 119     /* Table size.
 120
 121        n[TABLE_HORZ]: Number of columns.
 122        n[TABLE_VERT]: Number of rows. */
 123     int n[TABLE_N_AXES];
 124
 125     /* Table headers.
 126
 127        Rows at the top and bottom of a table and columns at the left and right
 128        edges of a table can be designated as headers.  If the table must be
 129        broken across more than one page for output, headers rows and columns
 130        are repeated on each page.
 131
 132        h[TABLE_HORZ][0]: Left header columns.
 133        h[TABLE_HORZ][1]: Right header columns.
 134        h[TABLE_VERT][0]: Top header rows.
 135        h[TABLE_VERT][1]: Bottom header rows. */
 136     int h[TABLE_N_AXES][2];
 137
 138     /* Reference count.  A table may be shared between multiple owners,
 139        indicated by a reference count greater than 1.  When this is the case,
 140        the table must not be modified. */
 141     int ref_cnt;
 142   };
 143
 144 /* Reference counting. */
 145 struct table *table_ref (const struct table *);
 146 void table_unref (struct table *);
 147 bool table_is_shared (const struct table *);
 148 struct table *table_unshare (struct table *);
 149
 150 /* Returns the number of columns or rows, respectively, in T. */
 151 static inline int table_nc (const struct table *t)
 152         { return t->n[TABLE_HORZ]; }
 153 static inline int table_nr (const struct table *t)
 154         { return t->n[TABLE_VERT]; }
 155
 156 /* Returns the number of left, right, top, or bottom headers, respectively, in
 157    T.  */
 158 static inline int table_hl (const struct table *t)
 159         { return t->h[TABLE_HORZ][0]; }
 160 static inline int table_hr (const struct table *t)
 161         { return t->h[TABLE_HORZ][1]; }
 162 static inline int table_ht (const struct table *t)
 163         { return t->h[TABLE_VERT][0]; }
 164 static inline int table_hb (const struct table *t)
 165         { return t->h[TABLE_VERT][1]; }
 166
 167 /* Set headers. */
 168 void table_set_hl (struct table *, int hl);
 169 void table_set_hr (struct table *, int hr);
 170 void table_set_ht (struct table *, int ht);
 171 void table_set_hb (struct table *, int hb);
 172 \f
 173 /* Table classes. */
 174
 175 /* Simple kinds of tables. */
 176 struct table *table_from_string (unsigned int options, const char *);
 177 struct table *table_from_string_span (unsigned int options, const char *,
 178                                       int colspan, int rowspan);
 179 struct table *table_from_variables (unsigned int options,
 180                                     struct variable **, size_t);
 181 struct table *table_from_casereader (const struct casereader *,
 182                                      size_t column,
 183                                      const char *heading,
 184                                      const struct fmt_spec *);
 185
 186 /* Combining tables. */
 187 struct table *table_paste (struct table *, struct table *,
 188                            enum table_axis orientation);
 189 struct table *table_hpaste (struct table *left, struct table *right);
 190 struct table *table_vpaste (struct table *top, struct table *bottom);
 191 struct table *table_stomp (struct table *);
 192
 193 /* Taking subsets of tables. */
 194 struct table *table_select (struct table *, int rect[TABLE_N_AXES][2]);
 195 struct table *table_select_slice (struct table *, enum table_axis,
 196                                   int z0, int z1, bool add_headers);
 197 struct table *table_select_columns (struct table *,
 198                                     int x0, int x1, bool add_headers);
 199 struct table *table_select_rows (struct table *,
 200                                  int y0, int y1, bool add_headers);
 201
 202 /* Miscellaneous table operations. */
 203 struct table *table_transpose (struct table *);
 204
 205 #endif /* output/table.h */