-/* PSPP - computes sample statistics.
- Copyright (C) 1997-9, 2000 Free Software Foundation, Inc.
- Written by Ben Pfaff <blp@gnu.org>.
+/* PSPP - a program for statistical analysis.
+ Copyright (C) 1997, 1998, 1999, 2000, 2009, 2013, 2014 Free Software Foundation, Inc.
- This program is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License as
- published by the Free Software Foundation; either version 2 of the
- License, or (at your option) any later version.
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
- 02110-1301, USA. */
+ along with this program. If not, see <http://www.gnu.org/licenses/>. */
-#if !tab_h
-#define tab_h 1
+#ifndef OUTPUT_TABLE_H
+#define OUTPUT_TABLE_H 1
-#include <limits.h>
-#include "str.h"
+/* Tables.
-/* Cell options. */
-enum
- {
- TAB_NONE = 0,
+. A table is a rectangular grid of cells. Cells can be joined to form larger
+ cells. Rows and columns can be separated by rules of various types. Rows
+ at the top and bottom of a table and columns at the left and right edges of
+ a table can be designated as headers, which means that if the table must be
+ broken across more than one page, those rows or columns are repeated on each
+ page.
- /* Must match output.h: OUTP_T_JUST_*. */
- TAB_ALIGN_MASK = 03, /* Alignment mask. */
- TAB_RIGHT = 00, /* Right justify. */
- TAB_LEFT = 01, /* Left justify. */
- TAB_CENTER = 02, /* Center. */
+ Every table is an instance of a particular table class that is responsible
+ for keeping track of cell data. By far the most common table class is
+ struct tab_table (see output/tab.h). This header also declares some other
+ kinds of table classes, near the end of the file.
- /* Oddball cell types. */
- TAB_JOIN = 010, /* Joined cell. */
- TAB_EMPTY = 020 /* Empty cell. */
- };
+ A table is not itself an output_item, and thus a table cannot by itself be
+ used for output, but they can be embedded inside struct table_item (see
+ table-item.h) for that purpose. */
-/* Line styles. These must match output.h:OUTP_L_*. */
-enum
- {
- TAL_0 = 0, /* No line. */
- TAL_1 = 1, /* Single line. */
- TAL_2 = 2, /* Double line. */
- TAL_3 = 3, /* Special line of driver-defined style. */
- TAL_COUNT, /* Number of line styles. */
+#include <stdbool.h>
+#include <stddef.h>
- TAL_SPACING = 0200 /* Don't draw the line, just reserve space. */
- };
+struct casereader;
+struct fmt_spec;
+struct table_item;
+struct variable;
-/* Column styles. Must correspond to SOM_COL_*. */
+/* Properties of a table cell. */
enum
{
- TAB_COL_NONE, /* No columns. */
- TAB_COL_DOWN /* Columns down first. */
- };
+ TAB_NONE = 0,
-/* Joined cell. */
-struct tab_joined_cell
- {
- int x1, y1;
- int x2, y2;
- int hit;
- struct fixed_string contents;
- };
+ /* Alignment of cell contents. */
+ TAB_RIGHT = 0 << 0, /* Right justify. */
+ TAB_LEFT = 1 << 0, /* Left justify. */
+ TAB_CENTER = 2 << 0, /* Centered. */
+ TAB_ALIGNMENT = 3 << 0, /* Alignment mask. */
-struct outp_driver;
-struct tab_table;
-typedef void tab_dim_func (struct tab_table *, struct outp_driver *);
+ /* These flags may be combined with any alignment. */
+ TAB_EMPH = 1 << 2, /* Emphasize cell contents. */
+ TAB_FIX = 1 << 3, /* Use fixed font. */
-/* A table. */
-struct tab_table
+ /* Bits with values (1 << TAB_FIRST_AVAILABLE) and higher are
+ not used, so they are available for subclasses to use as
+ they wish. */
+ TAB_FIRST_AVAILABLE = 4
+ };
+
+/* Styles for the rules around table cells. */
+enum
{
- struct pool *container;
-
- /* Contents. */
- int col_style; /* Columns: One of TAB_COL_*. */
- int col_group; /* Number of rows per column group. */
- struct fixed_string title; /* Table title. */
- unsigned flags; /* SOMF_*. */
- int nc, nr; /* Number of columns, rows. */
- int cf; /* Column factor for indexing purposes. */
- int l, r, t, b; /* Number of header rows on each side. */
- struct fixed_string *cc; /* Cell contents; fixed_string *[nr][nc]. */
- unsigned char *ct; /* Cell types; unsigned char[nr][nc]. */
- unsigned char *rh; /* Horiz rules; unsigned char[nr+1][nc]. */
- unsigned char *trh; /* Types of horiz rules; [nr+1]. */
- unsigned char *rv; /* Vert rules; unsigned char[nr][nc+1]. */
- unsigned char *trv; /* Types of vert rules; [nc+1]. */
- tab_dim_func *dim; /* Calculates cell widths and heights. */
-
- /* Calculated during output. */
- int *w; /* Column widths; [nc]. */
- int *h; /* Row heights; [nr]. */
- int *hrh; /* Heights of horizontal rules; [nr+1]. */
- int *wrv; /* Widths of vertical rules; [nc+1]. */
- int wl, wr, ht, hb; /* Width/height of header rows/columns. */
- int hr_tot, vr_tot; /* Hrules total height, vrules total width. */
-
- /* Editing info. */
- int col_ofs, row_ofs; /* X and Y offsets. */
-#if DEBUGGING
- int reallocable; /* Can table be reallocated? */
-#endif
+ TAL_0, /* No line. */
+ TAL_GAP, /* Spacing but no line. */
+ TAL_1, /* Single line. */
+ TAL_2, /* Double line. */
+ N_LINES
};
-extern int tab_hit;
+/* Given line styles A and B (each one of the TAL_* enumeration constants
+ above), returns a line style that "combines" them, that is, that gives a
+ reasonable line style choice for a rule for different reasons should have
+ both styles A and B.
-/* Number of rows in TABLE. */
-#define tab_nr(TABLE) ((TABLE)->nr)
+ Used especially for pasting tables together (see table_paste()). */
+static inline int table_rule_combine (int a, int b)
+{
+ return a > b ? a : b;
+}
-/* Number of columns in TABLE. */
-#define tab_nc(TABLE) ((TABLE)->nc)
+/* A table axis.
-/* Number of left header columns in TABLE. */
-#define tab_l(TABLE) ((TABLE)->l)
+ Many table-related declarations use 2-element arrays in place of "x" and "y"
+ variables. This reduces code duplication significantly, because much table
+ code has treat rows and columns the same way.
+
+ A lot of code that uses these enumerations assumes that the two values are 0
+ and 1, so don't change them to other values. */
+enum table_axis
+ {
+ TABLE_HORZ,
+ TABLE_VERT,
+ TABLE_N_AXES
+ };
-/* Number of right header columns in TABLE. */
-#define tab_r(TABLE) ((TABLE)->r)
+/* A table. */
+struct table
+ {
+ const struct table_class *klass;
-/* Number of top header rows in TABLE. */
-#define tab_t(TABLE) ((TABLE)->t)
+ /* Table size.
-/* Number of bottom header rows in TABLE. */
-#define tab_b(TABLE) ((TABLE)->b)
+ n[TABLE_HORZ]: Number of columns.
+ n[TABLE_VERT]: Number of rows. */
+ int n[TABLE_N_AXES];
-/* Tables. */
-struct tab_table *tab_create (int nc, int nr, int reallocable);
-void tab_destroy (struct tab_table *);
-void tab_resize (struct tab_table *, int nc, int nr);
-void tab_realloc (struct tab_table *, int nc, int nr);
-void tab_headers (struct tab_table *, int l, int r, int t, int b);
-void tab_columns (struct tab_table *, int style, int group);
-void tab_title (struct tab_table *, int format, const char *, ...);
-void tab_flags (struct tab_table *, unsigned);
-void tab_submit (struct tab_table *);
+ /* Table headers.
-/* Dimensioning. */
-tab_dim_func tab_natural_dimensions;
-int tab_natural_width (struct tab_table *t, struct outp_driver *d, int c);
-int tab_natural_height (struct tab_table *t, struct outp_driver *d, int r);
-void tab_dim (struct tab_table *, tab_dim_func *);
+ Rows at the top and bottom of a table and columns at the left and right
+ edges of a table can be designated as headers. If the table must be
+ broken across more than one page for output, headers rows and columns
+ are repeated on each page.
-/* Rules. */
-void tab_hline (struct tab_table *, int style, int x1, int x2, int y);
-void tab_vline (struct tab_table *, int style, int x, int y1, int y2);
-void tab_box (struct tab_table *, int f_h, int f_v, int i_h, int i_v,
- int x1, int y1, int x2, int y2);
+ h[TABLE_HORZ][0]: Left header columns.
+ h[TABLE_HORZ][1]: Right header columns.
+ h[TABLE_VERT][0]: Top header rows.
+ h[TABLE_VERT][1]: Bottom header rows. */
+ int h[TABLE_N_AXES][2];
-/* Text options, passed in the `opt' argument. */
-enum
- {
- TAT_NONE = 0, /* No options. */
- TAT_PRINTF = 0x0100, /* Format the text string with sprintf. */
- TAT_TITLE = 0x0204, /* Title attributes. */
- TAT_FIX = 0x0400, /* Use fixed-pitch font. */
- TAT_NOWRAP = 0x0800 /* No text wrap (tab_output_text() only). */
+ /* Reference count. A table may be shared between multiple owners,
+ indicated by a reference count greater than 1. When this is the case,
+ the table must not be modified. */
+ int ref_cnt;
};
-/* Cells. */
-struct fmt_spec;
-union value;
-void tab_value (struct tab_table *, int c, int r, unsigned char opt,
- const union value *, const struct fmt_spec *);
-void tab_float (struct tab_table *, int c, int r, unsigned char opt,
- double v, int w, int d);
-void tab_text (struct tab_table *, int c, int r, unsigned opt,
- const char *, ...)
- PRINTF_FORMAT (5, 6);
-void tab_joint_text (struct tab_table *, int x1, int y1, int x2, int y2,
- unsigned opt, const char *, ...)
- PRINTF_FORMAT (7, 8);
-
-/* Cell low-level access. */
-#define tab_alloc(TABLE, AMT) pool_alloc ((TABLE)->container, (AMT))
-void tab_raw (struct tab_table *, int c, int r, unsigned opt,
- struct fixed_string *);
-
-/* Editing. */
-void tab_offset (struct tab_table *, int col, int row);
-void tab_next_row (struct tab_table *);
-
-/* Current row/column offset. */
-#define tab_row(TABLE) ((TABLE)->row_ofs)
-#define tab_col(TABLE) ((TABLE)->col_ofs)
-
-/* Simple output. */
-void tab_output_text (int options, const char *string, ...)
- PRINTF_FORMAT (2, 3);
-
-/* Embedding the command name in the output. */
-void tab_set_command_name (const char *);
-
-#endif /* tab_h */
-
+/* Reference counting. */
+struct table *table_ref (const struct table *);
+void table_unref (struct table *);
+bool table_is_shared (const struct table *);
+struct table *table_unshare (struct table *);
+
+/* Returns the number of columns or rows, respectively, in T. */
+static inline int table_nc (const struct table *t)
+ { return t->n[TABLE_HORZ]; }
+static inline int table_nr (const struct table *t)
+ { return t->n[TABLE_VERT]; }
+
+/* Returns the number of left, right, top, or bottom headers, respectively, in
+ T. */
+static inline int table_hl (const struct table *t)
+ { return t->h[TABLE_HORZ][0]; }
+static inline int table_hr (const struct table *t)
+ { return t->h[TABLE_HORZ][1]; }
+static inline int table_ht (const struct table *t)
+ { return t->h[TABLE_VERT][0]; }
+static inline int table_hb (const struct table *t)
+ { return t->h[TABLE_VERT][1]; }
+
+/* Set headers. */
+void table_set_hl (struct table *, int hl);
+void table_set_hr (struct table *, int hr);
+void table_set_ht (struct table *, int ht);
+void table_set_hb (struct table *, int hb);
+\f
+/* Table classes. */
+
+/* Simple kinds of tables. */
+struct table *table_from_string (unsigned int options, const char *);
+struct table *table_from_string_span (unsigned int options, const char *,
+ int colspan, int rowspan);
+struct table *table_from_variables (unsigned int options,
+ struct variable **, size_t);
+struct table *table_from_casereader (const struct casereader *,
+ size_t column,
+ const char *heading,
+ const struct fmt_spec *);
+struct table *table_create_nested (struct table *);
+struct table *table_create_nested_item (struct table_item *);
+
+/* Combining tables. */
+struct table *table_paste (struct table *, struct table *,
+ enum table_axis orientation);
+struct table *table_hpaste (struct table *left, struct table *right);
+struct table *table_vpaste (struct table *top, struct table *bottom);
+struct table *table_stomp (struct table *);
+
+/* Taking subsets of tables. */
+struct table *table_select (struct table *, int rect[TABLE_N_AXES][2]);
+struct table *table_select_slice (struct table *, enum table_axis,
+ int z0, int z1, bool add_headers);
+struct table *table_select_columns (struct table *,
+ int x0, int x1, bool add_headers);
+struct table *table_select_rows (struct table *,
+ int y0, int y1, bool add_headers);
+
+/* Miscellaneous table operations. */
+struct table *table_transpose (struct table *);
+
+#endif /* output/table.h */
projects / pspp / blobdiff