src/output/table-provider.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997, 1998, 1999, 2000, 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 OUTPUT_TABLE_PROVIDER
  18 #define OUTPUT_TABLE_PROVIDER 1
  19
  20 #include "output/table.h"
  21
  22 /* A cell in a table. */
  23 struct table_cell
  24   {
  25     /* Occupied table region.
  26
  27        d[TABLE_HORZ][0] is the leftmost column.
  28        d[TABLE_HORZ][1] is the rightmost column, plus 1.
  29        d[TABLE_VERT][0] is the top row.
  30        d[TABLE_VERT][1] is the bottom row, plus 1.
  31
  32        For an ordinary cell:
  33            d[TABLE_HORZ][1] == d[TABLE_HORZ][0] + 1
  34        and d[TABLE_VERT][1] == d[TABLE_VERT][0] + 1
  35
  36        For a joined cell:
  37           d[TABLE_HORZ][1] > d[TABLE_HORZ][0] + 1
  38        or d[TABLE_VERT][1] > d[TABLE_VERT][0] + 1
  39        or both. */
  40     int d[TABLE_N_AXES][2];
  41
  42     const char *contents;       /* Text string contents. */
  43     unsigned int options;       /* TAB_* values. */
  44
  45     /* Called to free the cell's data, if nonnull. */
  46     void (*destructor) (void *destructor_aux);
  47     void *destructor_aux;
  48   };
  49
  50 void table_cell_free (struct table_cell *);
  51
  52 /* Returns the number of columns that CELL spans.  This is 1 for an ordinary
  53    cell and greater than one for a cell that joins multiple columns. */
  54 static inline int
  55 table_cell_colspan (const struct table_cell *cell)
  56 {
  57   return cell->d[TABLE_HORZ][1] - cell->d[TABLE_HORZ][0];
  58 }
  59
  60 /* Returns the number of rows that CELL spans.  This is 1 for an ordinary cell
  61    and greater than one for a cell that joins multiple rows. */
  62 static inline int
  63 table_cell_rowspan (const struct table_cell *cell)
  64 {
  65   return cell->d[TABLE_VERT][1] - cell->d[TABLE_VERT][0];
  66 }
  67
  68 /* Returns true if CELL is a joined cell, that is, if it spans multiple rows
  69    or columns.  Otherwise, returns false. */
  70 static inline bool
  71 table_cell_is_joined (const struct table_cell *cell)
  72 {
  73   return table_cell_colspan (cell) > 1 || table_cell_rowspan (cell) > 1;
  74 }
  75 \f
  76 /* Declarations to allow defining table classes. */
  77
  78 struct table_class
  79   {
  80     /* Frees TABLE.
  81
  82        The table class may assume that any cells that were retrieved by calling
  83        the 'get_cell' function have been freed (by calling their destructors)
  84        before this function is called. */
  85     void (*destroy) (struct table *table);
  86
  87     /* Initializes CELL with the contents of the table cell at column X and row
  88        Y within TABLE.  All members of CELL must be initialized, except that if
  89        'destructor' is set to a null pointer, then 'destructor_aux' need not be
  90        initialized.  The 'contents' member of CELL must be set to a nonnull
  91        value.
  92
  93        The table class must allow any number of cells in the table to be
  94        retrieved simultaneously; that is, TABLE must not assume that a given
  95        cell will be freed before another one is retrieved using 'get_cell'.
  96
  97        The table class must allow joined cells to be retrieved, with identical
  98        contents, using any (X,Y) location inside the cell.
  99
 100        The table class must not allow cells to overlap.
 101
 102        The table class should not allow a joined cell to cross the border
 103        between header rows/columns and the interior of the table.  That is, a
 104        joined cell should be entirely within headers rows and columns or
 105        entirely outside them.
 106
 107        The table class may assume that CELL will be freed before TABLE is
 108        destroyed. */
 109     void (*get_cell) (const struct table *table, int x, int y,
 110                       struct table_cell *cell);
 111
 112     /* Returns one of the TAL_* enumeration constants (declared in
 113        output/table.h) representing a rule running alongside one of the cells
 114        in TABLE.
 115
 116        See table_get_rule() in table.c for a detailed explanation of the
 117        meaning of AXIS and X and Y, including a diagram. */
 118     int (*get_rule) (const struct table *table,
 119                      enum table_axis axis, int x, int y);
 120
 121     /* This function is optional and most table classes will not implement it.
 122
 123        If provided, this function must take ownership of A and B and return a
 124        table that consists of tables A and B "pasted together", that is, a
 125        table whose size is the sum of the sizes of A and B along the axis
 126        specified by ORIENTATION.  A and B will ordinarily have the same size
 127        along the axis opposite ORIENTATION; no particular handling of tables
 128        that have different sizes along that axis is required.
 129
 130        The handling of rules at the seam between A and B is not specified, but
 131        table_rule_combine() is one reasonable way to do it.
 132
 133        Called only if neither A and B is shared (as returned by
 134        table_is_shared()).
 135
 136        Called if A or B or both is of the class defined by this table class.
 137        That is, the implementation must be prepared to deal with the case where
 138        A or B is not the ordinarily expected table class.
 139
 140        This function may return a null pointer if it cannot implement the paste
 141        operation, in which case the caller will use a fallback
 142        implementation.
 143
 144        This function is used to implement table_paste(). */
 145     struct table *(*paste) (struct table *a, struct table *b,
 146                             enum table_axis orientation);
 147
 148     /* This function is optional and most table classes will not implement it.
 149
 150        If provided, this function must take ownership of TABLE and return a new
 151        table whose contents are the TABLE's rows RECT[TABLE_VERT][0] through
 152        RECT[TABLE_VERT][1], exclusive, and the TABLE's columns
 153        RECT[TABLE_HORZ][0] through RECT[TABLE_HORZ][1].
 154
 155        Called only if TABLE is not shared (as returned by table_is_shared()).p
 156
 157        This function may return a null pointer if it cannot implement the
 158        select operation, in which case the caller will use a fallback
 159        implementation.
 160
 161        This function is used to implement table_select(). */
 162     struct table *(*select) (struct table *table, int rect[TABLE_N_AXES][2]);
 163   };
 164
 165 void table_init (struct table *, const struct table_class *);
 166
 167 /* Table class implementations can call these functions or just set the
 168    table's n[] and h[][] members directly. */
 169 void table_set_nc (struct table *, int nc);
 170 void table_set_nr (struct table *, int nr);
 171 \f
 172 /* For use primarily by output drivers. */
 173
 174 void table_get_cell (const struct table *, int x, int y, struct table_cell *);
 175 int table_get_rule (const struct table *, enum table_axis, int x, int y);
 176
 177 #endif /* output/table-provider.h */