tests: Avoid nonportable "mktemp" usage.
[pspp] / doc / dev / concepts.texi
1 @node Basic Concepts
2 @chapter Basic Concepts
3
4 This chapter introduces basic data structures and other concepts
5 needed for developing in PSPP.
6
7 @menu
8 * Values::
9 * Input and Output Formats::
10 * User-Missing Values::
11 * Value Labels::
12 * Variables::
13 * Dictionaries::
14 * Coding Conventions::
15 * Cases::
16 * Data Sets::
17 * Pools::
18 @end menu
19
20 @node Values
21 @section Values
22
23 @cindex value
24 The unit of data in PSPP is a @dfn{value}.
25
26 @cindex width
27 @cindex string value
28 @cindex numeric value
29 @cindex MAX_STRING
30 Values are classified by @dfn{type} and @dfn{width}.  The
31 type of a value is either @dfn{numeric} or @dfn{string} (sometimes
32 called alphanumeric).  The width of a string value ranges from 1 to
33 @code{MAX_STRING} bytes.  The width of a numeric value is artificially
34 defined to be 0; thus, the type of a value can be inferred from its
35 width.
36
37 Some support is provided for working with value types and widths, in
38 @file{data/val-type.h}:
39
40 @deftypefn Macro int MAX_STRING
41 Maximum width of a string value, in bytes, currently 32,767.
42 @end deftypefn
43
44 @deftypefun bool val_type_is_valid (enum val_type @var{val_type})
45 Returns true if @var{val_type} is a valid value type, that is,
46 either @code{VAL_NUMERIC} or @code{VAL_STRING}.  Useful for
47 assertions.
48 @end deftypefun
49
50 @deftypefun {enum val_type} val_type_from_width (int @var{width})
51 Returns @code{VAL_NUMERIC} if @var{width} is 0 and thus represents the
52 width of a numeric value, otherwise @code{VAL_STRING} to indicate that
53 @var{width} is the width of a string value.
54 @end deftypefun
55
56 The following subsections describe how values of each type are
57 represented.
58
59 @menu
60 * Numeric Values::
61 * String Values::
62 * Runtime Typed Values::
63 @end menu
64
65 @node Numeric Values
66 @subsection Numeric Values
67
68 A value known to be numeric at compile time is represented as a
69 @code{double}.  PSPP provides three values of @code{double} for
70 special purposes, defined in @file{data/val-type.h}:
71
72 @deftypefn Macro double SYSMIS
73 The @dfn{system-missing value}, used to represent a datum whose true
74 value is unknown, such as a survey question that was not answered by
75 the respondent, or undefined, such as the result of division by zero.
76 PSPP propagates the system-missing value through calculations and
77 compensates for missing values in statistical analyses.  @xref{Missing
78 Observations,,,pspp, PSPP Users Guide}, for a PSPP user's view of
79 missing values.
80
81 PSPP currently defines @code{SYSMIS} as @code{-DBL_MAX}, that is, the
82 greatest finite negative value of @code{double}.  It is best not to
83 depend on this definition, because PSPP may transition to using an
84 IEEE NaN (not a number) instead at some point in the future.
85 @end deftypefn
86
87 @deftypefn Macro double LOWEST
88 @deftypefnx Macro double HIGHEST
89 The greatest finite negative (except for @code{SYSMIS}) and positive
90 values of @code{double}, respectively.  These values do not ordinarily
91 appear in user data files.  Instead, they are used to implement
92 endpoints of open-ended ranges that are occasionally permitted in PSPP
93 syntax, e.g.@: @code{5 THRU HI} as a range of missing values
94 (@pxref{MISSING VALUES,,,pspp, PSPP Users Guide}).
95 @end deftypefn
96
97 @node String Values
98 @subsection String Values
99
100 A value known at compile time to have string type is represented as an
101 array of @code{char}.  String values do not necessarily represent
102 readable text strings and may contain arbitrary 8-bit data, including
103 null bytes, control codes, and bytes with the high bit set.  Thus,
104 string values are not null-terminated strings, but rather opaque
105 arrays of bytes.
106
107 @code{SYSMIS}, @code{LOWEST}, and @code{HIGHEST} have no equivalents
108 as string values.  Usually, PSPP fills an unknown or undefined string
109 values with spaces, but PSPP does not treat such a string as a special
110 case when it processes it later.
111
112 @cindex MAX_STRING
113 @code{MAX_STRING}, the maximum length of a string value, is defined in
114 @file{data/val-type.h}.
115
116 @node Runtime Typed Values
117 @subsection Runtime Typed Values
118
119 When a value's type is only known at runtime, it is often represented
120 as a @union{value}, defined in @file{data/value.h}.  A @union{value}
121 does not identify the type or width of the data it contains.  Code
122 that works with @union{values}s must therefore have external knowledge
123 of its content, often through the type and width of a
124 @struct{variable} (@pxref{Variables}).
125
126 @union{value} has one member that clients are permitted to access
127 directly, a @code{double} named @samp{f} that stores the content of a
128 numeric @union{value}.  It has other members that store the content of
129 string @union{value}, but client code should use accessor functions
130 instead of referring to these directly.
131
132 PSPP provides some functions for working with @union{value}s.  The
133 most useful are described below.  To use these functions, recall that
134 a numeric value has a width of 0.
135
136 @deftypefun void value_init (union value *@var{value}, int @var{width})
137 Initializes @var{value} as a value of the given @var{width}.  After
138 initialization, the data in @var{value} are indeterminate; the caller
139 is responsible for storing initial data in it.
140 @end deftypefun
141
142 @deftypefun void value_destroy (union value *@var{value}, int @var{width})
143 Frees auxiliary storage associated with @var{value}, which must have
144 the given @var{width}.
145 @end deftypefun
146
147 @deftypefun bool value_needs_init (int @var{width})
148 For some widths, @func{value_init} and @func{value_destroy} do not
149 actually do anything, because no additional storage is needed beyond
150 the size of @union{value}.  This function returns true if @var{width}
151 is such a width, which case there is no actual need to call those
152 functions.  This can be a useful optimization if a large number of
153 @union{value}s of such a width are to be initialized or destroyed.
154
155 This function returns false if @func{value_init} and
156 @func{value_destroy} are actually required for the given @var{width}.
157 @end deftypefun
158
159 @deftypefun double value_num (const union value *@var{value})
160 Returns the numeric value in @var{value}, which must have been
161 initialized as a numeric value.  Equivalent to @code{@var{value}->f}.
162 @end deftypefun
163
164 @deftypefun {const char *} value_str (const union value *@var{value}, int @var{width})
165 @deftypefunx {char *} value_str_rw (union value *@var{value}, int @var{width})
166 Returns the string value in @var{value}, which must have been
167 initialized with positive width @var{width}.  The string returned is
168 not null-terminated.  Only @var{width} bytes of returned data may be
169 accessed.
170
171 The two different functions exist only for @code{const}-correctness.
172 Otherwise they are identical.
173
174 It is important that @var{width} be the correct value that was passed
175 to @func{value_init}.  Passing a smaller or larger value (e.g.@:
176 because that number of bytes will be accessed) will not always work
177 and should be avoided.
178 @end deftypefun
179
180 @deftypefun void value_copy (union value *@var{dst}, @
181                              const union value *@var{src}, @
182                              int @var{width})
183 Copies the contents of @union{value} @var{src} to @var{dst}.  Both
184 @var{dst} and @var{src} must have been initialized with the specified
185 @var{width}.
186 @end deftypefun
187
188 @deftypefun void value_set_missing (union value *@var{value}, int @var{width})
189 Sets @var{value} to @code{SYSMIS} if it is numeric or to all spaces if
190 it is alphanumeric, according to @var{width}.  @var{value} must have
191 been initialized with the specified @var{width}.
192 @end deftypefun
193
194 @anchor{value_is_resizable}
195 @deftypefun bool value_is_resizable (const union value *@var{value}, int @var{old_width}, int @var{new_width})
196 Determines whether @var{value}, which must have been initialized with
197 the specified @var{old_width}, may be resized to @var{new_width}.
198 Resizing is possible if the following criteria are met.  First,
199 @var{old_width} and @var{new_width} must be both numeric or both
200 string widths.  Second, if @var{new_width} is a short string width and
201 less than @var{old_width}, resizing is allowed only if bytes
202 @var{new_width} through @var{old_width} in @var{value} contain only
203 spaces.
204
205 These rules are part of those used by @func{mv_is_resizable} and
206 @func{val_labs_can_set_width}.
207 @end deftypefun
208
209 @deftypefun void value_resize (union value *@var{value}, int @var{old_width}, int @var{new_width})
210 Resizes @var{value} from @var{old_width} to @var{new_width}, which
211 must be allowed by the rules stated above.  @var{value} must have been
212 initialized with the specified @var{old_width} before calling this
213 function.  After resizing, @var{value} has width @var{new_width}.
214
215 If @var{new_width} is greater than @var{old_width}, @var{value} will
216 be padded on the right with spaces to the new width.  If
217 @var{new_width} is less than @var{old_width}, the rightmost bytes of
218 @var{value} are truncated.
219 @end deftypefun
220
221 @deftypefun bool value_equal (const union value *@var{a}, const union value *@var{b}, int @var{width})
222 Compares of @var{a} and @var{b}, which must both have width
223 @var{width}.  Returns true if their contents are the same, false if
224 they differ.
225 @end deftypefun
226
227 @deftypefun int value_compare_3way (const union value *@var{a}, const union value *@var{b}, int @var{width})
228 Compares of @var{a} and @var{b}, which must both have width
229 @var{width}.  Returns -1 if @var{a} is less than @var{b}, 0 if they
230 are equal, or 1 if @var{a} is greater than @var{b}.
231
232 Numeric values are compared numerically, with @code{SYSMIS} comparing
233 less than any real number.  String values are compared
234 lexicographically byte-by-byte.
235 @end deftypefun
236
237 @deftypefun size_t value_hash (const union value *@var{value}, int @var{width}, unsigned int @var{basis})
238 Computes and returns a hash of @var{value}, which must have the
239 specified @var{width}.  The value in @var{basis} is folded into the
240 hash.
241 @end deftypefun
242
243 @node Input and Output Formats
244 @section Input and Output Formats
245
246 Input and output formats specify how to convert data fields to and
247 from data values (@pxref{Input and Output Formats,,,pspp, PSPP Users
248 Guide}).  PSPP uses @struct{fmt_spec} to represent input and output
249 formats.
250
251 Function prototypes and other declarations related to formats are in
252 the @file{<data/format.h>} header.
253
254 @deftp {Structure} {struct fmt_spec}
255 An input or output format, with the following members:
256
257 @table @code
258 @item enum fmt_type type
259 The format type (see below).
260
261 @item int w
262 Field width, in bytes.  The width of numeric fields is always between
263 1 and 40 bytes, and the width of string fields is always between 1 and
264 65534 bytes.  However, many individual types of formats place stricter
265 limits on field width (see @ref{fmt_max_input_width},
266 @ref{fmt_max_output_width}).
267
268 @item int d
269 Number of decimal places, in character positions.  For format types
270 that do not allow decimal places to be specified, this value must be
271 0.  Format types that do allow decimal places have type-specific and
272 often width-specific restrictions on @code{d} (see
273 @ref{fmt_max_input_decimals}, @ref{fmt_max_output_decimals}).
274 @end table
275 @end deftp
276
277 @deftp {Enumeration} {enum fmt_type}
278 An enumerated type representing an input or output format type.  Each
279 PSPP input and output format has a corresponding enumeration constant
280 prefixed by @samp{FMT}: @code{FMT_F}, @code{FMT_COMMA},
281 @code{FMT_DOT}, and so on.
282 @end deftp
283
284 The following sections describe functions for manipulating formats and
285 the data in fields represented by formats.
286
287 @menu
288 * Constructing and Verifying Formats::
289 * Format Utility Functions::
290 * Obtaining Properties of Format Types::
291 * Numeric Formatting Styles::
292 * Formatted Data Input and Output::
293 @end menu
294
295 @node Constructing and Verifying Formats
296 @subsection Constructing and Verifying Formats
297
298 These functions construct @struct{fmt_spec}s and verify that they are
299 valid.
300
301
302
303 @deftypefun {struct fmt_spec} fmt_for_input (enum fmt_type @var{type}, int @var{w}, int @var{d})
304 @deftypefunx {struct fmt_spec} fmt_for_output (enum fmt_type @var{type}, int @var{w}, int @var{d})
305 Constructs a @struct{fmt_spec} with the given @var{type}, @var{w}, and
306 @var{d}, asserts that the result is a valid input (or output) format,
307 and returns it.
308 @end deftypefun
309
310 @anchor{fmt_for_output_from_input}
311 @deftypefun {struct fmt_spec} fmt_for_output_from_input (const struct fmt_spec *@var{input})
312 Given @var{input}, which must be a valid input format, returns the
313 equivalent output format.  @xref{Input and Output Formats,,,pspp, PSPP
314 Users Guide}, for the rules for converting input formats into output
315 formats.
316 @end deftypefun
317
318 @deftypefun {struct fmt_spec} fmt_default_for_width (int @var{width})
319 Returns the default output format for a variable of the given
320 @var{width}.  For a numeric variable, this is F8.2 format; for a
321 string variable, it is the A format of the given @var{width}.
322 @end deftypefun
323
324 The following functions check whether a @struct{fmt_spec} is valid for
325 various uses and return true if so, false otherwise.  When any of them
326 returns false, it also outputs an explanatory error message using
327 @func{msg}.  To suppress error output, enclose a call to one of these
328 functions by a @func{msg_disable}/@func{msg_enable} pair.
329
330 @deftypefun bool fmt_check (const struct fmt_spec *@var{format}, bool @var{for_input})
331 @deftypefunx bool fmt_check_input (const struct fmt_spec *@var{format})
332 @deftypefunx bool fmt_check_output (const struct fmt_spec *@var{format})
333 Checks whether @var{format} is a valid input format (for
334 @func{fmt_check_input}, or @func{fmt_check} if @var{for_input}) or
335 output format (for @func{fmt_check_output}, or @func{fmt_check} if not
336 @var{for_input}).
337 @end deftypefun
338
339 @deftypefun bool fmt_check_type_compat (const struct fmt_spec *@var{format}, enum val_type @var{type})
340 Checks whether @var{format} matches the value type @var{type}, that
341 is, if @var{type} is @code{VAL_NUMERIC} and @var{format} is a numeric
342 format or @var{type} is @code{VAL_STRING} and @var{format} is a string
343 format.
344 @end deftypefun
345
346 @deftypefun bool fmt_check_width_compat (const struct fmt_spec *@var{format}, int @var{width})
347 Checks whether @var{format} may be used as an output format for a
348 value of the given @var{width}.
349
350 @func{fmt_var_width}, described in
351 the following section, can be also be used to determine the value
352 width needed by a format.
353 @end deftypefun
354
355 @node Format Utility Functions
356 @subsection Format Utility Functions
357
358 These functions work with @struct{fmt_spec}s.
359
360 @deftypefun int fmt_var_width (const struct fmt_spec *@var{format})
361 Returns the width for values associated with @var{format}.  If
362 @var{format} is a numeric format, the width is 0; if @var{format} is
363 an A format, then the width @code{@var{format}->w}; otherwise,
364 @var{format} is an AHEX format and its width is @code{@var{format}->w
365 / 2}.
366 @end deftypefun
367
368 @deftypefun char *fmt_to_string (const struct fmt_spec *@var{format}, char @var{s}[FMT_STRING_LEN_MAX + 1])
369 Converts @var{format} to a human-readable format specifier in @var{s}
370 and returns @var{s}.  @var{format} need not be a valid input or output
371 format specifier, e.g.@: it is allowed to have an excess width or
372 decimal places.  In particular, if @var{format} has decimals, they are
373 included in the output string, even if @var{format}'s type does not
374 allow decimals, to allow accurately presenting incorrect formats to
375 the user.
376 @end deftypefun
377
378 @deftypefun bool fmt_equal (const struct fmt_spec *@var{a}, const struct fmt_spec *@var{b})
379 Compares @var{a} and @var{b} memberwise and returns true if they are
380 identical, false otherwise.  @var{format} need not be a valid input or
381 output format specifier.
382 @end deftypefun
383
384 @deftypefun void fmt_resize (struct fmt_spec *@var{fmt}, int @var{width})
385 Sets the width of @var{fmt} to a valid format for a  @union{value} of size @var{width}.
386 @end deftypefun
387
388 @node Obtaining Properties of Format Types
389 @subsection Obtaining Properties of Format Types
390
391 These functions work with @enum{fmt_type}s instead of the higher-level
392 @struct{fmt_spec}s.  Their primary purpose is to report properties of
393 each possible format type, which in turn allows clients to abstract
394 away many of the details of the very heterogeneous requirements of
395 each format type.
396
397 The first group of functions works with format type names.
398
399 @deftypefun const char *fmt_name (enum fmt_type @var{type})
400 Returns the name for the given @var{type}, e.g.@: @code{"COMMA"} for
401 @code{FMT_COMMA}.
402 @end deftypefun
403
404 @deftypefun bool fmt_from_name (const char *@var{name}, enum fmt_type *@var{type})
405 Tries to find the @enum{fmt_type} associated with @var{name}.  If
406 successful, sets @code{*@var{type}} to the type and returns true;
407 otherwise, returns false without modifying @code{*@var{type}}.
408 @end deftypefun
409
410 The functions below query basic limits on width and decimal places for
411 each kind of format.
412
413 @deftypefun bool fmt_takes_decimals (enum fmt_type @var{type})
414 Returns true if a format of the given @var{type} is allowed to have a
415 nonzero number of decimal places (the @code{d} member of
416 @struct{fmt_spec}), false if not.
417 @end deftypefun
418
419 @anchor{fmt_min_input_width}
420 @anchor{fmt_max_input_width}
421 @anchor{fmt_min_output_width}
422 @anchor{fmt_max_output_width}
423 @deftypefun int fmt_min_input_width (enum fmt_type @var{type})
424 @deftypefunx int fmt_max_input_width (enum fmt_type @var{type})
425 @deftypefunx int fmt_min_output_width (enum fmt_type @var{type})
426 @deftypefunx int fmt_max_output_width (enum fmt_type @var{type})
427 Returns the minimum or maximum width (the @code{w} member of
428 @struct{fmt_spec}) allowed for an input or output format of the
429 specified @var{type}.
430 @end deftypefun
431
432 @anchor{fmt_max_input_decimals}
433 @anchor{fmt_max_output_decimals}
434 @deftypefun int fmt_max_input_decimals (enum fmt_type @var{type}, int @var{width})
435 @deftypefunx int fmt_max_output_decimals (enum fmt_type @var{type}, int @var{width})
436 Returns the maximum number of decimal places allowed for an input or
437 output format, respectively, of the given @var{type} and @var{width}.
438 Returns 0 if the specified @var{type} does not allow any decimal
439 places or if @var{width} is too narrow to allow decimal places.
440 @end deftypefun
441
442 @deftypefun int fmt_step_width (enum fmt_type @var{type})
443 Returns the ``width step'' for a @struct{fmt_spec} of the given
444 @var{type}.  A @struct{fmt_spec}'s width must be a multiple of its
445 type's width step.  Most format types have a width step of 1, so that
446 their formats' widths may be any integer within the valid range, but
447 hexadecimal numeric formats and AHEX string formats have a width step
448 of 2.
449 @end deftypefun
450
451 These functions allow clients to broadly determine how each kind of
452 input or output format behaves.
453
454 @deftypefun bool fmt_is_string (enum fmt_type @var{type})
455 @deftypefunx bool fmt_is_numeric (enum fmt_type @var{type})
456 Returns true if @var{type} is a format for numeric or string values,
457 respectively, false otherwise.
458 @end deftypefun
459
460 @deftypefun enum fmt_category fmt_get_category (enum fmt_type @var{type})
461 Returns the category within which @var{type} falls.
462
463 @deftp {Enumeration} {enum fmt_category}
464 A group of format types.  Format type categories correspond to the
465 input and output categories described in the PSPP user documentation
466 (@pxref{Input and Output Formats,,,pspp, PSPP Users Guide}).
467
468 Each format is in exactly one category.  The categories have bitwise
469 disjoint values to make it easy to test whether a format type is in
470 one of multiple categories, e.g.@:
471
472 @example
473 if (fmt_get_category (type) & (FMT_CAT_DATE | FMT_CAT_TIME))
474   @{
475     /* @dots{}@r{@code{type} is a date or time format}@dots{} */
476   @}
477 @end example
478
479 The format categories are:
480 @table @code
481 @item FMT_CAT_BASIC
482 Basic numeric formats.
483
484 @item FMT_CAT_CUSTOM
485 Custom currency formats.
486
487 @item FMT_CAT_LEGACY
488 Legacy numeric formats.
489
490 @item FMT_CAT_BINARY
491 Binary formats.
492
493 @item FMT_CAT_HEXADECIMAL
494 Hexadecimal formats.
495
496 @item FMT_CAT_DATE
497 Date formats.
498
499 @item FMT_CAT_TIME
500 Time formats.
501
502 @item FMT_CAT_DATE_COMPONENT
503 Date component formats.
504
505 @item FMT_CAT_STRING
506 String formats.
507 @end table
508 @end deftp
509 @end deftypefun
510
511 The PSPP input and output routines use the following pair of functions
512 to convert @enum{fmt_type}s to and from the separate set of codes used
513 in system and portable files:
514
515 @deftypefun int fmt_to_io (enum fmt_type @var{type})
516 Returns the format code used in system and portable files that
517 corresponds to @var{type}.
518 @end deftypefun
519
520 @deftypefun bool fmt_from_io (int @var{io}, enum fmt_type *@var{type})
521 Converts @var{io}, a format code used in system and portable files,
522 into a @enum{fmt_type} in @code{*@var{type}}.  Returns true if
523 successful, false if @var{io} is not valid.
524 @end deftypefun
525
526 These functions reflect the relationship between input and output
527 formats.
528
529 @deftypefun enum fmt_type fmt_input_to_output (enum fmt_type @var{type})
530 Returns the output format type that is used by default by DATA LIST
531 and other input procedures when @var{type} is specified as an input
532 format.  The conversion from input format to output format is more
533 complicated than simply changing the format.
534 @xref{fmt_for_output_from_input}, for a function that performs the
535 entire conversion.
536 @end deftypefun
537
538 @deftypefun bool fmt_usable_for_input (enum fmt_type @var{type})
539 Returns true if @var{type} may be used as an input format type, false
540 otherwise.  The custom currency formats, in particular, may be used
541 for output but not for input.
542
543 All format types are valid for output.
544 @end deftypefun
545
546 The final group of format type property functions obtain
547 human-readable templates that illustrate the formats graphically.
548
549 @deftypefun const char *fmt_date_template (enum fmt_type @var{type})
550 Returns a formatting template for @var{type}, which must be a date or
551 time format type.  These formats are used by @func{data_in} and
552 @func{data_out} to guide parsing and formatting date and time data.
553 @end deftypefun
554
555 @deftypefun char *fmt_dollar_template (const struct fmt_spec *@var{format})
556 Returns a string of the form @code{$#,###.##} according to
557 @var{format}, which must be of type @code{FMT_DOLLAR}.  The caller
558 must free the string with @code{free}.
559 @end deftypefun
560
561 @node Numeric Formatting Styles
562 @subsection Numeric Formatting Styles
563
564 Each of the basic numeric formats (F, E, COMMA, DOT, DOLLAR, PCT) and
565 custom currency formats (CCA, CCB, CCC, CCD, CCE) has an associated
566 numeric formatting style, represented by @struct{fmt_number_style}.
567 Input and output conversion of formats that have numeric styles is
568 determined mainly by the style, although the formatting rules have
569 special cases that are not represented within the style.
570
571 @deftp {Structure} {struct fmt_number_style}
572 A structure type with the following members:
573
574 @table @code
575 @item struct substring neg_prefix
576 @itemx struct substring prefix
577 @itemx struct substring suffix
578 @itemx struct substring neg_suffix
579 A set of strings used a prefix to negative numbers, a prefix to every
580 number, a suffix to every number, and a suffix to negative numbers,
581 respectively.  Each of these strings is no more than
582 @code{FMT_STYLE_AFFIX_MAX} bytes (currently 16) bytes in length.
583 These strings must be freed with @func{ss_dealloc} when no longer
584 needed.
585
586 @item decimal
587 The character used as a decimal point.  It must be either @samp{.} or
588 @samp{,}.
589
590 @item grouping
591 The character used for grouping digits to the left of the decimal
592 point.  It may be @samp{.} or @samp{,}, in which case it must not be
593 equal to @code{decimal}, or it may be set to 0 to disable grouping.
594 @end table
595 @end deftp
596
597 The following functions are provided for working with numeric
598 formatting styles.
599
600 @deftypefun void fmt_number_style_init (struct fmt_number_style *@var{style})
601 Initialises a @struct{fmt_number_style} with all of the
602 prefixes and suffixes set to the empty string, @samp{.} as the decimal
603 point character, and grouping disables.
604 @end deftypefun
605
606
607 @deftypefun void fmt_number_style_destroy (struct fmt_number_style *@var{style})
608 Destroys @var{style}, freeing its storage.
609 @end deftypefun
610
611 @deftypefun {struct fmt_number_style}    *fmt_create (void)
612 A function which creates an array of all the styles used by pspp, and 
613 calls fmt_number_style_init on each of them.
614 @end deftypefun
615
616 @deftypefun void fmt_done (struct fmt_number_style *@var{styles})
617 A wrapper function which takes an array of @struct{fmt_number_style}, calls
618 fmt_number_style_destroy on each of them, and then frees the array.
619 @end deftypefun
620
621
622
623 @deftypefun int fmt_affix_width (const struct fmt_number_style *@var{style})
624 Returns the total length of @var{style}'s @code{prefix} and @code{suffix}.
625 @end deftypefun
626
627 @deftypefun int fmt_neg_affix_width (const struct fmt_number_style *@var{style})
628 Returns the total length of @var{style}'s @code{neg_prefix} and
629 @code{neg_suffix}.
630 @end deftypefun
631
632 PSPP maintains a global set of number styles for each of the basic
633 numeric formats and custom currency formats.  The following functions
634 work with these global styles:
635
636 @deftypefun {const struct fmt_number_style *} fmt_get_style (enum fmt_type @var{type})
637 Returns the numeric style for the given format @var{type}.
638 @end deftypefun
639
640 @deftypefun {const char *} fmt_name (enum fmt_type @var{type})
641 Returns the name of the given format @var{type}.
642 @end deftypefun
643
644
645
646 @node Formatted Data Input and Output
647 @subsection Formatted Data Input and Output
648
649 These functions provide the ability to convert data fields into
650 @union{value}s and vice versa.
651
652 @deftypefun bool data_in (struct substring @var{input}, const char *@var{encoding}, enum fmt_type @var{type}, int @var{implied_decimals}, int @var{first_column}, const struct dictionary *@var{dict}, union value *@var{output}, int @var{width})
653 Parses @var{input} as a field containing data in the given format
654 @var{type}.  The resulting value is stored in @var{output}, which the
655 caller must have initialized with the given @var{width}.  For
656 consistency, @var{width} must be 0 if
657 @var{type} is a numeric format type and greater than 0 if @var{type}
658 is a string format type.
659 @var{encoding} should be set to indicate the character
660 encoding of @var{input}.
661 @var{dict} must be a pointer to the dictionary with which @var{output}
662 is associated.
663
664 If @var{input} is the empty string (with length 0), @var{output} is
665 set to the value set on SET BLANKS (@pxref{SET BLANKS,,,pspp, PSPP
666 Users Guide}) for a numeric value, or to all spaces for a string
667 value.  This applies regardless of the usual parsing requirements for
668 @var{type}.
669
670 If @var{implied_decimals} is greater than zero, then the numeric
671 result is shifted right by @var{implied_decimals} decimal places if
672 @var{input} does not contain a decimal point character or an exponent.
673 Only certain numeric format types support implied decimal places; for
674 string formats and other numeric formats, @var{implied_decimals} has
675 no effect.  DATA LIST FIXED is the primary user of this feature
676 (@pxref{DATA LIST FIXED,,,pspp, PSPP Users Guide}).  Other callers
677 should generally specify 0 for @var{implied_decimals}, to disable this
678 feature.
679
680 When @var{input} contains invalid input data, @func{data_in} outputs a
681 message using @func{msg}.
682 @c (@pxref{msg}).
683 If @var{first_column} is
684 nonzero, it is included in any such error message as the 1-based
685 column number of the start of the field.  The last column in the field
686 is calculated as @math{@var{first_column} + @var{input} - 1}.  To
687 suppress error output, enclose the call to @func{data_in} by calls to
688 @func{msg_disable} and @func{msg_enable}.
689
690 This function returns true on success, false if a message was output
691 (even if suppressed).  Overflow and underflow provoke warnings but are
692 not propagated to the caller as errors.
693
694 This function is declared in @file{data/data-in.h}.
695 @end deftypefun
696
697 @deftypefun char * data_out (const union value *@var{input}, const struct fmt_spec *@var{format})
698 @deftypefunx char * data_out_legacy (const union value *@var{input}, const char *@var{encoding}, const struct fmt_spec *@var{format})
699 Converts the data pointed to by @var{input} into a string value, which
700 will be encoded in UTF-8,  according to output format specifier @var{format}.
701 Format 
702 must be a valid output format.   The width of @var{input} is
703 inferred from @var{format} using an algorithm equivalent to
704 @func{fmt_var_width}.
705
706 When @var{input} contains data that cannot be represented in the given
707 @var{format}, @func{data_out} may output a message using @func{msg},
708 @c (@pxref{msg}),
709 although the current implementation does not
710 consistently do so.  To suppress error output, enclose the call to
711 @func{data_out} by calls to @func{msg_disable} and @func{msg_enable}.
712
713 This function is declared in @file{data/data-out.h}.
714 @end deftypefun
715
716 @node User-Missing Values
717 @section User-Missing Values
718
719 In addition to the system-missing value for numeric values, each
720 variable has a set of user-missing values (@pxref{MISSING
721 VALUES,,,pspp, PSPP Users Guide}).  A set of user-missing values is
722 represented by @struct{missing_values}.
723
724 It is rarely necessary to interact directly with a
725 @struct{missing_values} object.  Instead, the most common operation,
726 querying whether a particular value is a missing value for a given
727 variable, is most conveniently executed through functions on
728 @struct{variable}.  @xref{Variable Missing Values}, for details.
729
730 A @struct{missing_values} is essentially a set of @union{value}s that
731 have a common value width (@pxref{Values}).  For a set of
732 missing values associated with a variable (the common case), the set's
733 width is the same as the variable's width.
734
735 Function prototypes and other declarations related to missing values
736 are declared in @file{data/missing-values.h}.
737
738 @deftp {Structure} {struct missing_values}
739 Opaque type that represents a set of missing values.
740 @end deftp
741
742 The contents of a set of missing values is subject to some
743 restrictions.  Regardless of width, a set of missing values is allowed
744 to be empty.  A set of numeric missing values may contain up to three
745 discrete numeric values, or a range of numeric values (which includes
746 both ends of the range), or a range plus one discrete numeric value.
747 A set of string missing values may contain up to three discrete string
748 values (with the same width as the set), but ranges are not supported.
749
750 In addition, values in string missing values wider than
751 @code{MV_MAX_STRING} bytes may contain non-space characters only in
752 their first @code{MV_MAX_STRING} bytes; all the bytes after the first
753 @code{MV_MAX_STRING} must be spaces.  @xref{mv_is_acceptable}, for a
754 function that tests a value against these constraints.
755
756 @deftypefn Macro int MV_MAX_STRING
757 Number of bytes in a string missing value that are not required to be
758 spaces.  The current value is 8, a value which is fixed by the system
759 file format.  In PSPP we could easily eliminate this restriction, but
760 doing so would also require us to extend the system file format in an
761 incompatible way, which we consider a bad tradeoff.
762 @end deftypefn
763
764 The most often useful functions for missing values are those for
765 testing whether a given value is missing, described in the following
766 section.  Several other functions for creating, inspecting, and
767 modifying @struct{missing_values} objects are described afterward, but
768 these functions are much more rarely useful.
769
770 @menu
771 * Testing for Missing Values::
772 * Creating and Destroying User-Missing Values::
773 * Changing User-Missing Value Set Width::
774 * Inspecting User-Missing Value Sets::
775 * Modifying User-Missing Value Sets::
776 @end menu
777
778 @node Testing for Missing Values
779 @subsection Testing for Missing Values
780
781 The most often useful functions for missing values are those for
782 testing whether a given value is missing, described here.  However,
783 using one of the corresponding missing value testing functions for
784 variables can be even easier (@pxref{Variable Missing Values}).
785
786 @deftypefun bool mv_is_value_missing (const struct missing_values *@var{mv}, const union value *@var{value}, enum mv_class @var{class})
787 @deftypefunx bool mv_is_num_missing (const struct missing_values *@var{mv}, double @var{value}, enum mv_class @var{class})
788 @deftypefunx bool mv_is_str_missing (const struct missing_values *@var{mv}, const char @var{value}[], enum mv_class @var{class})
789 Tests whether @var{value} is in one of the categories of missing
790 values given by @var{class}.  Returns true if so, false otherwise.
791
792 @var{mv} determines the width of @var{value} and provides the set of
793 user-missing values to test.
794
795 The only difference among these functions in the form in which
796 @var{value} is provided, so you may use whichever function is most
797 convenient.
798
799 The @var{class} argument determines the exact kinds of missing values
800 that the functions test for:
801
802 @deftp Enumeration {enum mv_class}
803 @table @t
804 @item MV_USER
805 Returns true if @var{value} is in the set of user-missing values given
806 by @var{mv}.
807
808 @item MV_SYSTEM
809 Returns true if @var{value} is system-missing.  (If @var{mv}
810 represents a set of string values, then @var{value} is never
811 system-missing.)
812
813 @item MV_ANY
814 @itemx MV_USER | MV_SYSTEM
815 Returns true if @var{value} is user-missing or system-missing.
816
817 @item MV_NONE
818 Always returns false, that is, @var{value} is never considered
819 missing.
820 @end table
821 @end deftp
822 @end deftypefun
823
824 @node Creating and Destroying User-Missing Values
825 @subsection Creation and Destruction
826
827 These functions create and destroy @struct{missing_values} objects.
828
829 @deftypefun void mv_init (struct missing_values *@var{mv}, int @var{width})
830 Initializes @var{mv} as a set of user-missing values.  The set is
831 initially empty.  Any values added to it must have the specified
832 @var{width}.
833 @end deftypefun
834
835 @deftypefun void mv_destroy (struct missing_values *@var{mv})
836 Destroys @var{mv}, which must not be referred to again.
837 @end deftypefun
838
839 @deftypefun void mv_copy (struct missing_values *@var{mv}, const struct missing_values *@var{old})
840 Initializes @var{mv} as a copy of the existing set of user-missing
841 values @var{old}.
842 @end deftypefun
843
844 @deftypefun void mv_clear (struct missing_values *@var{mv})
845 Empties the user-missing value set @var{mv}, retaining its existing
846 width.
847 @end deftypefun
848
849 @node Changing User-Missing Value Set Width
850 @subsection Changing User-Missing Value Set Width
851
852 A few PSPP language constructs copy sets of user-missing values from
853 one variable to another.  When the source and target variables have
854 the same width, this is simple.  But when the target variable's width
855 might be different from the source variable's, it takes a little more
856 work.  The functions described here can help.
857
858 In fact, it is usually unnecessary to call these functions directly.
859 Most of the time @func{var_set_missing_values}, which uses
860 @func{mv_resize} internally to resize the new set of missing values to
861 the required width, may be used instead.
862 @xref{var_set_missing_values}, for more information.
863
864 @deftypefun bool mv_is_resizable (const struct missing_values *@var{mv}, int @var{new_width})
865 Tests whether @var{mv}'s width may be changed to @var{new_width} using
866 @func{mv_resize}.  Returns true if it is allowed, false otherwise.
867
868 If @var{mv} contains any missing values, then it may be resized only
869 if each missing value may be resized, as determined by
870 @func{value_is_resizable} (@pxref{value_is_resizable}).
871 @end deftypefun
872
873 @anchor{mv_resize}
874 @deftypefun void mv_resize (struct missing_values *@var{mv}, int @var{width})
875 Changes @var{mv}'s width to @var{width}.  @var{mv} and @var{width}
876 must satisfy the constraints explained above.
877
878 When a string missing value set's width is increased, each
879 user-missing value is padded on the right with spaces to the new
880 width.
881 @end deftypefun
882
883 @node Inspecting User-Missing Value Sets
884 @subsection Inspecting User-Missing Value Sets
885
886 These functions inspect the properties and contents of
887 @struct{missing_values} objects.
888
889 The first set of functions inspects the discrete values that sets of
890 user-missing values may contain:
891
892 @deftypefun bool mv_is_empty (const struct missing_values *@var{mv})
893 Returns true if @var{mv} contains no user-missing values, false if it
894 contains at least one user-missing value (either a discrete value or a
895 numeric range).
896 @end deftypefun
897
898 @deftypefun int mv_get_width (const struct missing_values *@var{mv})
899 Returns the width of the user-missing values that @var{mv} represents.
900 @end deftypefun
901
902 @deftypefun int mv_n_values (const struct missing_values *@var{mv})
903 Returns the number of discrete user-missing values included in
904 @var{mv}.  The return value will be between 0 and 3.  For sets of
905 numeric user-missing values that include a range, the return value
906 will be 0 or 1.
907 @end deftypefun
908
909 @deftypefun bool mv_has_value (const struct missing_values *@var{mv})
910 Returns true if @var{mv} has at least one discrete user-missing
911 values, that is, if @func{mv_n_values} would return nonzero for
912 @var{mv}.
913 @end deftypefun
914
915 @deftypefun {const union value *} mv_get_value (const struct missing_values *@var{mv}, int @var{index})
916 Returns the discrete user-missing value in @var{mv} with the given
917 @var{index}.  The caller must not modify or free the returned value or
918 refer to it after modifying or freeing @var{mv}.  The index must be
919 less than the number of discrete user-missing values in @var{mv}, as
920 reported by @func{mv_n_values}.
921 @end deftypefun
922
923 The second set of functions inspects the single range of values that
924 numeric sets of user-missing values may contain:
925
926 @deftypefun bool mv_has_range (const struct missing_values *@var{mv})
927 Returns true if @var{mv} includes a range, false otherwise.
928 @end deftypefun
929
930 @deftypefun void mv_get_range (const struct missing_values *@var{mv}, double *@var{low}, double *@var{high})
931 Stores the low endpoint of @var{mv}'s range in @code{*@var{low}} and
932 the high endpoint of the range in @code{*@var{high}}.  @var{mv} must
933 include a range.
934 @end deftypefun
935
936 @node Modifying User-Missing Value Sets
937 @subsection Modifying User-Missing Value Sets
938
939 These functions modify the contents of @struct{missing_values}
940 objects.
941
942 The next set of functions applies to all sets of user-missing values:
943
944 @deftypefun bool mv_add_value (struct missing_values *@var{mv}, const union value *@var{value})
945 @deftypefunx bool mv_add_str (struct missing_values *@var{mv}, const char @var{value}[])
946 @deftypefunx bool mv_add_num (struct missing_values *@var{mv}, double @var{value})
947 Attempts to add the given discrete @var{value} to set of user-missing
948 values @var{mv}.  @var{value} must have the same width as @var{mv}.
949 Returns true if @var{value} was successfully added, false if the set
950 could not accept any more discrete values or if @var{value} is not an
951 acceptable user-missing value (see @func{mv_is_acceptable} below).
952
953 These functions are equivalent, except for the form in which
954 @var{value} is provided, so you may use whichever function is most
955 convenient.
956 @end deftypefun
957
958 @deftypefun void mv_pop_value (struct missing_values *@var{mv}, union value *@var{value})
959 Removes a discrete value from @var{mv} (which must contain at least
960 one discrete value) and stores it in @var{value}.
961 @end deftypefun
962
963 @deftypefun bool mv_replace_value (struct missing_values *@var{mv}, const union value *@var{value}, int @var{index})
964 Attempts to replace the discrete value with the given @var{index} in
965 @var{mv} (which must contain at least @var{index} + 1 discrete values)
966 by @var{value}.  Returns true if successful, false if @var{value} is
967 not an acceptable user-missing value (see @func{mv_is_acceptable}
968 below).
969 @end deftypefun
970
971 @deftypefun bool mv_is_acceptable (const union value *@var{value}, int @var{width})
972 @anchor{mv_is_acceptable}
973 Returns true if @var{value}, which must have the specified
974 @var{width}, may be added to a missing value set of the same
975 @var{width}, false if it cannot.  As described above, all numeric
976 values and string values of width @code{MV_MAX_STRING} or less may be
977 added, but string value of greater width may be added only if bytes
978 beyond the first @code{MV_MAX_STRING} are all spaces.
979 @end deftypefun
980
981 The second set of functions applies only to numeric sets of
982 user-missing values:
983
984 @deftypefun bool mv_add_range (struct missing_values *@var{mv}, double @var{low}, double @var{high})
985 Attempts to add a numeric range covering @var{low}@dots{}@var{high}
986 (inclusive on both ends) to @var{mv}, which must be a numeric set of
987 user-missing values.  Returns true if the range is successful added,
988 false on failure.  Fails if @var{mv} already contains a range, or if
989 @var{mv} contains more than one discrete value, or if @var{low} >
990 @var{high}.
991 @end deftypefun
992
993 @deftypefun void mv_pop_range (struct missing_values *@var{mv}, double *@var{low}, double *@var{high})
994 Given @var{mv}, which must be a numeric set of user-missing values
995 that contains a range, removes that range from @var{mv} and stores its
996 low endpoint in @code{*@var{low}} and its high endpoint in
997 @code{*@var{high}}.
998 @end deftypefun
999
1000 @node Value Labels
1001 @section Value Labels
1002
1003 Each variable has a set of value labels (@pxref{VALUE LABELS,,,pspp,
1004 PSPP Users Guide}), represented as @struct{val_labs}.  A
1005 @struct{val_labs} is essentially a map from @union{value}s to strings.
1006 All of the values in a set of value labels have the same width, which
1007 for a set of value labels owned by a variable (the common case) is the
1008 same as its variable.
1009
1010 Sets of value labels may contain any number of entries.
1011
1012 It is rarely necessary to interact directly with a @struct{val_labs}
1013 object.  Instead, the most common operation, looking up the label for
1014 a value of a given variable, can be conveniently executed through
1015 functions on @struct{variable}.  @xref{Variable Value Labels}, for
1016 details.
1017
1018 Function prototypes and other declarations related to missing values
1019 are declared in @file{data/value-labels.h}.
1020
1021 @deftp {Structure} {struct val_labs}
1022 Opaque type that represents a set of value labels.
1023 @end deftp
1024
1025 The most often useful function for value labels is
1026 @func{val_labs_find}, for looking up the label associated with a
1027 value.
1028
1029 @deftypefun {char *} val_labs_find (const struct val_labs *@var{val_labs}, union value @var{value})
1030 Looks in @var{val_labs} for a label for the given @var{value}.
1031 Returns the label, if one is found, or a null pointer otherwise.
1032 @end deftypefun
1033
1034 Several other functions for working with value labels are described in
1035 the following section, but these are more rarely useful.
1036
1037 @menu
1038 * Value Labels Creation and Destruction::
1039 * Value Labels Properties::
1040 * Value Labels Adding and Removing Labels::
1041 * Value Labels Iteration::
1042 @end menu
1043
1044 @node Value Labels Creation and Destruction
1045 @subsection Creation and Destruction
1046
1047 These functions create and destroy @struct{val_labs} objects.
1048
1049 @deftypefun {struct val_labs *} val_labs_create (int @var{width})
1050 Creates and returns an initially empty set of value labels with the
1051 given @var{width}.
1052 @end deftypefun
1053
1054 @deftypefun {struct val_labs *} val_labs_clone (const struct val_labs *@var{val_labs})
1055 Creates and returns a set of value labels whose width and contents are
1056 the same as those of @var{var_labs}.
1057 @end deftypefun
1058
1059 @deftypefun void val_labs_clear (struct val_labs *@var{var_labs})
1060 Deletes all value labels from @var{var_labs}.
1061 @end deftypefun
1062
1063 @deftypefun void val_labs_destroy (struct val_labs *@var{var_labs})
1064 Destroys @var{var_labs}, which must not be referenced again.
1065 @end deftypefun
1066
1067 @node Value Labels Properties
1068 @subsection Value Labels Properties
1069
1070 These functions inspect and manipulate basic properties of
1071 @struct{val_labs} objects.
1072
1073 @deftypefun size_t val_labs_count (const struct val_labs *@var{val_labs})
1074 Returns the number of value labels in @var{val_labs}.
1075 @end deftypefun
1076
1077 @deftypefun bool val_labs_can_set_width (const struct val_labs *@var{val_labs}, int @var{new_width})
1078 Tests whether @var{val_labs}'s width may be changed to @var{new_width}
1079 using @func{val_labs_set_width}.  Returns true if it is allowed, false
1080 otherwise.
1081
1082 A set of value labels may be resized to a given width only if each
1083 value in it may be resized to that width, as determined by
1084 @func{value_is_resizable} (@pxref{value_is_resizable}).
1085 @end deftypefun
1086
1087 @deftypefun void val_labs_set_width (struct val_labs *@var{val_labs}, int @var{new_width})
1088 Changes the width of @var{val_labs}'s values to @var{new_width}, which
1089 must be a valid new width as determined by
1090 @func{val_labs_can_set_width}.
1091 @end deftypefun
1092
1093 @node Value Labels Adding and Removing Labels
1094 @subsection Adding and Removing Labels
1095
1096 These functions add and remove value labels from a @struct{val_labs}
1097 object.
1098
1099 @deftypefun bool val_labs_add (struct val_labs *@var{val_labs}, union value @var{value}, const char *@var{label})
1100 Adds @var{label} to in @var{var_labs} as a label for @var{value},
1101 which must have the same width as the set of value labels.  Returns
1102 true if successful, false if @var{value} already has a label.
1103 @end deftypefun
1104
1105 @deftypefun void val_labs_replace (struct val_labs *@var{val_labs}, union value @var{value}, const char *@var{label})
1106 Adds @var{label} to in @var{var_labs} as a label for @var{value},
1107 which must have the same width as the set of value labels.  If
1108 @var{value} already has a label in @var{var_labs}, it is replaced.
1109 @end deftypefun
1110
1111 @deftypefun bool val_labs_remove (struct val_labs *@var{val_labs}, union value @var{value})
1112 Removes from @var{val_labs} any label for @var{value}, which must have
1113 the same width as the set of value labels.  Returns true if a label
1114 was removed, false otherwise.
1115 @end deftypefun
1116
1117 @node Value Labels Iteration
1118 @subsection Iterating through Value Labels
1119
1120 These functions allow iteration through the set of value labels
1121 represented by a @struct{val_labs} object.  They may be used in the
1122 context of a @code{for} loop:
1123
1124 @example
1125 struct val_labs val_labs;
1126 const struct val_lab *vl;
1127
1128 @dots{}
1129
1130 for (vl = val_labs_first (val_labs); vl != NULL;
1131      vl = val_labs_next (val_labs, vl))
1132   @{
1133     @dots{}@r{do something with @code{vl}}@dots{}
1134   @}
1135 @end example
1136
1137 Value labels should not be added or deleted from a @struct{val_labs}
1138 as it is undergoing iteration.
1139
1140 @deftypefun {const struct val_lab *} val_labs_first (const struct val_labs *@var{val_labs})
1141 Returns the first value label in @var{var_labs}, if it contains at
1142 least one value label, or a null pointer if it does not contain any
1143 value labels.
1144 @end deftypefun
1145
1146 @deftypefun {const struct val_lab *} val_labs_next (const struct val_labs *@var{val_labs}, const struct val_labs_iterator **@var{vl})
1147 Returns the value label in @var{var_labs} following @var{vl}, if
1148 @var{vl} is not the last value label in @var{val_labs}, or a null
1149 pointer if there are no value labels following @var{vl}.
1150 @end deftypefun
1151
1152 @deftypefun {const struct val_lab **} val_labs_sorted (const struct val_labs *@var{val_labs})
1153 Allocates and returns an array of pointers to value labels, which are
1154 sorted in increasing order by value.  The array has
1155 @code{val_labs_count (@var{val_labs})} elements.  The caller is
1156 responsible for freeing the array with @func{free} (but must not free
1157 any of the @struct{val_lab} elements that the array points to).
1158 @end deftypefun
1159
1160 The iteration functions above work with pointers to @struct{val_lab}
1161 which is an opaque data structure that users of @struct{val_labs} must
1162 not modify or free directly.  The following functions work with
1163 objects of this type:
1164
1165 @deftypefun {const union value *} val_lab_get_value (const struct val_lab *@var{vl})
1166 Returns the value of value label @var{vl}.  The caller must not modify
1167 or free the returned value.  (To achieve a similar result, remove the
1168 value label with @func{val_labs_remove}, then add the new value with
1169 @func{val_labs_add}.)
1170
1171 The width of the returned value cannot be determined directly from
1172 @var{vl}.  It may be obtained by calling @func{val_labs_get_width} on
1173 the @struct{val_labs} that @var{vl} is in.
1174 @end deftypefun
1175
1176 @deftypefun {const char *} val_lab_get_label (const struct val_lab *@var{vl})
1177 Returns the label in @var{vl} as a null-terminated string.  The caller
1178 must not modify or free the returned string.  (Use
1179 @func{val_labs_replace} to change a value label.)
1180 @end deftypefun
1181
1182 @node Variables
1183 @section Variables
1184
1185 A PSPP variable is represented by @struct{variable}, an opaque type
1186 declared in @file{data/variable.h} along with related declarations.
1187 @xref{Variables,,,pspp, PSPP Users Guide}, for a description of PSPP
1188 variables from a user perspective.
1189
1190 PSPP is unusual among computer languages in that, by itself, a PSPP
1191 variable does not have a value.  Instead, a variable in PSPP takes on
1192 a value only in the context of a case, which supplies one value for
1193 each variable in a set of variables (@pxref{Cases}).  The set of
1194 variables in a case, in turn, are ordinarily part of a dictionary
1195 (@pxref{Dictionaries}).
1196
1197 Every variable has several attributes, most of which correspond
1198 directly to one of the variable attributes visible to PSPP users
1199 (@pxref{Attributes,,,pspp, PSPP Users Guide}).
1200
1201 The following sections describe variable-related functions and macros.
1202
1203 @menu
1204 * Variable Name::
1205 * Variable Type and Width::
1206 * Variable Missing Values::
1207 * Variable Value Labels::
1208 * Variable Print and Write Formats::
1209 * Variable Labels::
1210 * Variable GUI Attributes::
1211 * Variable Leave Status::
1212 * Dictionary Class::
1213 * Variable Creation and Destruction::
1214 * Variable Short Names::
1215 * Variable Relationships::
1216 * Variable Auxiliary Data::
1217 * Variable Categorical Values::
1218 @end menu
1219
1220 @node Variable Name
1221 @subsection Variable Name
1222
1223 A variable name is a string between 1 and @code{ID_MAX_LEN} bytes
1224 long that satisfies the rules for PSPP identifiers
1225 (@pxref{Tokens,,,pspp, PSPP Users Guide}).  Variable names are
1226 mixed-case and treated case-insensitively.
1227
1228 @deftypefn Macro int ID_MAX_LEN
1229 Maximum length of a variable name, in bytes, currently 64.
1230 @end deftypefn
1231
1232 Only one commonly useful function relates to variable names:
1233
1234 @deftypefun {const char *} var_get_name (const struct variable *@var{var})
1235 Returns @var{var}'s variable name as a C string.
1236 @end deftypefun
1237
1238 A few other functions are much more rarely used.  Some of these
1239 functions are used internally by the dictionary implementation:
1240
1241 @anchor{var_set_name}
1242 @deftypefun {void} var_set_name (struct variable *@var{var}, const char *@var{new_name})
1243 Changes the name of @var{var} to @var{new_name}, which must be a
1244 ``plausible'' name as defined below.
1245
1246 This function cannot be applied to a variable that is part of a
1247 dictionary.  Use @func{dict_rename_var} instead (@pxref{Dictionary
1248 Renaming Variables}).
1249 @end deftypefun
1250
1251 @deftypefun {enum dict_class} var_get_dict_class (const struct variable *@var{var})
1252 Returns the dictionary class of @var{var}'s name (@pxref{Dictionary
1253 Class}).
1254 @end deftypefun
1255
1256 @node Variable Type and Width
1257 @subsection Variable Type and Width
1258
1259 A variable's type and width are the type and width of its values
1260 (@pxref{Values}).
1261
1262 @deftypefun {enum val_type} var_get_type (const struct variable *@var{var})
1263 Returns the type of variable @var{var}.
1264 @end deftypefun
1265
1266 @deftypefun int var_get_width (const struct variable *@var{var})
1267 Returns the width of variable @var{var}.
1268 @end deftypefun
1269
1270 @deftypefun void var_set_width (struct variable *@var{var}, int @var{width})
1271 Sets the width of variable @var{var} to @var{width}.  The width of a
1272 variable should not normally be changed after the variable is created,
1273 so this function is rarely used.  This function cannot be applied to a
1274 variable that is part of a dictionary.
1275 @end deftypefun
1276
1277 @deftypefun bool var_is_numeric (const struct variable *@var{var})
1278 Returns true if @var{var} is a numeric variable, false otherwise.
1279 @end deftypefun
1280
1281 @deftypefun bool var_is_alpha (const struct variable *@var{var})
1282 Returns true if @var{var} is an alphanumeric (string) variable, false
1283 otherwise.
1284 @end deftypefun
1285
1286 @node Variable Missing Values
1287 @subsection Variable Missing Values
1288
1289 A numeric or short string variable may have a set of user-missing
1290 values (@pxref{MISSING VALUES,,,pspp, PSPP Users Guide}), represented
1291 as a @struct{missing_values} (@pxref{User-Missing Values}).
1292
1293 The most frequent operation on a variable's missing values is to query
1294 whether a value is user- or system-missing:
1295
1296 @deftypefun bool var_is_value_missing (const struct variable *@var{var}, const union value *@var{value}, enum mv_class @var{class})
1297 @deftypefunx bool var_is_num_missing (const struct variable *@var{var}, double @var{value}, enum mv_class @var{class})
1298 @deftypefunx bool var_is_str_missing (const struct variable *@var{var}, const char @var{value}[], enum mv_class @var{class})
1299 Tests whether @var{value} is a missing value of the given @var{class}
1300 for variable @var{var} and returns true if so, false otherwise.
1301 @func{var_is_num_missing} may only be applied to numeric variables;
1302 @func{var_is_str_missing} may only be applied to string variables.
1303 @var{value} must have been initialized with the same width as
1304 @var{var}.
1305
1306 @code{var_is_@var{type}_missing (@var{var}, @var{value}, @var{class})}
1307 is equivalent to @code{mv_is_@var{type}_missing
1308 (var_get_missing_values (@var{var}), @var{value}, @var{class})}.
1309 @end deftypefun
1310
1311 In addition, a few functions are provided to work more directly with a
1312 variable's @struct{missing_values}:
1313
1314 @deftypefun {const struct missing_values *} var_get_missing_values (const struct variable *@var{var})
1315 Returns the @struct{missing_values} associated with @var{var}.  The
1316 caller must not modify the returned structure.  The return value is
1317 always non-null.
1318 @end deftypefun
1319
1320 @anchor{var_set_missing_values}
1321 @deftypefun {void} var_set_missing_values (struct variable *@var{var}, const struct missing_values *@var{miss})
1322 Changes @var{var}'s missing values to a copy of @var{miss}, or if
1323 @var{miss} is a null pointer, clears @var{var}'s missing values.  If
1324 @var{miss} is non-null, it must have the same width as @var{var} or be
1325 resizable to @var{var}'s width (@pxref{mv_resize}).  The caller
1326 retains ownership of @var{miss}.
1327 @end deftypefun
1328
1329 @deftypefun void var_clear_missing_values (struct variable *@var{var})
1330 Clears @var{var}'s missing values.  Equivalent to
1331 @code{var_set_missing_values (@var{var}, NULL)}.
1332 @end deftypefun
1333
1334 @deftypefun bool var_has_missing_values (const struct variable *@var{var})
1335 Returns true if @var{var} has any missing values, false if it has
1336 none.  Equivalent to @code{mv_is_empty (var_get_missing_values (@var{var}))}.
1337 @end deftypefun
1338
1339 @node Variable Value Labels
1340 @subsection Variable Value Labels
1341
1342 A numeric or short string variable may have a set of value labels
1343 (@pxref{VALUE LABELS,,,pspp, PSPP Users Guide}), represented as a
1344 @struct{val_labs} (@pxref{Value Labels}).  The most commonly useful
1345 functions for value labels return the value label associated with a
1346 value:
1347
1348 @deftypefun {const char *} var_lookup_value_label (const struct variable *@var{var}, const union value *@var{value})
1349 Looks for a label for @var{value} in @var{var}'s set of value labels.
1350 @var{value} must have the same width as @var{var}.  Returns the label
1351 if one exists, otherwise a null pointer.
1352 @end deftypefun
1353
1354 @deftypefun void var_append_value_name (const struct variable *@var{var}, const union value *@var{value}, struct string *@var{str})
1355 Looks for a label for @var{value} in @var{var}'s set of value labels.
1356 @var{value} must have the same width as @var{var}.
1357 If a label exists, it will be appended to the string pointed to by @var{str}.
1358 Otherwise, it formats @var{value}
1359 using @var{var}'s print format (@pxref{Input and Output Formats}) 
1360 and appends the formatted string.
1361 @end deftypefun
1362
1363 The underlying @struct{val_labs} structure may also be accessed
1364 directly using the functions described below.
1365
1366 @deftypefun bool var_has_value_labels (const struct variable *@var{var})
1367 Returns true if @var{var} has at least one value label, false
1368 otherwise.
1369 @end deftypefun
1370
1371 @deftypefun {const struct val_labs *} var_get_value_labels (const struct variable *@var{var})
1372 Returns the @struct{val_labs} associated with @var{var}.  If @var{var}
1373 has no value labels, then the return value may or may not be a null
1374 pointer.
1375
1376 The variable retains ownership of the returned @struct{val_labs},
1377 which the caller must not attempt to modify.
1378 @end deftypefun
1379
1380 @deftypefun void var_set_value_labels (struct variable *@var{var}, const struct val_labs *@var{val_labs})
1381 Replaces @var{var}'s value labels by a copy of @var{val_labs}.  The
1382 caller retains ownership of @var{val_labs}.  If @var{val_labs} is a
1383 null pointer, then @var{var}'s value labels, if any, are deleted.
1384 @end deftypefun
1385
1386 @deftypefun void var_clear_value_labels (struct variable *@var{var})
1387 Deletes @var{var}'s value labels.  Equivalent to
1388 @code{var_set_value_labels (@var{var}, NULL)}.
1389 @end deftypefun
1390
1391 A final group of functions offers shorthands for operations that would
1392 otherwise require getting the value labels from a variable, copying
1393 them, modifying them, and then setting the modified value labels into
1394 the variable (making a second copy):
1395
1396 @deftypefun bool var_add_value_label (struct variable *@var{var}, const union value *@var{value}, const char *@var{label})
1397 Attempts to add a copy of @var{label} as a label for @var{value} for
1398 the given @var{var}.  @var{value} must have the same width as
1399 @var{var}.  If @var{value} already has a label, then the old label is
1400 retained.  Returns true if a label is added, false if there was an
1401 existing label for @var{value}.  Either way, the caller retains
1402 ownership of @var{value} and @var{label}.
1403 @end deftypefun
1404
1405 @deftypefun void var_replace_value_label (struct variable *@var{var}, const union value *@var{value}, const char *@var{label})
1406 Attempts to add a copy of @var{label} as a label for @var{value} for
1407 the given @var{var}.  @var{value} must have the same width as
1408 @var{var}.  If @var{value} already has a label, then
1409 @var{label} replaces the old label.  Either way, the caller retains
1410 ownership of @var{value} and @var{label}.
1411 @end deftypefun
1412
1413 @node Variable Print and Write Formats
1414 @subsection Variable Print and Write Formats
1415
1416 Each variable has an associated pair of output formats, called its
1417 @dfn{print format} and @dfn{write format}.  @xref{Input and Output
1418 Formats,,,pspp, PSPP Users Guide}, for an introduction to formats.
1419 @xref{Input and Output Formats}, for a developer's description of
1420 format representation.
1421
1422 The print format is used to convert a variable's data values to
1423 strings for human-readable output.  The write format is used similarly
1424 for machine-readable output, primarily by the WRITE transformation
1425 (@pxref{WRITE,,,pspp, PSPP Users Guide}).  Most often a variable's
1426 print and write formats are the same.
1427
1428 A newly created variable by default has format F8.2 if it is numeric
1429 or an A format with the same width as the variable if it is string.
1430 Many creators of variables override these defaults.
1431
1432 Both the print format and write format are output formats.  Input
1433 formats are not part of @struct{variable}.  Instead, input programs
1434 and transformations keep track of variable input formats themselves.
1435
1436 The following functions work with variable print and write formats.
1437
1438 @deftypefun {const struct fmt_spec *} var_get_print_format (const struct variable *@var{var})
1439 @deftypefunx {const struct fmt_spec *} var_get_write_format (const struct variable *@var{var})
1440 Returns @var{var}'s print or write format, respectively.
1441 @end deftypefun
1442
1443 @deftypefun void var_set_print_format (struct variable *@var{var}, const struct fmt_spec *@var{format})
1444 @deftypefunx void var_set_write_format (struct variable *@var{var}, const struct fmt_spec *@var{format})
1445 @deftypefunx void var_set_both_formats (struct variable *@var{var}, const struct fmt_spec *@var{format})
1446 Sets @var{var}'s print format, write format, or both formats,
1447 respectively, to a copy of @var{format}.
1448 @end deftypefun
1449
1450 @node Variable Labels
1451 @subsection Variable Labels
1452
1453 A variable label is a string that describes a variable.  Variable
1454 labels may contain spaces and punctuation not allowed in variable
1455 names.  @xref{VARIABLE LABELS,,,pspp, PSPP Users Guide}, for a
1456 user-level description of variable labels.
1457
1458 The most commonly useful functions for variable labels are those to
1459 retrieve a variable's label:
1460
1461 @deftypefun {const char *} var_to_string (const struct variable *@var{var})
1462 Returns @var{var}'s variable label, if it has one, otherwise
1463 @var{var}'s name.  In either case the caller must not attempt to
1464 modify or free the returned string.
1465
1466 This function is useful for user output.
1467 @end deftypefun
1468
1469 @deftypefun {const char *} var_get_label (const struct variable *@var{var})
1470 Returns @var{var}'s variable label, if it has one, or a null pointer
1471 otherwise.
1472 @end deftypefun
1473
1474 A few other variable label functions are also provided:
1475
1476 @deftypefun void var_set_label (struct variable *@var{var}, const char *@var{label})
1477 Sets @var{var}'s variable label to a copy of @var{label}, or removes
1478 any label from @var{var} if @var{label} is a null pointer or contains
1479 only spaces.  Leading and trailing spaces are removed from the
1480 variable label and its remaining content is truncated at 255 bytes.
1481 @end deftypefun
1482
1483 @deftypefun void var_clear_label (struct variable *@var{var})
1484 Removes any variable label from @var{var}.
1485 @end deftypefun
1486
1487 @deftypefun bool var_has_label (const struct variable *@var{var})
1488 Returns true if @var{var} has a variable label, false otherwise.
1489 @end deftypefun
1490
1491 @node Variable GUI Attributes
1492 @subsection GUI Attributes
1493
1494 These functions and types access and set attributes that are mainly
1495 used by graphical user interfaces.  Their values are also stored in
1496 and retrieved from system files (but not portable files).
1497
1498 The first group of functions relate to the measurement level of
1499 numeric data.  New variables are assigned a nominal level of
1500 measurement by default.
1501
1502 @deftp {Enumeration} {enum measure}
1503 Measurement level.  Available values are:
1504
1505 @table @code
1506 @item MEASURE_NOMINAL
1507 Numeric data values are arbitrary.  Arithmetic operations and
1508 numerical comparisons of such data are not meaningful.
1509
1510 @item MEASURE_ORDINAL
1511 Numeric data values indicate progression along a rank order.
1512 Arbitrary arithmetic operations such as addition are not meaningful on
1513 such data, but inequality comparisons (less, greater, etc.) have
1514 straightforward interpretations.
1515
1516 @item MEASURE_SCALE
1517 Ratios, sums, etc. of numeric data values have meaningful
1518 interpretations.
1519 @end table
1520
1521 PSPP does not have a separate category for interval data, which would
1522 naturally fall between the ordinal and scale measurement levels.
1523 @end deftp
1524
1525 @deftypefun bool measure_is_valid (enum measure @var{measure})
1526 Returns true if @var{measure} is a valid level of measurement, that
1527 is, if it is one of the @code{enum measure} constants listed above,
1528 and false otherwise.
1529 @end deftypefun
1530
1531 @deftypefun enum measure var_get_measure (const struct variable *@var{var})
1532 @deftypefunx void var_set_measure (struct variable *@var{var}, enum measure @var{measure})
1533 Gets or sets @var{var}'s measurement level.
1534 @end deftypefun
1535
1536 The following set of functions relates to the width of on-screen
1537 columns used for displaying variable data in a graphical user
1538 interface environment.  The unit of measurement is the width of a
1539 character.  For proportionally spaced fonts, this is based on the
1540 average width of a character.
1541
1542 @deftypefun int var_get_display_width (const struct variable *@var{var})
1543 @deftypefunx void var_set_display_width (struct variable *@var{var}, int @var{display_width})
1544 Gets or sets @var{var}'s display width.
1545 @end deftypefun
1546
1547 @anchor{var_default_display_width}
1548 @deftypefun int var_default_display_width (int @var{width})
1549 Returns the default display width for a variable with the given
1550 @var{width}.  The default width of a numeric variable is 8.  The
1551 default width of a string variable is @var{width} or 32, whichever is
1552 less.
1553 @end deftypefun
1554
1555 The final group of functions work with the justification of data when
1556 it is displayed in on-screen columns.  New variables are by default
1557 right-justified.
1558
1559 @deftp {Enumeration} {enum alignment}
1560 Text justification.  Possible values are @code{ALIGN_LEFT},
1561 @code{ALIGN_RIGHT}, and @code{ALIGN_CENTRE}.
1562 @end deftp
1563
1564 @deftypefun bool alignment_is_valid (enum alignment @var{alignment})
1565 Returns true if @var{alignment} is a valid alignment, that is, if it
1566 is one of the @code{enum alignment} constants listed above, and false
1567 otherwise.
1568 @end deftypefun
1569
1570 @deftypefun enum alignment var_get_alignment (const struct variable *@var{var})
1571 @deftypefunx void var_set_alignment (struct variable *@var{var}, enum alignment @var{alignment})
1572 Gets or sets @var{var}'s alignment.
1573 @end deftypefun
1574
1575 @node Variable Leave Status
1576 @subsection Variable Leave Status
1577
1578 Commonly, most or all data in a case come from an input file, read
1579 with a command such as DATA LIST or GET, but data can also be
1580 generated with transformations such as COMPUTE.  In the latter case
1581 the question of a datum's ``initial value'' can arise.  For example,
1582 the value of a piece of generated data can recursively depend on its
1583 own value:
1584 @example
1585 COMPUTE X = X + 1.
1586 @end example
1587 Another situation where the initial value of a variable arises is when
1588 its value is not set at all for some cases, e.g.@: below, @code{Y} is
1589 set only for the first 10 cases:
1590 @example
1591 DO IF #CASENUM <= 10.
1592 + COMPUTE Y = 1.
1593 END IF.
1594 @end example
1595
1596 By default, the initial value of a datum in either of these situations
1597 is the system-missing value for numeric values and spaces for string
1598 values.  This means that, above, X would be system-missing and that Y
1599 would be 1 for the first 10 cases and system-missing for the
1600 remainder.
1601
1602 PSPP also supports retaining the value of a variable from one case to
1603 another, using the LEAVE command (@pxref{LEAVE,,,pspp, PSPP Users
1604 Guide}).  The initial value of such a variable is 0 if it is numeric
1605 and spaces if it is a string.  If the command @samp{LEAVE X Y} is
1606 appended to the above example, then X would have value 1 in the first
1607 case and increase by 1 in every succeeding case, and Y would have
1608 value 1 for the first 10 cases and 0 for later cases.
1609
1610 The LEAVE command has no effect on data that comes from an input file
1611 or whose values do not depend on a variable's initial value.
1612
1613 The value of scratch variables (@pxref{Scratch Variables,,,pspp, PSPP
1614 Users Guide}) are always left from one case to another.
1615
1616 The following functions work with a variable's leave status.
1617
1618 @deftypefun bool var_get_leave (const struct variable *@var{var})
1619 Returns true if @var{var}'s value is to be retained from case to case,
1620 false if it is reinitialized to system-missing or spaces.
1621 @end deftypefun
1622
1623 @deftypefun void var_set_leave (struct variable *@var{var}, bool @var{leave})
1624 If @var{leave} is true, marks @var{var} to be left from case to case;
1625 if @var{leave} is false, marks @var{var} to be reinitialized for each
1626 case.
1627
1628 If @var{var} is a scratch variable, @var{leave} must be true.
1629 @end deftypefun
1630
1631 @deftypefun bool var_must_leave (const struct variable *@var{var})
1632 Returns true if @var{var} must be left from case to case, that is, if
1633 @var{var} is a scratch variable.
1634 @end deftypefun
1635
1636 @node Dictionary Class
1637 @subsection Dictionary Class
1638
1639 Occasionally it is useful to classify variables into @dfn{dictionary
1640 classes} based on their names.  Dictionary classes are represented by
1641 @enum{dict_class}.  This type and other declarations for dictionary
1642 classes are in the @file{<data/dict-class.h>} header.
1643
1644 @deftp {Enumeration} {enum dict_class}
1645 The dictionary classes are:
1646
1647 @table @code
1648 @item DC_ORDINARY
1649 An ordinary variable, one whose name does not begin with @samp{$} or
1650 @samp{#}.
1651
1652 @item DC_SYSTEM
1653 A system variable, one whose name begins with @samp{$}.  @xref{System
1654 Variables,,,pspp, PSPP Users Guide}.
1655
1656 @item DC_SCRATCH
1657 A scratch variable, one whose name begins with @samp{#}.
1658 @xref{Scratch Variables,,,pspp, PSPP Users Guide}.
1659 @end table
1660
1661 The values for dictionary classes are bitwise disjoint, which allows
1662 them to be used in bit-masks.  An extra enumeration constant
1663 @code{DC_ALL}, whose value is the bitwise-@i{or} of all of the above
1664 constants, is provided to aid in this purpose.
1665 @end deftp
1666
1667 One example use of dictionary classes arises in connection with PSPP
1668 syntax that uses @code{@var{a} TO @var{b}} to name the variables in a
1669 dictionary from @var{a} to @var{b} (@pxref{Sets of Variables,,,pspp,
1670 PSPP Users Guide}).  This syntax requires @var{a} and @var{b} to be in
1671 the same dictionary class.  It limits the variables that it includes
1672 to those in that dictionary class.
1673
1674 The following functions relate to dictionary classes.
1675
1676 @deftypefun {enum dict_class} dict_class_from_id (const char *@var{name})
1677 Returns the ``dictionary class'' for the given variable @var{name}, by
1678 looking at its first letter.
1679 @end deftypefun
1680
1681 @deftypefun {const char *} dict_class_to_name (enum dict_class @var{dict_class})
1682 Returns a name for the given @var{dict_class} as an adjective, e.g.@:
1683 @code{"scratch"}.
1684
1685 This function should probably not be used in new code as it can lead
1686 to difficulties for internationalization.
1687 @end deftypefun
1688
1689 @node Variable Creation and Destruction
1690 @subsection Variable Creation and Destruction
1691
1692 Only rarely should PSPP code create or destroy variables directly.
1693 Ordinarily, variables are created within a dictionary and destroying
1694 by individual deletion from the dictionary or by destroying the entire
1695 dictionary at once.  The functions here enable the exceptional case,
1696 of creation and destruction of variables that are not associated with
1697 any dictionary.  These functions are used internally in the dictionary
1698 implementation.
1699
1700 @anchor{var_create}
1701 @deftypefun {struct variable *} var_create (const char *@var{name}, int @var{width})
1702 Creates and returns a new variable with the given @var{name} and
1703 @var{width}.  The new variable is not part of any dictionary.  Use
1704 @func{dict_create_var}, instead, to create a variable in a dictionary
1705 (@pxref{Dictionary Creating Variables}).
1706
1707 @var{name} should be a valid variable name and must be a ``plausible''
1708 variable name (@pxref{Variable Name}).  @var{width} must be between 0
1709 and @code{MAX_STRING}, inclusive (@pxref{Values}).
1710
1711 The new variable has no user-missing values, value labels, or variable
1712 label.  Numeric variables initially have F8.2 print and write formats,
1713 right-justified display alignment, and scale level of measurement.
1714 String variables are created with A print and write formats,
1715 left-justified display alignment, and nominal level of measurement.
1716 The initial display width is determined by
1717 @func{var_default_display_width} (@pxref{var_default_display_width}).
1718
1719 The new variable initially has no short name (@pxref{Variable Short
1720 Names}) and no auxiliary data (@pxref{Variable Auxiliary Data}).
1721 @end deftypefun
1722
1723 @anchor{var_clone}
1724 @deftypefun {struct variable *} var_clone (const struct variable *@var{old_var})
1725 Creates and returns a new variable with the same attributes as
1726 @var{old_var}, with a few exceptions.  First, the new variable is not
1727 part of any dictionary, regardless of whether @var{old_var} was in a
1728 dictionary.  Use @func{dict_clone_var}, instead, to add a clone of a
1729 variable to a dictionary.
1730
1731 Second, the new variable is not given any short name, even if
1732 @var{old_var} had a short name.  This is because the new variable is
1733 likely to be immediately renamed, in which case the short name would
1734 be incorrect (@pxref{Variable Short Names}).
1735
1736 Finally, @var{old_var}'s auxiliary data, if any, is not copied to the
1737 new variable (@pxref{Variable Auxiliary Data}).
1738 @end deftypefun
1739
1740 @deftypefun {void} var_destroy (struct variable *@var{var})
1741 Destroys @var{var} and frees all associated storage, including its
1742 auxiliary data, if any.  @var{var} must not be part of a dictionary.
1743 To delete a variable from a dictionary and destroy it, use
1744 @func{dict_delete_var} (@pxref{Dictionary Deleting Variables}).
1745 @end deftypefun
1746
1747 @node Variable Short Names
1748 @subsection Variable Short Names
1749
1750 PSPP variable names may be up to 64 (@code{ID_MAX_LEN}) bytes long.
1751 The system and portable file formats, however, were designed when
1752 variable names were limited to 8 bytes in length.  Since then, the
1753 system file format has been augmented with an extension record that
1754 explains how the 8-byte short names map to full-length names
1755 (@pxref{Long Variable Names Record}), but the short names are still
1756 present.  Thus, the continued presence of the short names is more or
1757 less invisible to PSPP users, but every variable in a system file
1758 still has a short name that must be unique.
1759
1760 PSPP can generate unique short names for variables based on their full
1761 names at the time it creates the data file.  If all variables' full
1762 names are unique in their first 8 bytes, then the short names are
1763 simply prefixes of the full names; otherwise, PSPP changes them so
1764 that they are unique.
1765
1766 By itself this algorithm interoperates well with other software that
1767 can read system files, as long as that software understands the
1768 extension record that maps short names to long names.  When the other
1769 software does not understand the extension record, it can produce
1770 surprising results.  Consider a situation where PSPP reads a system
1771 file that contains two variables named RANKINGSCORE, then the user
1772 adds a new variable named RANKINGSTATUS, then saves the modified data
1773 as a new system file.  A program that does not understand long names
1774 would then see one of these variables under the name RANKINGS---either
1775 one, depending on the algorithm's details---and the other under a
1776 different name.  The effect could be very confusing: by adding a new
1777 and apparently unrelated variable in PSPP, the user effectively
1778 renamed the existing variable.
1779
1780 To counteract this potential problem, every @struct{variable} may have
1781 a short name.  A variable created by the system or portable file
1782 reader receives the short name from that data file.  When a variable
1783 with a short name is written to a system or portable file, that
1784 variable receives priority over other long names whose names begin
1785 with the same 8 bytes but which were not read from a data file under
1786 that short name.
1787
1788 Variables not created by the system or portable file reader have no
1789 short name by default.
1790
1791 A variable with a full name of 8 bytes or less in length has absolute
1792 priority for that name when the variable is written to a system file,
1793 even over a second variable with that assigned short name.
1794
1795 PSPP does not enforce uniqueness of short names, although the short
1796 names read from any given data file will always be unique.  If two
1797 variables with the same short name are written to a single data file,
1798 neither one receives priority.
1799
1800 The following macros and functions relate to short names.
1801
1802 @defmac SHORT_NAME_LEN
1803 Maximum length of a short name, in bytes.  Its value is 8.
1804 @end defmac
1805
1806 @deftypefun {const char *} var_get_short_name (const struct variable *@var{var})
1807 Returns @var{var}'s short name, or a null pointer if @var{var} has not
1808 been assigned a short name.
1809 @end deftypefun
1810
1811 @deftypefun void var_set_short_name (struct variable *@var{var}, const char *@var{short_name})
1812 Sets @var{var}'s short name to @var{short_name}, or removes
1813 @var{var}'s short name if @var{short_name} is a null pointer.  If it
1814 is non-null, then @var{short_name} must be a plausible name for a
1815 variable.  The name will be truncated
1816 to 8 bytes in length and converted to all-uppercase.
1817 @end deftypefun
1818
1819 @deftypefun void var_clear_short_name (struct variable *@var{var})
1820 Removes @var{var}'s short name.
1821 @end deftypefun
1822
1823 @node Variable Relationships
1824 @subsection Variable Relationships
1825
1826 Variables have close relationships with dictionaries
1827 (@pxref{Dictionaries}) and cases (@pxref{Cases}).  A variable is
1828 usually a member of some dictionary, and a case is often used to store
1829 data for the set of variables in a dictionary.
1830
1831 These functions report on these relationships.  They may be applied
1832 only to variables that are in a dictionary.
1833
1834 @deftypefun size_t var_get_dict_index (const struct variable *@var{var})
1835 Returns @var{var}'s index within its dictionary.  The first variable
1836 in a dictionary has index 0, the next variable index 1, and so on.
1837
1838 The dictionary index can be influenced using dictionary functions such
1839 as dict_reorder_var (@pxref{dict_reorder_var}).
1840 @end deftypefun
1841
1842 @deftypefun size_t var_get_case_index (const struct variable *@var{var})
1843 Returns @var{var}'s index within a case.  The case index is an index
1844 into an array of @union{value} large enough to contain all the data in
1845 the dictionary.
1846
1847 The returned case index can be used to access the value of @var{var}
1848 within a case for its dictionary, as in e.g.@: @code{case_data_idx
1849 (case, var_get_case_index (@var{var}))}, but ordinarily it is more
1850 convenient to use the data access functions that do variable-to-index
1851 translation internally, as in e.g.@: @code{case_data (case,
1852 @var{var})}.
1853 @end deftypefun
1854
1855 @node Variable Auxiliary Data
1856 @subsection Variable Auxiliary Data
1857
1858 Each @struct{variable} can have a single pointer to auxiliary data of
1859 type @code{void *}.  These functions manipulate a variable's auxiliary
1860 data.
1861
1862 Use of auxiliary data is discouraged because of its lack of
1863 flexibility.  Only one client can make use of auxiliary data on a
1864 given variable at any time, even though many clients could usefully
1865 associate data with a variable.
1866
1867 To prevent multiple clients from attempting to use a variable's single
1868 auxiliary data field at the same time, we adopt the convention that
1869 use of auxiliary data in the active dataset dictionary is restricted to
1870 the currently executing command.  In particular, transformations must
1871 not attach auxiliary data to a variable in the active dataset in the
1872 expectation that it can be used later when the active dataset is read and
1873 the transformation is executed.  To help enforce this restriction,
1874 auxiliary data is deleted from all variables in the active dataset
1875 dictionary after the execution of each PSPP command.
1876
1877 This convention for safe use of auxiliary data applies only to the
1878 active dataset dictionary.  Rules for other dictionaries may be
1879 established separately.
1880
1881 Auxiliary data should be replaced by a more flexible mechanism at some
1882 point, but no replacement mechanism has been designed or implemented
1883 so far.
1884
1885 The following functions work with variable auxiliary data.
1886
1887 @deftypefun {void *} var_get_aux (const struct variable *@var{var})
1888 Returns @var{var}'s auxiliary data, or a null pointer if none has been
1889 assigned.
1890 @end deftypefun
1891
1892 @deftypefun {void *} var_attach_aux (const struct variable *@var{var}, void *@var{aux}, void (*@var{aux_dtor}) (struct variable *))
1893 Sets @var{var}'s auxiliary data to @var{aux}, which must not be null.
1894 @var{var} must not already have auxiliary data.
1895
1896 Before @var{var}'s auxiliary data is cleared by @code{var_clear_aux},
1897 @var{aux_dtor}, if non-null, will be called with @var{var} as its
1898 argument.  It should free any storage associated with @var{aux}, if
1899 necessary.  @code{var_dtor_free} may be appropriate for use as
1900 @var{aux_dtor}:
1901
1902 @deffn {Function} void var_dtor_free (struct variable *@var{var})
1903 Frees @var{var}'s auxiliary data by calling @code{free}.
1904 @end deffn
1905 @end deftypefun
1906
1907 @deftypefun void var_clear_aux (struct variable *@var{var})
1908 Removes auxiliary data, if any, from @var{var}, first calling the
1909 destructor passed to @code{var_attach_aux}, if one was provided.
1910
1911 Use @code{dict_clear_aux} to remove auxiliary data from every variable
1912 in a dictionary. @c (@pxref{dict_clear_aux}).
1913 @end deftypefun
1914
1915 @deftypefun {void *} var_detach_aux (struct variable *@var{var})
1916 Removes auxiliary data, if any, from @var{var}, and returns it.
1917 Returns a null pointer if @var{var} had no auxiliary data.
1918
1919 Any destructor passed to @code{var_attach_aux} is not called, so the
1920 caller is responsible for freeing storage associated with the returned
1921 auxiliary data.
1922 @end deftypefun
1923
1924 @node Variable Categorical Values
1925 @subsection Variable Categorical Values
1926
1927 Some statistical procedures require a list of all the values that a
1928 categorical variable takes on.  Arranging such a list requires making
1929 a pass through the data, so PSPP caches categorical values in
1930 @struct{variable}.
1931
1932 When variable auxiliary data is revamped to support multiple clients
1933 as described in the previous section, categorical values are an
1934 obvious candidate.  The form in which they are currently supported is
1935 inelegant.
1936
1937 Categorical values are not robust against changes in the data.  That
1938 is, there is currently no way to detect that a transformation has
1939 changed data values, meaning that categorical values lists for the
1940 changed variables must be recomputed.  PSPP is in fact in need of a
1941 general-purpose caching and cache-invalidation mechanism, but none
1942 has yet been designed and built.
1943
1944 The following functions work with cached categorical values.
1945
1946 @deftypefun {struct cat_vals *} var_get_obs_vals (const struct variable *@var{var})
1947 Returns @var{var}'s set of categorical values.  Yields undefined
1948 behavior if @var{var} does not have any categorical values.
1949 @end deftypefun
1950
1951 @deftypefun void var_set_obs_vals (const struct variable *@var{var}, struct cat_vals *@var{cat_vals})
1952 Destroys @var{var}'s categorical values, if any, and replaces them by
1953 @var{cat_vals}, ownership of which is transferred to @var{var}.  If
1954 @var{cat_vals} is a null pointer, then @var{var}'s categorical values
1955 are cleared.
1956 @end deftypefun
1957
1958 @deftypefun bool var_has_obs_vals (const struct variable *@var{var})
1959 Returns true if @var{var} has a set of categorical values, false
1960 otherwise.
1961 @end deftypefun
1962
1963 @node Dictionaries
1964 @section Dictionaries
1965
1966 Each data file in memory or on disk has an associated dictionary,
1967 whose primary purpose is to describe the data in the file.
1968 @xref{Variables,,,pspp, PSPP Users Guide}, for a PSPP user's view of a
1969 dictionary.
1970
1971 A data file stored in a PSPP format, either as a system or portable
1972 file, has a representation of its dictionary embedded in it.  Other
1973 kinds of data files are usually not self-describing enough to
1974 construct a dictionary unassisted, so the dictionaries for these files
1975 must be specified explicitly with PSPP commands such as @cmd{DATA
1976 LIST}.
1977
1978 The most important content of a dictionary is an array of variables,
1979 which must have unique names.  A dictionary also conceptually contains
1980 a mapping from each of its variables to a location within a case
1981 (@pxref{Cases}), although in fact these mappings are stored within
1982 individual variables.
1983
1984 System variables are not members of any dictionary (@pxref{System
1985 Variables,,,pspp, PSPP Users Guide}).
1986
1987 Dictionaries are represented by @struct{dictionary}.  Declarations
1988 related to dictionaries are in the @file{<data/dictionary.h>} header.
1989
1990 The following sections describe functions for use with dictionaries.
1991
1992 @menu
1993 * Dictionary Variable Access::
1994 * Dictionary Creating Variables::
1995 * Dictionary Deleting Variables::
1996 * Dictionary Reordering Variables::
1997 * Dictionary Renaming Variables::
1998 * Dictionary Weight Variable::
1999 * Dictionary Filter Variable::
2000 * Dictionary Case Limit::
2001 * Dictionary Split Variables::
2002 * Dictionary File Label::
2003 * Dictionary Documents::
2004 @end menu
2005
2006 @node Dictionary Variable Access
2007 @subsection Accessing Variables
2008
2009 The most common operations on a dictionary simply retrieve a
2010 @code{struct variable *} of an individual variable based on its name
2011 or position.
2012
2013 @deftypefun {struct variable *} dict_lookup_var (const struct dictionary *@var{dict}, const char *@var{name})
2014 @deftypefunx {struct variable *} dict_lookup_var_assert (const struct dictionary *@var{dict}, const char *@var{name})
2015 Looks up and returns the variable with the given @var{name} within
2016 @var{dict}.  Name lookup is not case-sensitive.
2017
2018 @code{dict_lookup_var} returns a null pointer if @var{dict} does not
2019 contain a variable named @var{name}.  @code{dict_lookup_var_assert}
2020 asserts that such a variable exists.
2021 @end deftypefun
2022
2023 @deftypefun {struct variable *} dict_get_var (const struct dictionary *@var{dict}, size_t @var{position})
2024 Returns the variable at the given @var{position} in @var{dict}.
2025 @var{position} must be less than the number of variables in @var{dict}
2026 (see below).
2027 @end deftypefun
2028
2029 @deftypefun size_t dict_get_var_cnt (const struct dictionary *@var{dict})
2030 Returns the number of variables in @var{dict}.
2031 @end deftypefun
2032
2033 Another pair of functions allows retrieving a number of variables at
2034 once.  These functions are more rarely useful.
2035
2036 @deftypefun void dict_get_vars (const struct dictionary *@var{dict}, const struct variable ***@var{vars}, size_t *@var{cnt}, enum dict_class @var{exclude})
2037 @deftypefunx void dict_get_vars_mutable (const struct dictionary *@var{dict}, struct variable ***@var{vars}, size_t *@var{cnt}, enum dict_class @var{exclude})
2038 Retrieves all of the variables in @var{dict}, in their original order,
2039 except that any variables in the dictionary classes specified
2040 @var{exclude}, if any, are excluded (@pxref{Dictionary Class}).
2041 Pointers to the variables are stored in an array allocated with
2042 @code{malloc}, and a pointer to the first element of this array is
2043 stored in @code{*@var{vars}}.  The caller is responsible for freeing
2044 this memory when it is no longer needed.  The number of variables
2045 retrieved is stored in @code{*@var{cnt}}.
2046
2047 The presence or absence of @code{DC_SYSTEM} in @var{exclude} has no
2048 effect, because dictionaries never include system variables.
2049 @end deftypefun
2050
2051 One additional function is available.  This function is most often
2052 used in assertions, but it is not restricted to such use.
2053
2054 @deftypefun bool dict_contains_var (const struct dictionary *@var{dict}, const struct variable *@var{var})
2055 Tests whether @var{var} is one of the variables in @var{dict}.
2056 Returns true if so, false otherwise.
2057 @end deftypefun
2058
2059 @node Dictionary Creating Variables
2060 @subsection Creating Variables
2061
2062 These functions create a new variable and insert it into a dictionary
2063 in a single step.
2064
2065 There is no provision for inserting an already created variable into a
2066 dictionary.  There is no reason that such a function could not be
2067 written, but so far there has been no need for one.
2068
2069 The names provided to one of these functions should be valid variable
2070 names and must be plausible variable names. @c (@pxref{Variable Names}).
2071
2072 If a variable with the same name already exists in the dictionary, the
2073 non-@code{assert} variants of these functions return a null pointer,
2074 without modifying the dictionary.  The @code{assert} variants, on the
2075 other hand, assert that no duplicate name exists.
2076
2077 A variable may be in only one dictionary at any given time.
2078
2079 @deftypefun {struct variable *} dict_create_var (struct dictionary *@var{dict}, const char *@var{name}, int @var{width})
2080 @deftypefunx {struct variable *} dict_create_var_assert (struct dictionary *@var{dict}, const char *@var{name}, int @var{width})
2081 Creates a new variable with the given @var{name} and @var{width}, as
2082 if through a call to @code{var_create} with those arguments
2083 (@pxref{var_create}), appends the new variable to @var{dict}'s array
2084 of variables, and returns the new variable.
2085 @end deftypefun
2086
2087 @deftypefun {struct variable *} dict_clone_var (struct dictionary *@var{dict}, const struct variable *@var{old_var})
2088 @deftypefunx {struct variable *} dict_clone_var_assert (struct dictionary *@var{dict}, const struct variable *@var{old_var})
2089 Creates a new variable as a clone of @var{var}, inserts the new
2090 variable into @var{dict}, and returns the new variable.  Other
2091 properties of the new variable are copied from @var{old_var}, except
2092 for those not copied by @code{var_clone} (@pxref{var_clone}).
2093
2094 @var{var} does not need to be a member of any dictionary.
2095 @end deftypefun
2096
2097 @deftypefun {struct variable *} dict_clone_var_as (struct dictionary *@var{dict}, const struct variable *@var{old_var}, const char *@var{name})
2098 @deftypefunx {struct variable *} dict_clone_var_as_assert (struct dictionary *@var{dict}, const struct variable *@var{old_var}, const char *@var{name})
2099 These functions are similar to @code{dict_clone_var} and
2100 @code{dict_clone_var_assert}, respectively, except that the new
2101 variable is named @var{name} instead of keeping @var{old_var}'s name.
2102 @end deftypefun
2103
2104 @node Dictionary Deleting Variables
2105 @subsection Deleting Variables
2106
2107 These functions remove variables from a dictionary's array of
2108 variables.  They also destroy the removed variables and free their
2109 associated storage.
2110
2111 Deleting a variable to which there might be external pointers is a bad
2112 idea.  In particular, deleting variables from the active dataset
2113 dictionary is a risky proposition, because transformations can retain
2114 references to arbitrary variables.  Therefore, no variable should be
2115 deleted from the active dataset dictionary when any transformations are
2116 active, because those transformations might reference the variable to
2117 be deleted.  The safest time to delete a variable is just after a
2118 procedure has been executed, as done by @cmd{DELETE VARIABLES}.
2119
2120 Deleting a variable automatically removes references to that variable
2121 from elsewhere in the dictionary as a weighting variable, filter
2122 variable, @cmd{SPLIT FILE} variable, or member of a vector.
2123
2124 No functions are provided for removing a variable from a dictionary
2125 without destroying that variable.  As with insertion of an existing
2126 variable, there is no reason that this could not be implemented, but
2127 so far there has been no need.
2128
2129 @deftypefun void dict_delete_var (struct dictionary *@var{dict}, struct variable *@var{var})
2130 Deletes @var{var} from @var{dict}, of which it must be a member.
2131 @end deftypefun
2132
2133 @deftypefun void dict_delete_vars (struct dictionary *@var{dict}, struct variable *const *@var{vars}, size_t @var{count})
2134 Deletes the @var{count} variables in array @var{vars} from @var{dict}.
2135 All of the variables in @var{vars} must be members of @var{dict}.  No
2136 variable may be included in @var{vars} more than once.
2137 @end deftypefun
2138
2139 @deftypefun void dict_delete_consecutive_vars (struct dictionary *@var{dict}, size_t @var{idx}, size_t @var{count})
2140 Deletes the variables in sequential positions
2141 @var{idx}@dots{}@var{idx} + @var{count} (exclusive) from @var{dict},
2142 which must contain at least @var{idx} + @var{count} variables.
2143 @end deftypefun
2144
2145 @deftypefun void dict_delete_scratch_vars (struct dictionary *@var{dict})
2146 Deletes all scratch variables from @var{dict}.
2147 @end deftypefun
2148
2149 @node Dictionary Reordering Variables
2150 @subsection Changing Variable Order
2151
2152 The variables in a dictionary are stored in an array.  These functions
2153 change the order of a dictionary's array of variables without changing
2154 which variables are in the dictionary.
2155
2156 @anchor{dict_reorder_var}
2157 @deftypefun void dict_reorder_var (struct dictionary *@var{dict}, struct variable *@var{var}, size_t @var{new_index})
2158 Moves @var{var}, which must be in @var{dict}, so that it is at
2159 position @var{new_index} in @var{dict}'s array of variables.  Other
2160 variables in @var{dict}, if any, retain their relative positions.
2161 @var{new_index} must be less than the number of variables in
2162 @var{dict}.
2163 @end deftypefun
2164
2165 @deftypefun void dict_reorder_vars (struct dictionary *@var{dict}, struct variable *const *@var{new_order}, size_t @var{count})
2166 Moves the @var{count} variables in @var{new_order} to the beginning of
2167 @var{dict}'s array of variables in the specified order.  Other
2168 variables in @var{dict}, if any, retain their relative positions.
2169
2170 All of the variables in @var{new_order} must be in @var{dict}.  No
2171 duplicates are allowed within @var{new_order}, which means that
2172 @var{count} must be no greater than the number of variables in
2173 @var{dict}.
2174 @end deftypefun
2175
2176 @node Dictionary Renaming Variables
2177 @subsection Renaming Variables
2178
2179 These functions change the names of variables within a dictionary.
2180 The @func{var_set_name} function (@pxref{var_set_name}) cannot be
2181 applied directly to a variable that is in a dictionary, because
2182 @struct{dictionary} contains an index by name that @func{var_set_name}
2183 would not update.  The following functions take care to update the
2184 index as well.  They also ensure that variable renaming does not cause
2185 a dictionary to contain a duplicate variable name.
2186
2187 @deftypefun void dict_rename_var (struct dictionary *@var{dict}, struct variable *@var{var}, const char *@var{new_name})
2188 Changes the name of @var{var}, which must be in @var{dict}, to
2189 @var{new_name}.  A variable named @var{new_name} must not already be
2190 in @var{dict}, unless @var{new_name} is the same as @var{var}'s
2191 current name.
2192 @end deftypefun
2193
2194 @deftypefun bool dict_rename_vars (struct dictionary *@var{dicT}, struct variable **@var{vars}, char **@var{new_names}, size_t @var{count}, char **@var{err_name})
2195 Renames each of the @var{count} variables in @var{vars} to the name in
2196 the corresponding position of @var{new_names}.  If the renaming would
2197 result in a duplicate variable name, returns false and stores one of
2198 the names that would be be duplicated into @code{*@var{err_name}}, if
2199 @var{err_name} is non-null.  Otherwise, the renaming is successful,
2200 and true is returned.
2201 @end deftypefun
2202
2203 @node Dictionary Weight Variable
2204 @subsection Weight Variable
2205
2206 A data set's cases may optionally be weighted by the value of a
2207 numeric variable.  @xref{WEIGHT,,,pspp, PSPP Users Guide}, for a user
2208 view of weight variables.
2209
2210 The weight variable is written to and read from system and portable
2211 files.
2212
2213 The most commonly useful function related to weighting is a
2214 convenience function to retrieve a weighting value from a case.
2215
2216 @deftypefun double dict_get_case_weight (const struct dictionary *@var{dict}, const struct ccase *@var{case}, bool *@var{warn_on_invalid})
2217 Retrieves and returns the value of the weighting variable specified by
2218 @var{dict} from @var{case}.  Returns 1.0 if @var{dict} has no
2219 weighting variable.
2220
2221 Returns 0.0 if @var{c}'s weight value is user- or system-missing,
2222 zero, or negative.  In such a case, if @var{warn_on_invalid} is
2223 non-null and @code{*@var{warn_on_invalid}} is true,
2224 @func{dict_get_case_weight} also issues an error message and sets
2225 @code{*@var{warn_on_invalid}} to false.  To disable error reporting,
2226 pass a null pointer or a pointer to false as @var{warn_on_invalid} or
2227 use a @func{msg_disable}/@func{msg_enable} pair.
2228 @end deftypefun
2229
2230 The dictionary also has a pair of functions for getting and setting
2231 the weight variable.
2232
2233 @deftypefun {struct variable *} dict_get_weight (const struct dictionary *@var{dict})
2234 Returns @var{dict}'s current weighting variable, or a null pointer if
2235 the dictionary does not have a weighting variable.
2236 @end deftypefun
2237
2238 @deftypefun void dict_set_weight (struct dictionary *@var{dict}, struct variable *@var{var})
2239 Sets @var{dict}'s weighting variable to @var{var}.  If @var{var} is
2240 non-null, it must be a numeric variable in @var{dict}.  If @var{var}
2241 is null, then @var{dict}'s weighting variable, if any, is cleared.
2242 @end deftypefun
2243
2244 @node Dictionary Filter Variable
2245 @subsection Filter Variable
2246
2247 When the active dataset is read by a procedure, cases can be excluded
2248 from analysis based on the values of a @dfn{filter variable}.
2249 @xref{FILTER,,,pspp, PSPP Users Guide}, for a user view of filtering.
2250
2251 These functions store and retrieve the filter variable.  They are
2252 rarely useful, because the data analysis framework automatically
2253 excludes from analysis the cases that should be filtered.
2254
2255 @deftypefun {struct variable *} dict_get_filter (const struct dictionary *@var{dict})
2256 Returns @var{dict}'s current filter variable, or a null pointer if the
2257 dictionary does not have a filter variable.
2258 @end deftypefun
2259
2260 @deftypefun void dict_set_filter (struct dictionary *@var{dict}, struct variable *@var{var})
2261 Sets @var{dict}'s filter variable to @var{var}.  If @var{var} is
2262 non-null, it must be a numeric variable in @var{dict}.  If @var{var}
2263 is null, then @var{dict}'s filter variable, if any, is cleared.
2264 @end deftypefun
2265
2266 @node Dictionary Case Limit
2267 @subsection Case Limit
2268
2269 The limit on cases analyzed by a procedure, set by the @cmd{N OF
2270 CASES} command (@pxref{N OF CASES,,,pspp, PSPP Users Guide}), is
2271 stored as part of the dictionary.  The dictionary does not, on the
2272 other hand, play any role in enforcing the case limit (a job done by
2273 data analysis framework code).
2274
2275 A case limit of 0 means that the number of cases is not limited.
2276
2277 These functions are rarely useful, because the data analysis framework
2278 automatically excludes from analysis any cases beyond the limit.
2279
2280 @deftypefun casenumber dict_get_case_limit (const struct dictionary *@var{dict})
2281 Returns the current case limit for @var{dict}.
2282 @end deftypefun
2283
2284 @deftypefun void dict_set_case_limit (struct dictionary *@var{dict}, casenumber @var{limit})
2285 Sets @var{dict}'s case limit to @var{limit}.
2286 @end deftypefun
2287
2288 @node Dictionary Split Variables
2289 @subsection Split Variables
2290
2291 The user may use the @cmd{SPLIT FILE} command (@pxref{SPLIT
2292 FILE,,,pspp, PSPP Users Guide}) to select a set of variables on which
2293 to split the active dataset into groups of cases to be analyzed
2294 independently in each statistical procedure.  The set of split
2295 variables is stored as part of the dictionary, although the effect on
2296 data analysis is implemented by each individual statistical procedure.
2297
2298 Split variables may be numeric or short or long string variables.
2299
2300 The most useful functions for split variables are those to retrieve
2301 them.  Even these functions are rarely useful directly: for the
2302 purpose of breaking cases into groups based on the values of the split
2303 variables, it is usually easier to use
2304 @func{casegrouper_create_splits}.
2305
2306 @deftypefun {const struct variable *const *} dict_get_split_vars (const struct dictionary *@var{dict})
2307 Returns a pointer to an array of pointers to split variables.  If and
2308 only if there are no split variables, returns a null pointer.  The
2309 caller must not modify or free the returned array.
2310 @end deftypefun
2311
2312 @deftypefun size_t dict_get_split_cnt (const struct dictionary *@var{dict})
2313 Returns the number of split variables.
2314 @end deftypefun
2315
2316 The following functions are also available for working with split
2317 variables.
2318
2319 @deftypefun void dict_set_split_vars (struct dictionary *@var{dict}, struct variable *const *@var{vars}, size_t @var{cnt})
2320 Sets @var{dict}'s split variables to the @var{cnt} variables in
2321 @var{vars}.  If @var{cnt} is 0, then @var{dict} will not have any
2322 split variables.  The caller retains ownership of @var{vars}.
2323 @end deftypefun
2324
2325 @deftypefun void dict_unset_split_var (struct dictionary *@var{dict}, struct variable *@var{var})
2326 Removes @var{var}, which must be a variable in @var{dict}, from
2327 @var{dict}'s split of split variables.
2328 @end deftypefun
2329
2330 @node Dictionary File Label
2331 @subsection File Label
2332
2333 A dictionary may optionally have an associated string that describes
2334 its contents, called its file label.  The user may set the file label
2335 with the @cmd{FILE LABEL} command (@pxref{FILE LABEL,,,pspp, PSPP
2336 Users Guide}).
2337
2338 These functions set and retrieve the file label.
2339
2340 @deftypefun {const char *} dict_get_label (const struct dictionary *@var{dict})
2341 Returns @var{dict}'s file label.  If @var{dict} does not have a label,
2342 returns a null pointer.
2343 @end deftypefun
2344
2345 @deftypefun void dict_set_label (struct dictionary *@var{dict}, const char *@var{label})
2346 Sets @var{dict}'s label to @var{label}.  If @var{label} is non-null,
2347 then its content, truncated to at most 60 bytes, becomes the new file
2348 label.  If @var{label} is null, then @var{dict}'s label is removed.
2349
2350 The caller retains ownership of @var{label}.
2351 @end deftypefun
2352
2353 @node Dictionary Documents
2354 @subsection Documents
2355
2356 A dictionary may include an arbitrary number of lines of explanatory
2357 text, called the dictionary's documents.  For compatibility, document
2358 lines have a fixed width, and lines that are not exactly this width
2359 are truncated or padded with spaces as necessary to bring them to the
2360 correct width.
2361
2362 PSPP users can use the @cmd{DOCUMENT} (@pxref{DOCUMENT,,,pspp, PSPP
2363 Users Guide}), @cmd{ADD DOCUMENT} (@pxref{ADD DOCUMENT,,,pspp, PSPP
2364 Users Guide}), and @cmd{DROP DOCUMENTS} (@pxref{DROP DOCUMENTS,,,pspp,
2365 PSPP Users Guide}) commands to manipulate documents.
2366
2367 @deftypefn Macro int DOC_LINE_LENGTH
2368 The fixed length of a document line, in bytes, defined to 80.
2369 @end deftypefn
2370
2371 The following functions work with whole sets of documents.  They
2372 accept or return sets of documents formatted as null-terminated
2373 strings that are an exact multiple of @code{DOC_LINE_LENGTH}
2374 bytes in length.
2375
2376 @deftypefun {const char *} dict_get_documents (const struct dictionary *@var{dict})
2377 Returns the documents in @var{dict}, or a null pointer if @var{dict}
2378 has no documents.
2379 @end deftypefun
2380
2381 @deftypefun void dict_set_documents (struct dictionary *@var{dict}, const char *@var{new_documents})
2382 Sets @var{dict}'s documents to @var{new_documents}.  If
2383 @var{new_documents} is a null pointer or an empty string, then
2384 @var{dict}'s documents are cleared.  The caller retains ownership of
2385 @var{new_documents}.
2386 @end deftypefun
2387
2388 @deftypefun void dict_clear_documents (struct dictionary *@var{dict})
2389 Clears the documents from @var{dict}.
2390 @end deftypefun
2391
2392 The following functions work with individual lines in a dictionary's
2393 set of documents.
2394
2395 @deftypefun void dict_add_document_line (struct dictionary *@var{dict}, const char *@var{content})
2396 Appends @var{content} to the documents in @var{dict}.  The text in
2397 @var{content} will be truncated or padded with spaces as necessary to
2398 make it exactly @code{DOC_LINE_LENGTH} bytes long.  The caller retains
2399 ownership of @var{content}.
2400
2401 If @var{content} is over @code{DOC_LINE_LENGTH}, this function also
2402 issues a warning using @func{msg}.  To suppress the warning, enclose a
2403 call to one of this function in a @func{msg_disable}/@func{msg_enable}
2404 pair.
2405 @end deftypefun
2406
2407 @deftypefun size_t dict_get_document_line_cnt (const struct dictionary *@var{dict})
2408 Returns the number of line of documents in @var{dict}.  If the
2409 dictionary contains no documents, returns 0.
2410 @end deftypefun
2411
2412 @deftypefun void dict_get_document_line (const struct dictionary *@var{dict}, size_t @var{idx}, struct string *@var{content})
2413 Replaces the text in @var{content} (which must already have been
2414 initialized by the caller) by the document line in @var{dict} numbered
2415 @var{idx}, which must be less than the number of lines of documents in
2416 @var{dict}.  Any trailing white space in the document line is trimmed,
2417 so that @var{content} will have a length between 0 and
2418 @code{DOC_LINE_LENGTH}.
2419 @end deftypefun
2420
2421 @node Coding Conventions
2422 @section Coding Conventions
2423
2424 Every @file{.c} file should have @samp{#include <config.h>} as its
2425 first non-comment line.  No @file{.h} file should include
2426 @file{config.h}.
2427
2428 This section needs to be finished.
2429
2430 @node Cases
2431 @section Cases
2432
2433 This section needs to be written.
2434
2435 @node Data Sets
2436 @section Data Sets
2437
2438 This section needs to be written.
2439
2440 @node Pools
2441 @section Pools
2442
2443 This section needs to be written.
2444
2445 @c  LocalWords:  bool