1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 2017-2018 Free Software Foundation, Inc.
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.
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.
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/>. */
17 #ifndef OUTPUT_PIVOT_TABLE_H
18 #define OUTPUT_PIVOT_TABLE_H 1
22 #include "data/format.h"
23 #include "data/settings.h"
24 #include "libpspp/compiler.h"
25 #include "libpspp/hmap.h"
26 #include "output/table.h"
36 Pivot tables are PSPP's primary form of output. They are analogous to the
37 pivot tables you might be familiar with from spreadsheets and databases.
38 See https://en.wikipedia.org/wiki/Pivot_table for a brief introduction to
39 the overall concept of a pivot table.
41 In PSPP, the most important internal pieces of a pivot table are:
43 - Title. Every pivot table has a title that is displayed above it. It also
44 has an optional caption (displayed below it) and corner text (displayed in
45 the upper left corner).
47 - Dimensions. A dimension consists of zero or more categories. A category
48 has a label, such as "df" or "Asymp. Sig." or 123 or a variable name. The
49 categories are the leaves of a tree whose non-leaf nodes form groups of
50 categories. The tree always has a root group whose label is the name of
53 - Axes. A table has three axes: column, row, and layer. Each dimension is
54 assigned to an axis, and each axis has zero or more dimensions. When an
55 axis has more than one dimension, they are ordered from innermost to
58 - Data. A table's data consists of zero or more cells. Each cell maps from
59 a category for each dimension to a value, which is commonly a number but
60 could also be a variable name or an arbitrary text string.
62 Creating a pivot table usually consists of the following steps:
64 1. Create the table with pivot_table_create(), passing in the title.
66 2. Optionally, set the format to use for "count" values with
67 pivot_table_set_weight_var() or pivot_table_set_weight_format().
69 3. Create each dimension with pivot_dimension_create() and populate it with
70 categories and, possibly, with groups that contain the categories. This
71 call also assigns the dimension to an axis.
73 In simple cases, only a call to pivot_dimension_create() is needed.
74 Other functions such as pivot_category_create_group() can be used for
75 hierarchies of categories.
77 Sometimes it's easier to create categories in tandem with inserting data,
78 for example by adding a category for a variable just before inserting the
79 first cell for that variable. In that case, creating categories and
80 inserting data can be interleaved.
82 4. Insert data. For each cell, supply the category indexes, which are
83 assigned starting from 0 in the order in which the categories were
84 created in step 2, and the value to go in the cell. If the table has a
85 small, fixed number of dimensions, functions like, e.g.
86 pivot_table_put3() for 3 dimensions, can be used. The general function
87 pivot_table_put() works for other cases.
89 5. Output the table for user consumption. Use pivot_table_submit(). */
91 /* Pivot table display styling. */
93 /* Areas of a pivot table for styling purposes. */
98 PIVOT_AREA_FOOTER, /* Footnotes. */
99 PIVOT_AREA_CORNER, /* Top-left corner. */
100 PIVOT_AREA_COLUMN_LABELS,
101 PIVOT_AREA_ROW_LABELS,
103 PIVOT_AREA_LAYERS, /* Layer indication. */
107 const char *pivot_area_to_string (enum pivot_area);
109 /* Table borders for styling purposes. */
115 PIVOT_BORDER_OUTER_LEFT,
116 PIVOT_BORDER_OUTER_TOP,
117 PIVOT_BORDER_OUTER_RIGHT,
118 PIVOT_BORDER_OUTER_BOTTOM,
121 PIVOT_BORDER_INNER_LEFT,
122 PIVOT_BORDER_INNER_TOP,
123 PIVOT_BORDER_INNER_RIGHT,
124 PIVOT_BORDER_INNER_BOTTOM,
127 PIVOT_BORDER_DATA_LEFT,
128 PIVOT_BORDER_DATA_TOP,
131 PIVOT_BORDER_DIM_ROW_HORZ,
132 PIVOT_BORDER_DIM_ROW_VERT,
133 PIVOT_BORDER_DIM_COL_HORZ,
134 PIVOT_BORDER_DIM_COL_VERT,
137 PIVOT_BORDER_CAT_ROW_HORZ,
138 PIVOT_BORDER_CAT_ROW_VERT,
139 PIVOT_BORDER_CAT_COL_HORZ,
140 PIVOT_BORDER_CAT_COL_VERT,
145 const char *pivot_border_to_string (enum pivot_border);
147 /* Sizing for rows or columns of a rendered table. The comments below talk
148 about columns and their widths but they apply equally to rows and their
150 struct pivot_table_sizing
152 /* Specific column widths, in 1/96" units. */
156 /* Specific page breaks: 0-based columns after which a page break must
157 occur, e.g. a value of 1 requests a break after the second column. */
161 /* Keeps: columns to keep together on a page if possible. */
162 struct pivot_keep *keeps;
166 void pivot_table_sizing_uninit (struct pivot_table_sizing *);
168 /* A set of columns to keep together on a page if possible, e.g. ofs=1, n=10
169 requests keeping together the 2nd through 11th columns. */
172 size_t ofs; /* 0-based first column. */
173 size_t n; /* Number of columns. */
183 #define PIVOT_N_AXES 3
186 const char *pivot_axis_type_to_string (enum pivot_axis_type);
188 /* An axis within a pivot table. */
191 /* dimensions[0] is the innermost dimension,
192 dimensions[1] is the next outer dimension,
194 dimensions[n_dimensions - 1] is the outermost dimension. */
195 struct pivot_dimension **dimensions;
198 /* The number of rows or columns along the axis,
199 that is, the product of dimension[*]->n_leaves.
200 It is 0 if any dimension has 0 leaves. */
203 /* Sum of dimensions[*]->label_depth. */
207 /* Successively assigns to INDEXES (which should be a "size_t *") each of the
208 combinations of the categories in AXIS's dimensions, in lexicographic order
209 with the innermost dimension iterating most quickly.
211 The value assigned to INDEXES is dynamically allocated. If the client
212 breaks out of the loop prematurely, it needs to free it with free(). */
213 #define PIVOT_AXIS_FOR_EACH(INDEXES, AXIS) \
214 for ((INDEXES) = NULL; \
215 ((INDEXES) = pivot_axis_iterator_next (INDEXES, AXIS)) != NULL;)
216 size_t *pivot_axis_iterator_next (size_t *indexes, const struct pivot_axis *);
220 A pivot_dimension identifies the categories associated with a single
221 dimension within a multidimensional pivot table.
223 A dimension contains a collection of categories, which are the leaves in a
226 (A dimension or a group can contain zero categories, but this is unusual.
227 If a dimension contains no categories, then its table cannot contain any
230 struct pivot_dimension
232 /* table->axes[axis_type]->dimensions[level] == dimension. */
233 struct pivot_table *table;
234 enum pivot_axis_type axis_type;
235 size_t level; /* 0 for innermost dimension within axis. */
237 /* table->dimensions[top_index] == dimension. */
240 /* Hierarchy of categories within the dimension. The groups and categories
241 are sorted in the order that should be used for display. This might be
242 different from the original order produced for output if the user
245 The root must always be a group, although it is allowed to have no
247 struct pivot_category *root;
249 /* All of the leaves reachable via the root.
251 The indexing for presentation_leaves is presentation order, thus
252 presentation_leaves[i]->presentation_index == i. This order is the same
253 as would be produced by an in-order traversal of the groups. It is the
254 order into which the user reordered or sorted the categories.
256 The indexing for data_leaves is that used for idx[] in struct
257 pivot_cell, thus data_leaves[i]->data_index == i. This might differ
258 from what an in-order traversal of 'root' would yield, if the user
259 reordered categories. */
260 struct pivot_category **data_leaves;
261 struct pivot_category **presentation_leaves;
262 size_t n_leaves, allocated_leaves;
265 bool hide_all_labels;
267 /* Number of rows or columns needed to express the labels. */
271 struct pivot_dimension *pivot_dimension_create (
272 struct pivot_table *, enum pivot_axis_type, const char *name, ...)
274 #define pivot_dimension_create(...) \
275 pivot_dimension_create(__VA_ARGS__, NULL_SENTINEL)
276 struct pivot_dimension *pivot_dimension_create__ (struct pivot_table *,
277 enum pivot_axis_type,
278 struct pivot_value *name);
280 void pivot_dimension_destroy (struct pivot_dimension *);
282 void pivot_dimension_dump (const struct pivot_dimension *,
283 const struct pivot_table *, int indentation);
285 /* Split file handling with pivot tables.
287 When SPLIT FILE is in effect with the LAYERED option, values for the split
288 file variables need to be incorporated into pivot table output. These
289 functions make that easier.
293 1. After adding the rest of the dimensions to an output pivot table, call
294 pivot_splits_create(). If there are any and LAYERED mode is in use, then
295 pivot_splits_create() will add a dimension for each split file
296 variable and return a structure. Otherwise, it returns NULL.
298 2. Before adding data to the pivot table for each SPLIT FILE group, call
299 pivot_splits_new_split(), passing in an example case from the group (the
300 first or last case is fine). This will the split file handler add
301 categories for the group to the split dimensions.
303 pivot_splits_new_split() does nothing if given a null pivot_splits, so
304 it's fine to call it unconditionally.
306 3. Use pivot_splits_put*(), instead of pivot_table_put*(), to add data to
307 the pivot table. These functions automatically add the current group
308 leaf indexes after the indexes passed in, as a convenience.
310 These functions still work fine if given a null pivot_splits, so it's
311 fine to use them in all cases.
313 4. Destroy the pivot_splits with pivot_splits_destroy() when the pivot table
314 has been fully constructed. */
316 struct pivot_splits *pivot_splits_create (struct pivot_table *,
317 enum pivot_axis_type,
318 const struct dictionary *);
319 void pivot_splits_destroy (struct pivot_splits *);
321 void pivot_splits_new_split (struct pivot_splits *, const struct ccase *);
323 void pivot_splits_put1 (struct pivot_splits *, struct pivot_table *,
324 size_t idx1, struct pivot_value *);
325 void pivot_splits_put2 (struct pivot_splits *, struct pivot_table *,
326 size_t idx1, size_t idx2, struct pivot_value *);
327 void pivot_splits_put3 (struct pivot_splits *, struct pivot_table *,
328 size_t idx1, size_t idx2, size_t idx3,
329 struct pivot_value *);
330 void pivot_splits_put4 (struct pivot_splits *, struct pivot_table *,
331 size_t idx1, size_t idx2, size_t idx3, size_t idx4,
332 struct pivot_value *);
334 /* A pivot_category is a leaf (a category) or a group:
336 - For a leaf, neither index is SIZE_MAX.
338 - For a group, both indexes are SIZE_MAX.
340 Do not use 'subs' or 'n_subs' to determine whether a category is a group,
341 because a group may (pathologically) have no leaves. */
342 struct pivot_category
344 struct pivot_value *name;
345 struct pivot_category *parent;
346 struct pivot_dimension *dimension;
347 size_t label_depth, extra_depth;
351 If show_label is true, then the group itself has a row (or a column)
352 giving the group's name. Otherwise, the group's own name is not
354 struct pivot_category **subs; /* Child categories or groups. */
355 size_t n_subs, allocated_subs;
356 bool show_label; /* Display a label for the group itself? */
357 bool show_label_in_corner;
360 size_t group_index; /* In ->parent->subs[]. */
361 size_t data_index; /* In ->dimension->data_leaves[]. */
362 size_t presentation_index; /* In ->dimension->presentation_leaves[]. */
363 struct fmt_spec format; /* Default format for values in this category. */
364 bool honor_small; /* Honor pivot_table 'small' setting? */
368 pivot_category_is_group (const struct pivot_category *category)
370 return category->data_index == SIZE_MAX;
374 pivot_category_is_leaf (const struct pivot_category *category)
376 return !pivot_category_is_group (category);
379 /* Creating leaf categories. */
380 int pivot_category_create_leaves (struct pivot_category *parent, ...)
382 #define pivot_category_create_leaves(...) \
383 pivot_category_create_leaves(__VA_ARGS__, NULL_SENTINEL)
385 int pivot_category_create_leaf (
386 struct pivot_category *parent, struct pivot_value *name);
387 int pivot_category_create_leaf_rc (
388 struct pivot_category *parent, struct pivot_value *name, const char *rc);
390 /* Creating category groups. */
391 struct pivot_category *pivot_category_create_group (
392 struct pivot_category *parent, const char *name, ...) SENTINEL (0);
393 #define pivot_category_create_group(...) \
394 pivot_category_create_group(__VA_ARGS__, NULL_SENTINEL)
395 struct pivot_category *pivot_category_create_group__ (
396 struct pivot_category *parent, struct pivot_value *name);
398 void pivot_category_destroy (struct pivot_category *);
400 /* Pivot result classes.
402 These are used to mark leaf categories as having particular types of data,
403 to set their numeric formats. The formats that actually get used for these
404 classes are in the result_classes[] global array in pivot-table.c, except
405 that PIVOT_RC_OTHER comes from settings_get_format() and PIVOT_RC_COUNT
406 should come from the weight variable in the dataset's dictionary. */
407 #define PIVOT_RC_OTHER ("RC_OTHER")
408 #define PIVOT_RC_INTEGER ("RC_INTEGER")
409 #define PIVOT_RC_CORRELATION ("RC_CORRELATIONS")
410 #define PIVOT_RC_SIGNIFICANCE ("RC_SIGNIFICANCE")
411 #define PIVOT_RC_PERCENT ("RC_PERCENT")
412 #define PIVOT_RC_RESIDUAL ("RC_RESIDUAL")
413 #define PIVOT_RC_COUNT ("RC_COUNT")
415 bool pivot_result_class_change (const char *, const struct fmt_spec *);
416 bool is_pivot_result_class (const char *);
418 /* Styling for a pivot table.
420 The division between this and the style information in struct pivot_table
421 seems fairly arbitrary. The ultimate reason for the division is simply
422 because that's how SPSS documentation and file formats do it. */
423 struct pivot_table_look
425 /* Reference count. A pivot_table_look may be shared between multiple
426 owners, indicated by a reference count greater than 1. When this is the
427 case, the pivot_table must not be modified. */
430 char *name; /* May be null. */
432 /* General properties.
434 col_heading_width_range and row_heading_width_range is minimum and
435 maximum width of columns based on their column heading labels, in 1/96"
436 units. row_heading_width_range is for columns in the row headings and
437 corner, and col_heading_width_range is for columns in the column
441 bool row_labels_in_corner;
442 int row_heading_width_range[2];
443 int col_heading_width_range[2];
445 /* Footnote display settings. */
446 bool show_numeric_markers;
447 bool footnote_marker_superscripts;
450 struct table_area_style areas[PIVOT_N_AREAS];
451 struct table_border_style borders[PIVOT_N_BORDERS];
453 /* Print settings. */
454 bool print_all_layers;
455 bool paginate_layers;
456 bool shrink_to_fit[TABLE_N_AXES];
457 bool top_continuation, bottom_continuation;
459 size_t n_orphan_lines;
462 const struct pivot_table_look *pivot_table_look_get_default (void);
463 void pivot_table_look_set_default (const struct pivot_table_look *);
465 char *pivot_table_look_read (const char *, struct pivot_table_look **)
468 const struct pivot_table_look *pivot_table_look_builtin_default (void);
469 struct pivot_table_look *pivot_table_look_new_builtin_default (void);
470 struct pivot_table_look *pivot_table_look_ref (
471 const struct pivot_table_look *);
472 void pivot_table_look_unref (struct pivot_table_look *);
473 struct pivot_table_look *pivot_table_look_unshare (struct pivot_table_look *);
475 /* A pivot table. See the top of this file for more information. */
478 /* Reference count. A pivot_table may be shared between multiple owners,
479 indicated by a reference count greater than 1. When this is the case,
480 the pivot_table must not be modified. */
484 struct pivot_table_look *look;
486 /* Display settings. */
487 bool rotate_inner_column_labels;
488 bool rotate_outer_row_labels;
489 bool show_grid_lines;
492 enum settings_value_show show_values;
493 enum settings_value_show show_variables;
494 struct fmt_spec weight_format;
496 /* Current layer indexes, with axes[PIVOT_AXIS_LAYER].n_dimensions
497 elements. current_layer[i] is an offset into
498 axes[PIVOT_AXIS_LAYER].dimensions[i]->data_leaves[], EXCEPT that a
499 dimension can have zero leaves, in which case current_layer[i] is zero
500 and there's no corresponding leaf. */
501 size_t *current_layer;
503 /* Column and row sizing and page breaks.
504 sizing[TABLE_HORZ] is for columns, sizing[TABLE_VERT] is for rows. */
505 struct pivot_table_sizing sizing[TABLE_N_AXES];
507 /* Format settings. */
508 struct fmt_settings settings;
509 char grouping; /* Usually '.' or ','. */
512 /* Command information. */
513 char *command_local; /* May be NULL. */
514 char *command_c; /* May be NULL. */
515 char *language; /* May be NULL. */
516 char *locale; /* May be NULL. */
518 /* Source information. */
519 char *dataset; /* May be NULL. */
520 char *datafile; /* May be NULL. */
521 time_t date; /* May be 0 if unknown. */
524 struct pivot_footnote **footnotes;
525 size_t n_footnotes, allocated_footnotes;
528 struct pivot_value *title;
529 struct pivot_value *subtype; /* Same as spv_item's subtype. */
530 struct pivot_value *corner_text;
531 struct pivot_value *caption;
532 char *notes; /* Shown as tooltip. */
535 struct pivot_dimension **dimensions;
538 /* Allocation of dimensions to rows, columns, and layers. */
539 struct pivot_axis axes[PIVOT_N_AXES];
541 struct hmap cells; /* Contains "struct pivot_cell"s. */
544 /* Creating and destroy pivot tables. */
545 struct pivot_table *pivot_table_create (const char *title);
546 struct pivot_table *pivot_table_create__ (struct pivot_value *title,
547 const char *subtype);
548 struct pivot_table *pivot_table_create_for_text (struct pivot_value *title,
549 struct pivot_value *content);
551 struct pivot_table *pivot_table_ref (const struct pivot_table *);
552 struct pivot_table *pivot_table_unshare (struct pivot_table *);
553 void pivot_table_unref (struct pivot_table *);
554 bool pivot_table_is_shared (const struct pivot_table *);
557 void pivot_table_set_title (struct pivot_table *, struct pivot_value *);
558 void pivot_table_set_subtype (struct pivot_table *, struct pivot_value *);
559 void pivot_table_set_corner_text (struct pivot_table *, struct pivot_value *);
560 void pivot_table_set_caption (struct pivot_table *, struct pivot_value *);
563 void pivot_table_swap_axes (struct pivot_table *,
564 enum pivot_axis_type, enum pivot_axis_type);
565 void pivot_table_transpose (struct pivot_table *);
566 void pivot_table_move_dimension (struct pivot_table *,
567 struct pivot_dimension *,
568 enum pivot_axis_type, size_t ofs);
571 const struct pivot_table_look *pivot_table_get_look (
572 const struct pivot_table *);
573 void pivot_table_set_look (struct pivot_table *,
574 const struct pivot_table_look *);
576 /* Format of PIVOT_RC_COUNT cells. */
577 void pivot_table_set_weight_var (struct pivot_table *,
578 const struct variable *);
579 void pivot_table_set_weight_format (struct pivot_table *,
580 const struct fmt_spec *);
583 bool pivot_table_is_empty (const struct pivot_table *);
586 void pivot_table_submit (struct pivot_table *);
589 void pivot_table_put (struct pivot_table *, const size_t *dindexes, size_t n,
590 struct pivot_value *);
591 void pivot_table_put1 (struct pivot_table *, size_t idx1,
592 struct pivot_value *);
593 void pivot_table_put2 (struct pivot_table *, size_t idx1, size_t idx2,
594 struct pivot_value *);
595 void pivot_table_put3 (struct pivot_table *, size_t idx1, size_t idx2,
596 size_t idx3, struct pivot_value *);
597 void pivot_table_put4 (struct pivot_table *, size_t idx1, size_t idx2,
598 size_t idx3, size_t idx4, struct pivot_value *);
600 const struct pivot_value *pivot_table_get (const struct pivot_table *,
601 const size_t *dindexes);
603 struct pivot_value *pivot_table_get_rw (struct pivot_table *,
604 const size_t *dindexes);
606 bool pivot_table_delete (struct pivot_table *, const size_t *dindexes);
610 Use pivot_table_create_footnote() to create a footnote.
611 Use pivot_value_add_footnote() to add a reference to a footnote. */
612 struct pivot_footnote
615 struct pivot_value *content;
616 struct pivot_value *marker;
620 struct pivot_footnote *pivot_table_create_footnote (
621 struct pivot_table *, struct pivot_value *content);
622 struct pivot_footnote *pivot_table_create_footnote__ (
623 struct pivot_table *, size_t idx,
624 struct pivot_value *marker, struct pivot_value *content);
626 void pivot_footnote_format_marker (const struct pivot_footnote *,
627 const struct pivot_table *,
629 char *pivot_footnote_marker_string (const struct pivot_footnote *,
630 const struct pivot_table *);
632 void pivot_footnote_destroy (struct pivot_footnote *);
635 void pivot_table_convert_indexes_ptod (const struct pivot_table *,
636 const size_t *pindexes[PIVOT_N_AXES],
638 size_t *pivot_table_enumerate_axis (const struct pivot_table *,
639 enum pivot_axis_type,
640 const size_t *layer_indexes,
641 bool omit_empty, size_t *n);
642 #define PIVOT_ENUMERATION_FOR_EACH(INDEXES, ENUMERATION, AXIS) \
643 for ((INDEXES) = (ENUMERATION); *(INDEXES) != SIZE_MAX; \
644 (INDEXES) += MAX (1, (AXIS)->n_dimensions))
646 void pivot_table_assign_label_depth (struct pivot_table *);
648 void pivot_table_dump (const struct pivot_table *, int indentation);
652 enum ATTRIBUTE ((packed)) pivot_value_type
654 PIVOT_VALUE_NUMERIC, /* A value of a numeric variable. */
655 PIVOT_VALUE_STRING, /* A value of a string variable. */
656 PIVOT_VALUE_VARIABLE, /* Name of a variable. */
657 PIVOT_VALUE_TEXT, /* Text. */
658 PIVOT_VALUE_TEMPLATE, /* Templated text. */
661 /* A pivot_value is the content of a single pivot table cell. A pivot_value is
662 also a pivot table's title, caption, footnote marker and contents, and so
665 A given pivot_value is one of:
667 1. A number resulting from a calculation (PIVOT_VALUE_NUMERIC). Use
668 pivot_value_new_number() to create such a pivot_value.
670 A numeric pivot_value has an associated display format (usually an F or
671 PCT format). This format can be set directly on the pivot_value, but
672 that is not usually the easiest way. Instead, it is usually true that
673 all of the values in a single category should have the same format
674 (e.g. all "Significance" values might use format F40.3), so PSPP makes
675 it easy to set the default format for a category while creating the
676 category. See pivot_dimension_create() for more details.
678 For numbers that should be displayed as integers,
679 pivot_value_new_integer() can occasionally be a useful special case.
681 2. A numeric or string value obtained from data (PIVOT_VALUE_NUMERIC or
682 PIVOT_VALUE_STRING). If such a value corresponds to a variable, then the
683 variable's name can be attached to the pivot_value. If the value has a
684 value label, then that can also be attached. When a label is present,
685 the user can control whether to show the value or the label or both.
687 Use pivot_value_new_var_value() to create pivot_values of these kinds.
689 3. A variable name (PIVOT_VALUE_VARIABLE). The variable label, if any, can
690 be attached too, and again the user can control whether to show the value
691 or the label or both.
693 4. A text string (PIVOT_VALUE_TEXT). The value stores the string in English
694 and translated into the output language (localized). Use
695 pivot_value_new_text() or pivot_value_new_text_format() for those cases.
696 In some cases, only an English or a localized version is available for
697 one reason or another, although this is regrettable; in those cases, use
698 pivot_value_new_user_text() or pivot_value_new_user_text_nocopy().
700 (There is also a PIVOT_VALUE_TEMPLATE but PSPP does not yet create these
707 A pivot_value may reference any number of footnotes. Use
708 pivot_value_add_footnote() to add a footnote reference. The footnotes being
709 referenced must first be created with pivot_table_create_footnote().
715 A pivot_value can have specific font and cell styles. Only the user should
720 struct pivot_value_ex *ex;
723 enum pivot_value_type type;
725 /* PIVOT_VALUE_NUMERIC. */
728 enum pivot_value_type type;
729 enum settings_value_show show; /* Show value or label or both? */
730 struct fmt_spec format; /* Format to display 'x'. */
731 bool honor_small; /* Honor value of pivot table 'small'? */
732 double x; /* The numeric value. */
733 char *var_name; /* May be NULL. */
734 char *value_label; /* May be NULL. */
738 /* PIVOT_VALUE_STRING. */
741 enum pivot_value_type type;
742 enum settings_value_show show; /* Show value or label or both? */
743 bool hex; /* Display in hex? */
744 char *s; /* The string value. */
745 char *var_name; /* May be NULL. */
746 char *value_label; /* May be NULL. */
750 /* PIVOT_VALUE_VARIABLE. */
753 enum pivot_value_type type;
754 enum settings_value_show show; /* Show name or label or both? */
756 char *var_label; /* May be NULL. */
760 /* PIVOT_VALUE_TEXT. */
763 enum pivot_value_type type;
765 /* 'local', 'c', and 'id' must all be nonnull, but they are allowed
766 to be the same pointer. */
768 char *local; /* Localized. */
769 char *c; /* English. */
770 char *id; /* Identifier. */
774 /* PIVOT_VALUE_TEMPLATE. */
777 enum pivot_value_type type;
781 The odd ordering in this struct reduces the overall size
782 of struct pivot_value. */
784 struct pivot_argument *args;
786 /* Both 'local' and 'id' must be nonnull, but they are allowed to
787 be the same pointer. */
788 char *local; /* Localized. */
789 char *id; /* Identifier. */
796 struct pivot_value *pivot_value_clone (const struct pivot_value *);
797 void pivot_value_destroy (struct pivot_value *);
799 /* Numbers resulting from calculations. */
800 struct pivot_value *pivot_value_new_number (double);
801 struct pivot_value *pivot_value_new_integer (double);
803 /* Values from data. */
804 struct pivot_value *pivot_value_new_var_value (
805 const struct variable *, const union value *);
806 struct pivot_value *pivot_value_new_value (const union value *, int width,
807 const struct fmt_spec *,
808 const char *encoding);
810 /* Values from variable names. */
811 struct pivot_value *pivot_value_new_variable (const struct variable *);
812 struct pivot_value *pivot_value_new_variable__ (const char *name,
815 /* Values from text strings. */
816 struct pivot_value *pivot_value_new_text (const char *);
817 struct pivot_value *pivot_value_new_text_format (const char *, ...)
818 #if defined(__GNUC__) && ((__GNUC__ == 4 && __GNUC_MINOR__>= 4) || __GNUC__ > 4)
819 __attribute__((format(gnu_printf, 1, 2)));
821 __attribute__((format(__printf__, 1, 2)));
824 struct pivot_value *pivot_value_new_user_text (const char *, size_t length);
825 struct pivot_value *pivot_value_new_user_text_nocopy (char *);
828 void pivot_value_add_footnote (struct pivot_value *, const struct pivot_footnote *);
829 void pivot_value_sort_footnotes (struct pivot_value *);
831 /* Numeric formats. */
832 void pivot_value_set_rc (const struct pivot_table *, struct pivot_value *,
835 /* Converting a pivot_value to a string for display. */
836 char *pivot_value_to_string (const struct pivot_value *,
837 const struct pivot_table *);
838 bool pivot_value_format (const struct pivot_value *,
839 const struct pivot_table *, struct string *);
840 bool pivot_value_format_body (const struct pivot_value *,
841 const struct pivot_table *,
845 void pivot_value_get_style (struct pivot_value *,
846 const struct font_style *base_font_style,
847 const struct cell_style *base_cell_style,
848 struct table_area_style *);
849 void pivot_value_set_style (struct pivot_value *,
850 const struct table_area_style *);
851 void pivot_value_set_font_style (struct pivot_value *,
852 const struct font_style *);
853 void pivot_value_set_cell_style (struct pivot_value *,
854 const struct cell_style *);
856 /* Template arguments. */
857 struct pivot_argument
860 struct pivot_value **values;
863 void pivot_argument_uninit (struct pivot_argument *);
864 void pivot_argument_copy (struct pivot_argument *,
865 const struct pivot_argument *);
867 /* Extra styling for a pivot_value.
869 This is logically part of pivot_value itself. It is broken into a separate
870 structure to save memory because it is rarely used. */
871 struct pivot_value_ex
873 struct font_style *font_style;
874 struct cell_style *cell_style;
879 size_t *footnote_indexes;
883 static inline const struct pivot_value_ex *
884 pivot_value_ex (const struct pivot_value *value)
886 static const struct pivot_value_ex empty_ex = { .font_style = NULL };
887 return value->ex ? value->ex : &empty_ex;
890 struct pivot_value_ex *pivot_value_ex_rw (struct pivot_value *);
891 struct pivot_value_ex *pivot_value_ex_clone (const struct pivot_value_ex *);
892 void pivot_value_ex_destroy (struct pivot_value_ex *);
894 /* One piece of data within a pivot table. */
897 struct hmap_node hmap_node; /* In struct pivot_table's 'cells' hmap. */
898 struct pivot_value *value;
899 unsigned int idx[]; /* One index per table dimension. */
902 #endif /* output/pivot-table.h */