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"
35 Pivot tables are PSPP's primary form of output. They are analogous to the
36 pivot tables you might be familiar with from spreadsheets and databases.
37 See https://en.wikipedia.org/wiki/Pivot_table for a brief introduction to
38 the overall concept of a pivot table.
40 In PSPP, the most important internal pieces of a pivot table are:
42 - Title. Every pivot table has a title that is displayed above it. It also
43 has an optional caption (displayed below it) and corner text (displayed in
44 the upper left corner).
46 - Dimensions. A dimension consists of zero or more categories. A category
47 has a label, such as "df" or "Asymp. Sig." or 123 or a variable name. The
48 categories are the leaves of a tree whose non-leaf nodes form groups of
49 categories. The tree always has a root group whose label is the name of
52 - Axes. A table has three axes: column, row, and layer. Each dimension is
53 assigned to an axis, and each axis has zero or more dimensions. When an
54 axis has more than one dimension, they are ordered from innermost to
57 - Data. A table's data consists of zero or more cells. Each cell maps from
58 a category for each dimension to a value, which is commonly a number but
59 could also be a variable name or an arbitrary text string.
61 Creating a pivot table usually consists of the following steps:
63 1. Create the table with pivot_table_create(), passing in the title.
65 2. Optionally, set the format to use for "count" values with
66 pivot_table_set_weight_var() or pivot_table_set_weight_format().
68 3. Create each dimension with pivot_dimension_create() and populate it with
69 categories and, possibly, with groups that contain the categories. This
70 call also assigns the dimension to an axis.
72 In simple cases, only a call to pivot_dimension_create() is needed.
73 Other functions such as pivot_category_create_group() can be used for
74 hierarchies of categories.
76 Sometimes it's easier to create categories in tandem with inserting data,
77 for example by adding a category for a variable just before inserting the
78 first cell for that variable. In that case, creating categories and
79 inserting data can be interleaved.
81 4. Insert data. For each cell, supply the category indexes, which are
82 assigned starting from 0 in the order in which the categories were
83 created in step 2, and the value to go in the cell. If the table has a
84 small, fixed number of dimensions, functions like, e.g.
85 pivot_table_put3() for 3 dimensions, can be used. The general function
86 pivot_table_put() works for other cases.
88 5. Output the table for user consumption. Use pivot_table_submit(). */
90 /* Pivot table display styling. */
92 /* Areas of a pivot table for styling purposes. */
97 PIVOT_AREA_FOOTER, /* Footnotes. */
98 PIVOT_AREA_CORNER, /* Top-left corner. */
99 PIVOT_AREA_COLUMN_LABELS,
100 PIVOT_AREA_ROW_LABELS,
102 PIVOT_AREA_LAYERS, /* Layer indication. */
106 const char *pivot_area_to_string (enum pivot_area);
108 /* Table borders for styling purposes. */
114 PIVOT_BORDER_OUTER_LEFT,
115 PIVOT_BORDER_OUTER_TOP,
116 PIVOT_BORDER_OUTER_RIGHT,
117 PIVOT_BORDER_OUTER_BOTTOM,
120 PIVOT_BORDER_INNER_LEFT,
121 PIVOT_BORDER_INNER_TOP,
122 PIVOT_BORDER_INNER_RIGHT,
123 PIVOT_BORDER_INNER_BOTTOM,
126 PIVOT_BORDER_DATA_LEFT,
127 PIVOT_BORDER_DATA_TOP,
130 PIVOT_BORDER_DIM_ROW_HORZ,
131 PIVOT_BORDER_DIM_ROW_VERT,
132 PIVOT_BORDER_DIM_COL_HORZ,
133 PIVOT_BORDER_DIM_COL_VERT,
136 PIVOT_BORDER_CAT_ROW_HORZ,
137 PIVOT_BORDER_CAT_ROW_VERT,
138 PIVOT_BORDER_CAT_COL_HORZ,
139 PIVOT_BORDER_CAT_COL_VERT,
144 const char *pivot_border_to_string (enum pivot_border);
146 /* Sizing for rows or columns of a rendered table. The comments below talk
147 about columns and their widths but they apply equally to rows and their
149 struct pivot_table_sizing
151 /* Specific column widths, in 1/96" units. */
155 /* Specific page breaks: 0-based columns after which a page break must
156 occur, e.g. a value of 1 requests a break after the second column. */
160 /* Keeps: columns to keep together on a page if possible. */
161 struct pivot_keep *keeps;
165 void pivot_table_sizing_uninit (struct pivot_table_sizing *);
167 /* A set of columns to keep together on a page if possible, e.g. ofs=1, n=10
168 requests keeping together the 2nd through 11th columns. */
171 size_t ofs; /* 0-based first column. */
172 size_t n; /* Number of columns. */
182 #define PIVOT_N_AXES 3
185 const char *pivot_axis_type_to_string (enum pivot_axis_type);
187 /* An axis within a pivot table. */
190 /* dimensions[0] is the innermost dimension,
191 dimensions[1] is the next outer dimension,
193 dimensions[n_dimensions - 1] is the outermost dimension. */
194 struct pivot_dimension **dimensions;
197 /* The number of rows or columns along the axis,
198 that is, the product of dimension[*]->n_leaves.
199 It is 0 if any dimension has 0 leaves. */
202 /* Sum of dimensions[*]->label_depth. */
206 /* Successively assigns to INDEXES (which should be a "size_t *") each of the
207 combinations of the categories in AXIS's dimensions, in lexicographic order
208 with the innermost dimension iterating most quickly.
210 The value assigned to INDEXES is dynamically allocated. If the client
211 breaks out of the loop prematurely, it needs to free it with free(). */
212 #define PIVOT_AXIS_FOR_EACH(INDEXES, AXIS) \
213 for ((INDEXES) = NULL; \
214 ((INDEXES) = pivot_axis_iterator_next (INDEXES, AXIS)) != NULL;)
215 size_t *pivot_axis_iterator_next (size_t *indexes, const struct pivot_axis *);
219 A pivot_dimension identifies the categories associated with a single
220 dimension within a multidimensional pivot table.
222 A dimension contains a collection of categories, which are the leaves in a
225 (A dimension or a group can contain zero categories, but this is unusual.
226 If a dimension contains no categories, then its table cannot contain any
229 struct pivot_dimension
231 /* table->axes[axis_type]->dimensions[level] == dimension. */
232 struct pivot_table *table;
233 enum pivot_axis_type axis_type;
234 size_t level; /* 0 for innermost dimension within axis. */
236 /* table->dimensions[top_index] == dimension. */
239 /* Hierarchy of categories within the dimension. The groups and categories
240 are sorted in the order that should be used for display. This might be
241 different from the original order produced for output if the user
244 The root must always be a group, although it is allowed to have no
246 struct pivot_category *root;
248 /* All of the leaves reachable via the root.
250 The indexing for presentation_leaves is presentation order, thus
251 presentation_leaves[i]->presentation_index == i. This order is the same
252 as would be produced by an in-order traversal of the groups. It is the
253 order into which the user reordered or sorted the categories.
255 The indexing for data_leaves is that used for idx[] in struct
256 pivot_cell, thus data_leaves[i]->data_index == i. This might differ
257 from what an in-order traversal of 'root' would yield, if the user
258 reordered categories. */
259 struct pivot_category **data_leaves;
260 struct pivot_category **presentation_leaves;
261 size_t n_leaves, allocated_leaves;
264 bool hide_all_labels;
266 /* Number of rows or columns needed to express the labels. */
270 struct pivot_dimension *pivot_dimension_create (
271 struct pivot_table *, enum pivot_axis_type, const char *name, ...)
273 #define pivot_dimension_create(...) \
274 pivot_dimension_create(__VA_ARGS__, NULL_SENTINEL)
275 struct pivot_dimension *pivot_dimension_create__ (struct pivot_table *,
276 enum pivot_axis_type,
277 struct pivot_value *name);
279 void pivot_dimension_destroy (struct pivot_dimension *);
281 void pivot_dimension_dump (const struct pivot_dimension *,
282 const struct pivot_table *, int indentation);
284 struct pivot_splits *pivot_splits_create (struct pivot_table *,
285 const struct dictionary *);
286 void pivot_splits_destroy (struct pivot_splits *);
288 size_t pivot_splits_count (const struct pivot_splits *);
290 /* A pivot_category is a leaf (a category) or a group:
292 - For a leaf, neither index is SIZE_MAX.
294 - For a group, both indexes are SIZE_MAX.
296 Do not use 'subs' or 'n_subs' to determine whether a category is a group,
297 because a group may (pathologically) have no leaves. */
298 struct pivot_category
300 struct pivot_value *name;
301 struct pivot_category *parent;
302 struct pivot_dimension *dimension;
303 size_t label_depth, extra_depth;
307 If show_label is true, then the group itself has a row (or a column)
308 giving the group's name. Otherwise, the group's own name is not
310 struct pivot_category **subs; /* Child categories or groups. */
311 size_t n_subs, allocated_subs;
312 bool show_label; /* Display a label for the group itself? */
313 bool show_label_in_corner;
316 size_t group_index; /* In ->parent->subs[]. */
317 size_t data_index; /* In ->dimension->data_leaves[]. */
318 size_t presentation_index; /* In ->dimension->presentation_leaves[]. */
319 struct fmt_spec format; /* Default format for values in this category. */
320 bool honor_small; /* Honor pivot_table 'small' setting? */
324 pivot_category_is_group (const struct pivot_category *category)
326 return category->data_index == SIZE_MAX;
330 pivot_category_is_leaf (const struct pivot_category *category)
332 return !pivot_category_is_group (category);
335 /* Creating leaf categories. */
336 int pivot_category_create_leaves (struct pivot_category *parent, ...)
338 #define pivot_category_create_leaves(...) \
339 pivot_category_create_leaves(__VA_ARGS__, NULL_SENTINEL)
341 int pivot_category_create_leaf (
342 struct pivot_category *parent, struct pivot_value *name);
343 int pivot_category_create_leaf_rc (
344 struct pivot_category *parent, struct pivot_value *name, const char *rc);
346 /* Creating category groups. */
347 struct pivot_category *pivot_category_create_group (
348 struct pivot_category *parent, const char *name, ...) SENTINEL (0);
349 #define pivot_category_create_group(...) \
350 pivot_category_create_group(__VA_ARGS__, NULL_SENTINEL)
351 struct pivot_category *pivot_category_create_group__ (
352 struct pivot_category *parent, struct pivot_value *name);
354 void pivot_category_destroy (struct pivot_category *);
356 /* Pivot result classes.
358 These are used to mark leaf categories as having particular types of data,
359 to set their numeric formats. The formats that actually get used for these
360 classes are in the result_classes[] global array in pivot-table.c, except
361 that PIVOT_RC_OTHER comes from settings_get_format() and PIVOT_RC_COUNT
362 should come from the weight variable in the dataset's dictionary. */
363 #define PIVOT_RC_OTHER ("RC_OTHER")
364 #define PIVOT_RC_INTEGER ("RC_INTEGER")
365 #define PIVOT_RC_CORRELATION ("RC_CORRELATIONS")
366 #define PIVOT_RC_SIGNIFICANCE ("RC_SIGNIFICANCE")
367 #define PIVOT_RC_PERCENT ("RC_PERCENT")
368 #define PIVOT_RC_RESIDUAL ("RC_RESIDUAL")
369 #define PIVOT_RC_COUNT ("RC_COUNT")
371 bool pivot_result_class_change (const char *, const struct fmt_spec *);
372 bool is_pivot_result_class (const char *);
374 /* Styling for a pivot table.
376 The division between this and the style information in struct pivot_table
377 seems fairly arbitrary. The ultimate reason for the division is simply
378 because that's how SPSS documentation and file formats do it. */
379 struct pivot_table_look
381 /* Reference count. A pivot_table_look may be shared between multiple
382 owners, indicated by a reference count greater than 1. When this is the
383 case, the pivot_table must not be modified. */
386 char *name; /* May be null. */
388 /* General properties. */
390 bool row_labels_in_corner;
391 int width_ranges[TABLE_N_AXES][2]; /* In 1/96" units. */
393 /* Footnote display settings. */
394 bool show_numeric_markers;
395 bool footnote_marker_superscripts;
398 struct table_area_style areas[PIVOT_N_AREAS];
399 struct table_border_style borders[PIVOT_N_BORDERS];
401 /* Print settings. */
402 bool print_all_layers;
403 bool paginate_layers;
404 bool shrink_to_fit[TABLE_N_AXES];
405 bool top_continuation, bottom_continuation;
407 size_t n_orphan_lines;
410 const struct pivot_table_look *pivot_table_look_get_default (void);
411 void pivot_table_look_set_default (const struct pivot_table_look *);
413 char *pivot_table_look_read (const char *, struct pivot_table_look **)
416 const struct pivot_table_look *pivot_table_look_builtin_default (void);
417 struct pivot_table_look *pivot_table_look_new_builtin_default (void);
418 struct pivot_table_look *pivot_table_look_ref (
419 const struct pivot_table_look *);
420 void pivot_table_look_unref (struct pivot_table_look *);
421 struct pivot_table_look *pivot_table_look_unshare (struct pivot_table_look *);
423 /* A pivot table. See the top of this file for more information. */
426 /* Reference count. A pivot_table may be shared between multiple owners,
427 indicated by a reference count greater than 1. When this is the case,
428 the pivot_table must not be modified. */
432 struct pivot_table_look *look;
434 /* Display settings. */
435 bool rotate_inner_column_labels;
436 bool rotate_outer_row_labels;
437 bool show_grid_lines;
440 size_t *current_layer; /* axes[PIVOT_AXIS_LAYER].n_dimensions elements. */
441 enum settings_value_show show_values;
442 enum settings_value_show show_variables;
443 struct fmt_spec weight_format;
445 /* Column and row sizing and page breaks.
446 sizing[TABLE_HORZ] is for columns, sizing[TABLE_VERT] is for rows. */
447 struct pivot_table_sizing sizing[TABLE_N_AXES];
449 /* Format settings. */
450 struct fmt_settings settings;
451 char grouping; /* Usually '.' or ','. */
454 /* Command information. */
455 char *command_local; /* May be NULL. */
456 char *command_c; /* May be NULL. */
457 char *language; /* May be NULL. */
458 char *locale; /* May be NULL. */
460 /* Source information. */
461 char *dataset; /* May be NULL. */
462 char *datafile; /* May be NULL. */
463 time_t date; /* May be 0 if unknown. */
466 struct pivot_footnote **footnotes;
467 size_t n_footnotes, allocated_footnotes;
470 struct pivot_value *title;
471 struct pivot_value *subtype; /* Same as spv_item's subtype. */
472 struct pivot_value *corner_text;
473 struct pivot_value *caption;
474 char *notes; /* Shown as tooltip. */
477 struct pivot_dimension **dimensions;
480 /* Allocation of dimensions to rows, columns, and layers. */
481 struct pivot_axis axes[PIVOT_N_AXES];
483 struct hmap cells; /* Contains "struct pivot_cell"s. */
486 /* Creating and destroy pivot tables. */
487 struct pivot_table *pivot_table_create (const char *title);
488 struct pivot_table *pivot_table_create__ (struct pivot_value *title,
489 const char *subtype);
490 struct pivot_table *pivot_table_create_for_text (struct pivot_value *title,
491 struct pivot_value *content);
493 struct pivot_table *pivot_table_ref (const struct pivot_table *);
494 struct pivot_table *pivot_table_unshare (struct pivot_table *);
495 void pivot_table_unref (struct pivot_table *);
496 bool pivot_table_is_shared (const struct pivot_table *);
499 void pivot_table_set_title (struct pivot_table *, struct pivot_value *);
500 void pivot_table_set_subtype (struct pivot_table *, struct pivot_value *);
501 void pivot_table_set_corner_text (struct pivot_table *, struct pivot_value *);
502 void pivot_table_set_caption (struct pivot_table *, struct pivot_value *);
505 void pivot_table_swap_axes (struct pivot_table *,
506 enum pivot_axis_type, enum pivot_axis_type);
507 void pivot_table_transpose (struct pivot_table *);
508 void pivot_table_move_dimension (struct pivot_table *,
509 struct pivot_dimension *,
510 enum pivot_axis_type, size_t ofs);
513 const struct pivot_table_look *pivot_table_get_look (
514 const struct pivot_table *);
515 void pivot_table_set_look (struct pivot_table *,
516 const struct pivot_table_look *);
518 /* Format of PIVOT_RC_COUNT cells. */
519 void pivot_table_set_weight_var (struct pivot_table *,
520 const struct variable *);
521 void pivot_table_set_weight_format (struct pivot_table *,
522 const struct fmt_spec *);
525 bool pivot_table_is_empty (const struct pivot_table *);
528 void pivot_table_submit (struct pivot_table *);
531 void pivot_table_put (struct pivot_table *, const size_t *dindexes, size_t n,
532 struct pivot_value *);
533 void pivot_table_put1 (struct pivot_table *, size_t idx1,
534 struct pivot_value *);
535 void pivot_table_put2 (struct pivot_table *, size_t idx1, size_t idx2,
536 struct pivot_value *);
537 void pivot_table_put3 (struct pivot_table *, size_t idx1, size_t idx2,
538 size_t idx3, struct pivot_value *);
539 void pivot_table_put4 (struct pivot_table *, size_t idx1, size_t idx2,
540 size_t idx3, size_t idx4, struct pivot_value *);
542 const struct pivot_value *pivot_table_get (const struct pivot_table *,
543 const size_t *dindexes);
545 struct pivot_value *pivot_table_get_rw (struct pivot_table *,
546 const size_t *dindexes);
548 bool pivot_table_delete (struct pivot_table *, const size_t *dindexes);
552 Use pivot_table_create_footnote() to create a footnote.
553 Use pivot_value_add_footnote() to add a reference to a footnote. */
554 struct pivot_footnote
557 struct pivot_value *content;
558 struct pivot_value *marker;
562 struct pivot_footnote *pivot_table_create_footnote (
563 struct pivot_table *, struct pivot_value *content);
564 struct pivot_footnote *pivot_table_create_footnote__ (
565 struct pivot_table *, size_t idx,
566 struct pivot_value *marker, struct pivot_value *content);
568 void pivot_footnote_format_marker (const struct pivot_footnote *,
569 const struct pivot_table *,
571 char *pivot_footnote_marker_string (const struct pivot_footnote *,
572 const struct pivot_table *);
574 void pivot_footnote_destroy (struct pivot_footnote *);
577 void pivot_table_convert_indexes_ptod (const struct pivot_table *,
578 const size_t *pindexes[PIVOT_N_AXES],
580 size_t *pivot_table_enumerate_axis (const struct pivot_table *,
581 enum pivot_axis_type,
582 const size_t *layer_indexes,
583 bool omit_empty, size_t *n);
584 #define PIVOT_ENUMERATION_FOR_EACH(INDEXES, ENUMERATION, AXIS) \
585 for ((INDEXES) = (ENUMERATION); *(INDEXES) != SIZE_MAX; \
586 (INDEXES) += MAX (1, (AXIS)->n_dimensions))
588 void pivot_table_assign_label_depth (struct pivot_table *);
590 void pivot_table_dump (const struct pivot_table *, int indentation);
594 enum ATTRIBUTE ((packed)) pivot_value_type
596 PIVOT_VALUE_NUMERIC, /* A value of a numeric variable. */
597 PIVOT_VALUE_STRING, /* A value of a string variable. */
598 PIVOT_VALUE_VARIABLE, /* Name of a variable. */
599 PIVOT_VALUE_TEXT, /* Text. */
600 PIVOT_VALUE_TEMPLATE, /* Templated text. */
603 /* A pivot_value is the content of a single pivot table cell. A pivot_value is
604 also a pivot table's title, caption, footnote marker and contents, and so
607 A given pivot_value is one of:
609 1. A number resulting from a calculation (PIVOT_VALUE_NUMERIC). Use
610 pivot_value_new_number() to create such a pivot_value.
612 A numeric pivot_value has an associated display format (usually an F or
613 PCT format). This format can be set directly on the pivot_value, but
614 that is not usually the easiest way. Instead, it is usually true that
615 all of the values in a single category should have the same format
616 (e.g. all "Significance" values might use format F40.3), so PSPP makes
617 it easy to set the default format for a category while creating the
618 category. See pivot_dimension_create() for more details.
620 For numbers that should be displayed as integers,
621 pivot_value_new_integer() can occasionally be a useful special case.
623 2. A numeric or string value obtained from data (PIVOT_VALUE_NUMERIC or
624 PIVOT_VALUE_STRING). If such a value corresponds to a variable, then the
625 variable's name can be attached to the pivot_value. If the value has a
626 value label, then that can also be attached. When a label is present,
627 the user can control whether to show the value or the label or both.
629 Use pivot_value_new_var_value() to create pivot_values of these kinds.
631 3. A variable name (PIVOT_VALUE_VARIABLE). The variable label, if any, can
632 be attached too, and again the user can control whether to show the value
633 or the label or both.
635 4. A text string (PIVOT_VALUE_TEXT). The value stores the string in English
636 and translated into the output language (localized). Use
637 pivot_value_new_text() or pivot_value_new_text_format() for those cases.
638 In some cases, only an English or a localized version is available for
639 one reason or another, although this is regrettable; in those cases, use
640 pivot_value_new_user_text() or pivot_value_new_user_text_nocopy().
642 (There is also a PIVOT_VALUE_TEMPLATE but PSPP does not yet create these
649 A pivot_value may reference any number of footnotes. Use
650 pivot_value_add_footnote() to add a footnote reference. The footnotes being
651 referenced must first be created with pivot_table_create_footnote().
657 A pivot_value can have specific font and cell styles. Only the user should
662 struct pivot_value_ex *ex;
665 enum pivot_value_type type;
667 /* PIVOT_VALUE_NUMERIC. */
670 enum pivot_value_type type;
671 enum settings_value_show show; /* Show value or label or both? */
672 struct fmt_spec format; /* Format to display 'x'. */
673 bool honor_small; /* Honor value of pivot table 'small'? */
674 double x; /* The numeric value. */
675 char *var_name; /* May be NULL. */
676 char *value_label; /* May be NULL. */
680 /* PIVOT_VALUE_STRING. */
683 enum pivot_value_type type;
684 enum settings_value_show show; /* Show value or label or both? */
685 bool hex; /* Display in hex? */
686 char *s; /* The string value. */
687 char *var_name; /* May be NULL. */
688 char *value_label; /* May be NULL. */
692 /* PIVOT_VALUE_VARIABLE. */
695 enum pivot_value_type type;
696 enum settings_value_show show; /* Show name or label or both? */
698 char *var_label; /* May be NULL. */
702 /* PIVOT_VALUE_TEXT. */
705 enum pivot_value_type type;
707 /* 'local', 'c', and 'id' must all be nonnull, but they are allowed
708 to be the same pointer. */
710 char *local; /* Localized. */
711 char *c; /* English. */
712 char *id; /* Identifier. */
716 /* PIVOT_VALUE_TEMPLATE. */
719 enum pivot_value_type type;
723 The odd ordering in this struct reduces the overall size
724 of struct pivot_value. */
726 struct pivot_argument *args;
728 /* Both 'local' and 'id' must be nonnull, but they are allowed to
729 be the same pointer. */
730 char *local; /* Localized. */
731 char *id; /* Identifier. */
738 struct pivot_value *pivot_value_clone (const struct pivot_value *);
739 void pivot_value_destroy (struct pivot_value *);
741 /* Numbers resulting from calculations. */
742 struct pivot_value *pivot_value_new_number (double);
743 struct pivot_value *pivot_value_new_integer (double);
745 /* Values from data. */
746 struct pivot_value *pivot_value_new_var_value (
747 const struct variable *, const union value *);
748 struct pivot_value *pivot_value_new_value (const union value *, int width,
749 const struct fmt_spec *,
750 const char *encoding);
752 /* Values from variable names. */
753 struct pivot_value *pivot_value_new_variable (const struct variable *);
754 struct pivot_value *pivot_value_new_variable__ (const char *name,
757 /* Values from text strings. */
758 struct pivot_value *pivot_value_new_text (const char *);
759 struct pivot_value *pivot_value_new_text_format (const char *, ...)
760 #if defined(__GNUC__) && ((__GNUC__ == 4 && __GNUC_MINOR__>= 4) || __GNUC__ > 4)
761 __attribute__((format(gnu_printf, 1, 2)));
763 __attribute__((format(__printf__, 1, 2)));
766 struct pivot_value *pivot_value_new_user_text (const char *, size_t length);
767 struct pivot_value *pivot_value_new_user_text_nocopy (char *);
770 void pivot_value_add_footnote (struct pivot_value *, const struct pivot_footnote *);
771 void pivot_value_sort_footnotes (struct pivot_value *);
773 /* Numeric formats. */
774 void pivot_value_set_rc (const struct pivot_table *, struct pivot_value *,
777 /* Converting a pivot_value to a string for display. */
778 char *pivot_value_to_string (const struct pivot_value *,
779 const struct pivot_table *);
780 char *pivot_value_to_string_defaults (const struct pivot_value *);
781 bool pivot_value_format (const struct pivot_value *,
782 const struct pivot_table *, struct string *);
783 bool pivot_value_format_body (const struct pivot_value *,
784 const struct pivot_table *,
788 void pivot_value_get_style (struct pivot_value *,
789 const struct font_style *base_font_style,
790 const struct cell_style *base_cell_style,
791 struct table_area_style *);
792 void pivot_value_set_style (struct pivot_value *,
793 const struct table_area_style *);
794 void pivot_value_set_font_style (struct pivot_value *,
795 const struct font_style *);
796 void pivot_value_set_cell_style (struct pivot_value *,
797 const struct cell_style *);
799 /* Template arguments. */
800 struct pivot_argument
803 struct pivot_value **values;
806 void pivot_argument_uninit (struct pivot_argument *);
807 void pivot_argument_copy (struct pivot_argument *,
808 const struct pivot_argument *);
810 /* Extra styling for a pivot_value.
812 This is logically part of pivot_value itself. It is broken into a separate
813 structure to save memory because it is rarely used. */
814 struct pivot_value_ex
816 struct font_style *font_style;
817 struct cell_style *cell_style;
822 size_t *footnote_indexes;
826 static inline const struct pivot_value_ex *
827 pivot_value_ex (const struct pivot_value *value)
829 static const struct pivot_value_ex empty_ex = { .font_style = NULL };
830 return value->ex ? value->ex : &empty_ex;
833 struct pivot_value_ex *pivot_value_ex_rw (struct pivot_value *);
834 struct pivot_value_ex *pivot_value_ex_clone (const struct pivot_value_ex *);
835 void pivot_value_ex_destroy (struct pivot_value_ex *);
837 /* One piece of data within a pivot table. */
840 struct hmap_node hmap_node; /* In struct pivot_table's 'cells' hmap. */
841 struct pivot_value *value;
842 unsigned int idx[]; /* One index per table dimension. */
845 #endif /* output/pivot-table.h */