6104cb13133b04a0de008c9a99756e84e7e90d4a
[pspp] / src / output / pivot-table.h
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 2017-2018 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_PIVOT_TABLE_H
18 #define OUTPUT_PIVOT_TABLE_H 1
19
20 #include <stdint.h>
21 #include <time.h>
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"
27
28 struct pivot_value;
29 struct variable;
30 union value;
31
32 /* Pivot tables.
33
34    Pivot tables are PSPP's primary form of output.  They are analogous to the
35    pivot tables you might be familiar with from spreadsheets and databases.
36    See https://en.wikipedia.org/wiki/Pivot_table for a brief introduction to
37    the overall concept of a pivot table.
38
39    In PSPP, the most important internal pieces of a pivot table are:
40
41    - Title.  Every pivot table has a title that is displayed above it.  It also
42      has an optional caption (displayed below it) and corner text (displayed in
43      the upper left corner).
44
45    - Dimensions.  A dimension consists of zero or more categories.  A category
46      has a label, such as "df" or "Asymp. Sig." or 123 or a variable name.  The
47      categories are the leaves of a tree whose non-leaf nodes form groups of
48      categories.  The tree always has a root group whose label is the name of
49      the dimension.
50
51    - Axes.  A table has three axes: column, row, and layer.  Each dimension is
52      assigned to an axis, and each axis has zero or more dimensions.  When an
53      axis has more than one dimension, they are ordered from innermost to
54      outermost.
55
56    - Data.  A table's data consists of zero or more cells.  Each cell maps from
57      a category for each dimension to a value, which is commonly a number but
58      could also be a variable name or an arbitrary text string.
59
60    Creating a pivot table usually consists of the following steps:
61
62    1. Create the table with pivot_table_create(), passing in the title.
63
64    2. Create each dimension with pivot_dimension_create() and populate it with
65       categories and, possibly, with groups that contain the categories.  This
66       call also assigns the dimension to an axis.
67
68       In simple cases, only a call to pivot_dimension_create() is needed.
69       Other functions such as pivot__create_group() can be used for
70       hierarchies of categories.
71
72       Sometimes it's easier to create categories in tandem with inserting data,
73       for example by adding a category for a variable just before inserting the
74       first cell for that variable.  In that case, creating categories and
75       inserting data can be interleaved.
76
77    3. Insert data.  For each cell, supply the category indexes, which are
78       assigned starting from 0 in the order in which the categories were
79       created in step 2, and the value to go in the cell.  If the table has a
80       small, fixed number of dimensions, functions like, e.g.
81       pivot_table_put3() for 3 dimensions, can be used.  The general function
82       pivot_table_put() works for other cases.
83
84    4. Output the table for user consumption.  Use pivot_table_submit(). */
85 \f
86 /* Pivot table display styling. */
87
88 /* Areas of a pivot table for styling purposes. */
89 enum pivot_area
90   {
91     PIVOT_AREA_TITLE,
92     PIVOT_AREA_CAPTION,
93     PIVOT_AREA_FOOTER,          /* Footnotes. */
94     PIVOT_AREA_CORNER,          /* Top-left corner. */
95     PIVOT_AREA_COLUMN_LABELS,
96     PIVOT_AREA_ROW_LABELS,
97     PIVOT_AREA_DATA,
98     PIVOT_AREA_LAYERS,          /* Layer indication. */
99     PIVOT_N_AREAS
100   };
101
102 const char *pivot_area_to_string (enum pivot_area);
103
104 /* Table borders for styling purposes. */
105 enum pivot_border
106   {
107     PIVOT_BORDER_TITLE,
108
109     /* Outer frame. */
110     PIVOT_BORDER_OUTER_LEFT,
111     PIVOT_BORDER_OUTER_TOP,
112     PIVOT_BORDER_OUTER_RIGHT,
113     PIVOT_BORDER_OUTER_BOTTOM,
114
115     /* Inner frame. */
116     PIVOT_BORDER_INNER_LEFT,
117     PIVOT_BORDER_INNER_TOP,
118     PIVOT_BORDER_INNER_RIGHT,
119     PIVOT_BORDER_INNER_BOTTOM,
120
121     /* Data area. */
122     PIVOT_BORDER_DATA_LEFT,
123     PIVOT_BORDER_DATA_TOP,
124
125     /* Dimensions. */
126     PIVOT_BORDER_DIM_ROW_HORZ,
127     PIVOT_BORDER_DIM_ROW_VERT,
128     PIVOT_BORDER_DIM_COL_HORZ,
129     PIVOT_BORDER_DIM_COL_VERT,
130
131     /* Categories. */
132     PIVOT_BORDER_CAT_ROW_HORZ,
133     PIVOT_BORDER_CAT_ROW_VERT,
134     PIVOT_BORDER_CAT_COL_HORZ,
135     PIVOT_BORDER_CAT_COL_VERT,
136
137     PIVOT_N_BORDERS
138   };
139
140 const char *pivot_border_to_string (enum pivot_border);
141
142 /* Sizing for rows or columns of a rendered table.  The comments below talk
143    about columns and their widths but they apply equally to rows and their
144    heights. */
145 struct pivot_table_sizing
146   {
147     /* Minimum and maximum column width, in 1/96" units. */
148     int range[2];
149
150     /* Specific column widths, in 1/96" units. */
151     int *widths;
152     size_t n_widths;
153
154     /* Specific page breaks: 0-based columns after which a page break must
155        occur, e.g. a value of 1 requests a break after the second column. */
156     size_t *breaks;
157     size_t n_breaks;
158
159     /* Keeps: columns to keep together on a page if possible. */
160     struct pivot_keep *keeps;
161     size_t n_keeps;
162   };
163
164 void pivot_table_sizing_uninit (struct pivot_table_sizing *);
165
166 /* A set of columns to keep together on a page if possible, e.g. ofs=1, n=10
167    requests keeping together the 2nd through 11th columns. */
168 struct pivot_keep
169   {
170     size_t ofs;                 /* 0-based first column. */
171     size_t n;                   /* Number of columns. */
172   };
173 \f
174 /* Axes. */
175
176 enum pivot_axis_type
177   {
178     PIVOT_AXIS_LAYER,
179     PIVOT_AXIS_ROW,
180     PIVOT_AXIS_COLUMN,
181
182     PIVOT_N_AXES
183   };
184
185 const char *pivot_axis_type_to_string (enum pivot_axis_type);
186
187 /* An axis within a pivot table. */
188 struct pivot_axis
189   {
190     /* dimensions[0] is the innermost dimension,
191        dimensions[1] is the next outer dimension,
192        ...
193        dimensions[n_dimensions - 1] is the outermost dimension. */
194     struct pivot_dimension **dimensions;
195     size_t n_dimensions;
196
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. */
200     size_t extent;
201
202     /* Sum of dimensions[*]->label_depth. */
203     size_t label_depth;
204   };
205
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.
209
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 *);
216 \f
217 /* Dimensions.
218
219    A pivot_dimension identifies the categories associated with a single
220    dimension within a multidimensional pivot table.
221
222    A dimension contains a collection of categories, which are the leaves in a
223    tree of groups.
224
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
227    data.)
228 */
229 struct pivot_dimension
230   {
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. */
235
236     /* table->dimensions[top_index] == dimension. */
237     size_t top_index;
238
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
242        adjusted it.
243
244        The root must always be a group, although it is allowed to have no
245        subcategories. */
246     struct pivot_category *root;
247
248     /* All of the leaves reachable via the root.
249
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.
254
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;
262
263     /* Display. */
264     bool hide_all_labels;
265
266     /* Number of rows or columns needed to express the labels. */
267     int label_depth;
268   };
269
270 struct pivot_dimension *pivot_dimension_create (
271   struct pivot_table *, enum pivot_axis_type, const char *name, ...)
272   SENTINEL (0);
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);
278
279 void pivot_dimension_destroy (struct pivot_dimension *);
280
281 void pivot_dimension_dump (const struct pivot_dimension *, int indentation);
282 \f
283 /* A pivot_category is a leaf (a category) or a group:
284
285    - For a leaf, neither index is SIZE_MAX.
286
287    - For a group, both indexes are SIZE_MAX.
288
289    Do not use 'subs' or 'n_subs' to determine whether a category is a group,
290    because a group may (pathologically) have no leaves. */
291 struct pivot_category
292   {
293     struct pivot_value *name;
294     struct pivot_category *parent;
295     struct pivot_dimension *dimension;
296     size_t label_depth, extra_depth;
297
298     /* Groups only.
299
300        If show_label is true, then the group itself has a row (or a column)
301        giving the group's name.  Otherwise, the group's own name is not
302        displayed. */
303     struct pivot_category **subs; /* Child categories or groups. */
304     size_t n_subs, allocated_subs;
305     bool show_label;            /* Display a label for the group itself? */
306     bool show_label_in_corner;
307
308     /* Leaf only. */
309     struct fmt_spec format;
310     size_t group_index;        /* In ->parent->subs[]. */
311     size_t data_index;         /* In ->dimension->data_leaves[]. */
312     size_t presentation_index; /* In ->dimension->presentation_leaves[]. */
313   };
314
315 static inline bool
316 pivot_category_is_group (const struct pivot_category *category)
317 {
318   return category->data_index == SIZE_MAX;
319 }
320
321 static inline bool
322 pivot_category_is_leaf (const struct pivot_category *category)
323 {
324   return !pivot_category_is_group (category);
325 }
326
327 /* Creating leaf categories. */
328 int pivot_category_create_leaves (struct pivot_category *parent, ...)
329   SENTINEL (0);
330 #define pivot_category_create_leaves(...) \
331   pivot_category_create_leaves(__VA_ARGS__, NULL_SENTINEL)
332
333 int pivot_category_create_leaf (
334   struct pivot_category *parent, struct pivot_value *name);
335 int pivot_category_create_leaf_rc (
336   struct pivot_category *parent, struct pivot_value *name, const char *rc);
337
338 /* Creating category groups. */
339 struct pivot_category *pivot_category_create_group (
340   struct pivot_category *parent, const char *name, ...) SENTINEL (0);
341 #define pivot_category_create_group(...) \
342   pivot_category_create_group(__VA_ARGS__, NULL_SENTINEL)
343 struct pivot_category *pivot_category_create_group__ (
344   struct pivot_category *parent, struct pivot_value *name);
345
346 void pivot_category_destroy (struct pivot_category *);
347
348 /* Pivot result classes.
349
350    These are used to mark leaf categories as having particular types of data,
351    to set their numeric formats.  The formats that actually get used for these
352    classes are in the result_classes[] global array in pivot-table.c, except
353    that PIVOT_RC_OTHER comes from settings_get_format() and PIVOT_RC_COUNT
354    should come from the weight variable in the dataset's dictionary. */
355 #define PIVOT_RC_OTHER ("RC_OTHER")
356 #define PIVOT_RC_INTEGER ("RC_INTEGER")
357 #define PIVOT_RC_CORRELATION ("RC_CORRELATIONS")
358 #define PIVOT_RC_SIGNIFICANCE ("RC_SIGNIFICANCE")
359 #define PIVOT_RC_PERCENT ("RC_PERCENT")
360 #define PIVOT_RC_RESIDUAL ("RC_RESIDUAL")
361 #define PIVOT_RC_COUNT ("RC_COUNT")
362
363 bool pivot_result_class_change (const char *, const struct fmt_spec *);
364 \f
365 /* A pivot table.  See the top of this file for more information. */
366 struct pivot_table
367   {
368     /* Display settings. */
369     bool rotate_inner_column_labels;
370     bool rotate_outer_row_labels;
371     bool row_labels_in_corner;
372     bool show_grid_lines;
373     bool omit_empty;
374     size_t *current_layer; /* axis[PIVOT_AXIS_LAYER]->n_dimensions elements. */
375     char *table_look;
376     enum settings_value_show show_values;
377     enum settings_value_show show_variables;
378     struct fmt_spec weight_format;
379
380     /* Footnote display settings. */
381     bool show_numeric_markers;
382     bool footnote_marker_superscripts;
383
384     /* Column and row sizing and page breaks.
385        sizing[TABLE_HORZ] is for columns, sizing[TABLE_VERT] is for rows. */
386     struct pivot_table_sizing sizing[TABLE_N_AXES];
387
388     /* Print settings. */
389     bool print_all_layers;
390     bool paginate_layers;
391     bool shrink_to_fit[TABLE_N_AXES];
392     bool top_continuation, bottom_continuation;
393     char *continuation;
394     size_t n_orphan_lines;
395
396     /* Format settings. */
397     int epoch;
398     char decimal;               /* Usually ',' or '.'. */
399     char grouping;              /* Usually '.' or ','. */
400     char *ccs[5];               /* Custom currency. */
401     double small;
402
403     /* Command information. */
404     char *command_local;        /* May be NULL. */
405     char *command_c;            /* May be NULL. */
406     char *language;             /* May be NULL. */
407     char *locale;               /* May be NULL. */
408
409     /* Source information. */
410     char *dataset;              /* May be NULL. */
411     char *datafile;             /* May be NULL. */
412     time_t date;                /* May be 0 if unknown. */
413
414     /* Footnotes. */
415     struct pivot_footnote **footnotes;
416     size_t n_footnotes, allocated_footnotes;
417
418     /* Titles. */
419     struct pivot_value *title;
420     struct pivot_value *subtype;  /* Same as pivot_item's subtype. */
421     struct pivot_value *corner_text;
422     struct pivot_value *caption;
423     char *notes;
424
425     /* Styles. */
426     struct area_style areas[PIVOT_N_AREAS];
427     struct table_border_style borders[PIVOT_N_BORDERS];
428
429     /* Dimensions. */
430     struct pivot_dimension **dimensions;
431     size_t n_dimensions;
432
433     /* Allocation of dimensions to rows, columns, and layers. */
434     struct pivot_axis axes[PIVOT_N_AXES];
435
436     struct hmap cells;          /* Contains "struct pivot_cell"s. */
437   };
438
439 /* Creating and destroy pivot tables. */
440 struct pivot_table *pivot_table_create (const char *title);
441 struct pivot_table *pivot_table_create__ (struct pivot_value *title);
442 struct pivot_table *pivot_table_create_for_text (struct pivot_value *title,
443                                                  struct pivot_value *content);
444 void pivot_table_destroy (struct pivot_table *);
445
446 /* Format of PIVOT_RC_COUNT cells. */
447 void pivot_table_set_weight_var (struct pivot_table *,
448                                  const struct variable *);
449 void pivot_table_set_weight_format (struct pivot_table *,
450                                     const struct fmt_spec *);
451
452 /* Query. */
453 bool pivot_table_is_empty (const struct pivot_table *);
454
455 /* Output. */
456 void pivot_table_submit (struct pivot_table *);
457
458 /* Data cells. */
459 void pivot_table_put (struct pivot_table *, const size_t *dindexes, size_t n,
460                       struct pivot_value *);
461 void pivot_table_put1 (struct pivot_table *, size_t idx1,
462                        struct pivot_value *);
463 void pivot_table_put2 (struct pivot_table *, size_t idx1, size_t idx2,
464                        struct pivot_value *);
465 void pivot_table_put3 (struct pivot_table *, size_t idx1, size_t idx2,
466                        size_t idx3, struct pivot_value *);
467 void pivot_table_put4 (struct pivot_table *, size_t idx1, size_t idx2,
468                        size_t idx3, size_t idx4, struct pivot_value *);
469
470 const struct pivot_value *pivot_table_get (const struct pivot_table *,
471                                            const size_t *dindexes);
472
473 struct pivot_value *pivot_table_get_rw (struct pivot_table *,
474                                         const size_t *dindexes);
475
476 /* Footnotes.
477
478    Use pivot_table_create_footnote() to create a footnote.
479    Use pivot_value_add_footnote() to add a reference to a footnote. */
480 struct pivot_footnote
481   {
482     size_t idx;
483     struct pivot_value *content;
484     struct pivot_value *marker;
485   };
486
487 struct pivot_footnote *pivot_table_create_footnote (
488   struct pivot_table *, struct pivot_value *content);
489 struct pivot_footnote *pivot_table_create_footnote__ (
490   struct pivot_table *, size_t idx,
491   struct pivot_value *marker, struct pivot_value *content);
492
493 void pivot_footnote_destroy (struct pivot_footnote *);
494
495 /* Internals. */
496 void pivot_table_convert_indexes_ptod (const struct pivot_table *,
497                                        const size_t *pindexes[PIVOT_N_AXES],
498                                        size_t *dindexes);
499 size_t *pivot_table_enumerate_axis (const struct pivot_table *,
500                                     enum pivot_axis_type,
501                                     const size_t *layer_indexes,
502                                     bool omit_empty, size_t *n);
503 #define PIVOT_ENUMERATION_FOR_EACH(INDEXES, ENUMERATION, AXIS)  \
504   for ((INDEXES) = (ENUMERATION); *(INDEXES) != SIZE_MAX;       \
505        (INDEXES) += MAX (1, (AXIS)->n_dimensions))
506
507 void pivot_table_assign_label_depth (struct pivot_table *);
508
509 void pivot_table_dump (const struct pivot_table *, int indentation);
510 \f
511 /* pivot_value. */
512
513 enum pivot_value_type
514   {
515     PIVOT_VALUE_NUMERIC,          /* A value of a numeric variable. */
516     PIVOT_VALUE_STRING,           /* A value of a string variable. */
517     PIVOT_VALUE_VARIABLE,         /* Name of a variable. */
518     PIVOT_VALUE_TEXT,             /* Text. */
519     PIVOT_VALUE_TEMPLATE,         /* Templated text. */
520   };
521
522 /* A pivot_value is the content of a single pivot table cell.  A pivot_value is
523    also a pivot table's title, caption, footnote marker and contents, and so
524    on.
525
526    A given pivot_value is one of:
527
528    1. A number resulting from a calculation (PIVOT_VALUE_NUMERIC).  Use
529       pivot_value_new_number() to create such a pivot_value.
530
531       A numeric pivot_value has an associated display format (usually an F or
532       PCT format).  This format can be set directly on the pivot_value, but
533       that is not usually the easiest way.  Instead, it is usually true that
534       all of the values in a single category should have the same format
535       (e.g. all "Significance" values might use format F40.3), so PSPP makes
536       it easy to set the default format for a category while creating the
537       category.  See pivot_dimension_create() for more details.
538
539       For numbers that should be displayed as integers,
540       pivot_value_new_integer() can occasionally be a useful special case.
541
542    2. A numeric or string value obtained from data (PIVOT_VALUE_NUMERIC or
543       PIVOT_VALUE_STRING).  If such a value corresponds to a variable, then the
544       variable's name can be attached to the pivot_value.  If the value has a
545       value label, then that can also be attached.  When a label is present,
546       the user can control whether to show the value or the label or both.
547
548       Use pivot_value_new_var_value() to create pivot_values of these kinds.
549
550    3. A variable name (PIVOT_VALUE_VARIABLE).  The variable label, if any, can
551       be attached too, and again the user can control whether to show the value
552       or the label or both.
553
554    4. A text string (PIVOT_VALUE_TEXT).  The value stores the string in English
555       and translated into the output language (localized).  Use
556       pivot_value_new_text() or pivot_value_new_text_format() for those cases.
557       In some cases, only an English or a localized version is available for
558       one reason or another, although this is regrettable; in those cases, use
559       pivot_value_new_user_text() or pivot_value_new_user_text_nocopy().
560
561    (There is also a PIVOT_VALUE_TEMPLATE but PSPP does not yet create these
562    itself.)
563
564
565    Footnotes
566    =========
567
568    A pivot_value may reference any number of footnotes.  Use
569    pivot_value_add_footnote() to add a footnote reference.  The footnotes being
570    referenced must first be created with pivot_table_create_footnote().
571
572
573    Styling
574    =======
575
576    A pivot_value can have specific font and cell styles.  Only the user should
577    add these.
578 */
579 struct pivot_value
580   {
581     struct font_style *font_style;
582     struct cell_style *cell_style;
583     char *subscript;
584     char *superscript;
585
586     struct pivot_footnote **footnotes;
587     size_t n_footnotes;
588
589     enum pivot_value_type type;
590     union
591       {
592         /* PIVOT_VALUE_NUMERIC. */
593         struct
594           {
595             double x;                 /* The numeric value. */
596             struct fmt_spec format;   /* Format to display 'x'. */
597             char *var_name;           /* May be NULL. */
598             char *value_label;        /* May be NULL. */
599             enum settings_value_show show; /* Show value or label or both? */
600           }
601         numeric;
602
603         /* PIVOT_VALUE_STRING. */
604         struct
605           {
606             char *s;                  /* The string value. */
607             bool hex;                 /* Display in hex? */
608             char *var_name;           /* May be NULL. */
609             char *value_label;        /* May be NULL. */
610             enum settings_value_show show; /* Show value or label or both? */
611           }
612         string;
613
614         /* PIVOT_VALUE_VARIABLE. */
615         struct
616           {
617             char *var_name;
618             char *var_label;          /* May be NULL. */
619             enum settings_value_show show; /* Show name or label or both? */
620           }
621         variable;
622
623         /* PIVOT_VALUE_TEXT. */
624         struct
625           {
626             char *local;              /* Localized. */
627             char *c;                  /* English. */
628             char *id;                 /* Identifier. */
629             bool user_provided;
630           }
631         text;
632
633         /* PIVOT_VALUE_TEMPLATE. */
634         struct
635           {
636             char *s;
637             struct pivot_argument *args;
638             size_t n_args;
639           }
640         template;
641       };
642   };
643
644 /* Numbers resulting from calculations. */
645 struct pivot_value *pivot_value_new_number (double);
646 struct pivot_value *pivot_value_new_integer (double);
647
648 /* Values from data. */
649 struct pivot_value *pivot_value_new_var_value (
650   const struct variable *, const union value *);
651 struct pivot_value *pivot_value_new_value (const union value *, int width,
652                                            const struct fmt_spec *,
653                                            const char *encoding);
654
655 /* Values from variable names. */
656 struct pivot_value *pivot_value_new_variable (const struct variable *);
657
658 /* Values from text strings. */
659 struct pivot_value *pivot_value_new_text (const char *);
660 struct pivot_value *pivot_value_new_text_format (const char *, ...)
661   PRINTF_FORMAT (1, 2);
662
663 struct pivot_value *pivot_value_new_user_text (const char *, size_t length);
664 struct pivot_value *pivot_value_new_user_text_nocopy (char *);
665
666 /* Footnotes. */
667 void pivot_value_add_footnote (struct pivot_value *, struct pivot_footnote *);
668
669 /* Numeric formats. */
670 void pivot_value_set_rc (struct pivot_table *, struct pivot_value *,
671                          const char *rc);
672
673 /* Converting a pivot_value to a string for display. */
674 char *pivot_value_to_string (const struct pivot_value *,
675                              enum settings_value_show show_values,
676                              enum settings_value_show show_variables);
677 void pivot_value_format (const struct pivot_value *,
678                          enum settings_value_show show_values,
679                          enum settings_value_show show_variables,
680                          struct string *);
681 bool pivot_value_format_body (const struct pivot_value *,
682                               enum settings_value_show show_values,
683                               enum settings_value_show show_variables,
684                               struct string *);
685
686 void pivot_value_destroy (struct pivot_value *);
687
688 /* Styling. */
689 void pivot_value_get_style (struct pivot_value *,
690                             const struct area_style *default_style,
691                             struct area_style *);
692 void pivot_value_set_style (struct pivot_value *, const struct area_style *);
693
694 /* Template arguments. */
695 struct pivot_argument
696   {
697     size_t n;
698     struct pivot_value **values;
699   };
700
701 void pivot_argument_uninit (struct pivot_argument *);
702
703 #endif /* output/pivot-table.h */