2.1.1 Numeric Values

A value known to be numeric at compile time is represented as a double. PSPP provides three values of double for special purposes, defined in data/val-type.h:

Macro: double SYSMIS ¶

The system-missing value, used to represent a datum whose true value is unknown, such as a survey question that was not answered by the respondent, or undefined, such as the result of division by zero. PSPP propagates the system-missing value through calculations and compensates for missing values in statistical analyses. See Missing Observations in PSPP Users Guide, for a PSPP user’s view of missing values.

PSPP currently defines SYSMIS as -DBL_MAX, that is, the greatest finite negative value of double. It is best not to depend on this definition, because PSPP may transition to using an IEEE NaN (not a number) instead at some point in the future.

Macro: double LOWEST ¶

Macro: double HIGHEST ¶

The greatest finite negative (except for SYSMIS) and positive values of double, respectively. These values do not ordinarily appear in user data files. Instead, they are used to implement endpoints of open-ended ranges that are occasionally permitted in PSPP syntax, e.g. 5 THRU HI as a range of missing values (see MISSING VALUES in PSPP Users Guide).

2.1.2 String Values

A value known at compile time to have string type is represented as an array of char. String values do not necessarily represent readable text strings and may contain arbitrary 8-bit data, including null bytes, control codes, and bytes with the high bit set. Thus, string values are not null-terminated strings, but rather opaque arrays of bytes.

SYSMIS, LOWEST, and HIGHEST have no equivalents as string values. Usually, PSPP fills an unknown or undefined string values with spaces, but PSPP does not treat such a string as a special case when it processes it later.

MAX_STRING, the maximum length of a string value, is defined in data/val-type.h.

2.1.3 Runtime Typed Values

When a value’s type is only known at runtime, it is often represented as a union value, defined in data/value.h. A union value does not identify the type or width of the data it contains. Code that works with union valuess must therefore have external knowledge of its content, often through the type and width of a struct variable (see Variables).

union value has one member that clients are permitted to access directly, a double named ‘f’ that stores the content of a numeric union value. It has other members that store the content of string union value, but client code should use accessor functions instead of referring to these directly.

PSPP provides some functions for working with union values. The most useful are described below. To use these functions, recall that a numeric value has a width of 0.

Function: void value_init (union value *value, int width) ¶

Initializes value as a value of the given width. After initialization, the data in value are indeterminate; the caller is responsible for storing initial data in it.

Function: void value_destroy (union value *value, int width) ¶

Frees auxiliary storage associated with value, which must have the given width.

Function: bool value_needs_init (int width) ¶

For some widths, value_init and value_destroy do not actually do anything, because no additional storage is needed beyond the size of union value. This function returns true if width is such a width, which case there is no actual need to call those functions. This can be a useful optimization if a large number of union values of such a width are to be initialized or destroyed.

This function returns false if value_init and value_destroy are actually required for the given width.

Function: void value_copy (union value *dst, const union value *src, int width) ¶

Copies the contents of union value src to dst. Both dst and src must have been initialized with the specified width.

Function: void value_set_missing (union value *value, int width) ¶

Sets value to SYSMIS if it is numeric or to all spaces if it is alphanumeric, according to width. value must have been initialized with the specified width.

Function: bool value_is_resizable (const union value *value, int old_width, int new_width) ¶

Determines whether value, which must have been initialized with the specified old_width, may be resized to new_width. Resizing is possible if the following criteria are met. First, old_width and new_width must be both numeric or both string widths. Second, if new_width is a short string width and less than old_width, resizing is allowed only if bytes new_width through old_width in value contain only spaces.

These rules are part of those used by mv_is_resizable and val_labs_can_set_width.

Function: void value_resize (union value *value, int old_width, int new_width) ¶

Resizes value from old_width to new_width, which must be allowed by the rules stated above. value must have been initialized with the specified old_width before calling this function. After resizing, value has width new_width.

If new_width is greater than old_width, value will be padded on the right with spaces to the new width. If new_width is less than old_width, the rightmost bytes of value are truncated.

Function: bool value_equal (const union value *a, const union value *b, int width) ¶

Compares of a and b, which must both have width width. Returns true if their contents are the same, false if they differ.

Function: int value_compare_3way (const union value *a, const union value *b, int width) ¶

Compares of a and b, which must both have width width. Returns -1 if a is less than b, 0 if they are equal, or 1 if a is greater than b.

Numeric values are compared numerically, with SYSMIS comparing less than any real number. String values are compared lexicographically byte-by-byte.

Function: size_t value_hash (const union value *value, int width, unsigned int basis) ¶

Computes and returns a hash of value, which must have the specified width. The value in basis is folded into the hash.

2.2.1 Constructing and Verifying Formats

These functions construct struct fmt_specs and verify that they are valid.

Function: struct fmt_spec fmt_for_input (enum fmt_type type, int w, int d) ¶

Function: struct fmt_spec fmt_for_output (enum fmt_type type, int w, int d) ¶

Constructs a struct fmt_spec with the given type, w, and d, asserts that the result is a valid input (or output) format, and returns it.

Function: struct fmt_spec fmt_for_output_from_input (const struct fmt_spec *input) ¶

Given input, which must be a valid input format, returns the equivalent output format. See Input and Output Formats in PSPP Users Guide, for the rules for converting input formats into output formats.

Function: struct fmt_spec fmt_default_for_width (int width) ¶

Returns the default output format for a variable of the given width. For a numeric variable, this is F8.2 format; for a string variable, it is the A format of the given width.

The following functions check whether a struct fmt_spec is valid for various uses and return true if so, false otherwise. When any of them returns false, it also outputs an explanatory error message using msg. To suppress error output, enclose a call to one of these functions by a msg_disable/msg_enable pair.

Function: bool fmt_check (const struct fmt_spec *format, bool for_input) ¶

Function: bool fmt_check_input (const struct fmt_spec *format) ¶

Function: bool fmt_check_output (const struct fmt_spec *format) ¶

Checks whether format is a valid input format (for fmt_check_input, or fmt_check if for_input) or output format (for fmt_check_output, or fmt_check if not for_input).

Function: bool fmt_check_type_compat (const struct fmt_spec *format, enum val_type type) ¶

Checks whether format matches the value type type, that is, if type is VAL_NUMERIC and format is a numeric format or type is VAL_STRING and format is a string format.

Function: bool fmt_check_width_compat (const struct fmt_spec *format, int width) ¶

Checks whether format may be used as an output format for a value of the given width.

fmt_var_width, described in the following section, can be also be used to determine the value width needed by a format.

2.2.2 Format Utility Functions

These functions work with struct fmt_specs.

Function: int fmt_var_width (const struct fmt_spec *format) ¶

Returns the width for values associated with format. If format is a numeric format, the width is 0; if format is an A format, then the width format->w; otherwise, format is an AHEX format and its width is format->w / 2.

Function: char *fmt_to_string (const struct fmt_spec *format, char s[FMT_STRING_LEN_MAX + 1]) ¶

Converts format to a human-readable format specifier in s and returns s. format need not be a valid input or output format specifier, e.g. it is allowed to have an excess width or decimal places. In particular, if format has decimals, they are included in the output string, even if format’s type does not allow decimals, to allow accurately presenting incorrect formats to the user.

Function: bool fmt_equal (const struct fmt_spec *a, const struct fmt_spec *b) ¶

Compares a and b memberwise and returns true if they are identical, false otherwise. format need not be a valid input or output format specifier.

Function: void fmt_resize (struct fmt_spec *fmt, int width) ¶

Sets the width of fmt to a valid format for a union value of size width.

2.2.3 Obtaining Properties of Format Types

These functions work with enum fmt_types instead of the higher-level struct fmt_specs. Their primary purpose is to report properties of each possible format type, which in turn allows clients to abstract away many of the details of the very heterogeneous requirements of each format type.

The first group of functions works with format type names.

Function: const char *fmt_name (enum fmt_type type) ¶

Returns the name for the given type, e.g. "COMMA" for FMT_COMMA.

Function: bool fmt_from_name (const char *name, enum fmt_type *type) ¶

Tries to find the enum fmt_type associated with name. If successful, sets *type to the type and returns true; otherwise, returns false without modifying *type.

The functions below query basic limits on width and decimal places for each kind of format.

Function: bool fmt_takes_decimals (enum fmt_type type) ¶

Returns true if a format of the given type is allowed to have a nonzero number of decimal places (the d member of struct fmt_spec), false if not.

Function: int fmt_min_input_width (enum fmt_type type) ¶

Function: int fmt_max_input_width (enum fmt_type type) ¶

Function: int fmt_min_output_width (enum fmt_type type) ¶

Function: int fmt_max_output_width (enum fmt_type type) ¶

Returns the minimum or maximum width (the w member of struct fmt_spec) allowed for an input or output format of the specified type.

Function: int fmt_max_input_decimals (enum fmt_type type, int width) ¶

Function: int fmt_max_output_decimals (enum fmt_type type, int width) ¶

Returns the maximum number of decimal places allowed for an input or output format, respectively, of the given type and width. Returns 0 if the specified type does not allow any decimal places or if width is too narrow to allow decimal places.

Function: int fmt_step_width (enum fmt_type type) ¶

Returns the “width step” for a struct fmt_spec of the given type. A struct fmt_spec’s width must be a multiple of its type’s width step. Most format types have a width step of 1, so that their formats’ widths may be any integer within the valid range, but hexadecimal numeric formats and AHEX string formats have a width step of 2.

These functions allow clients to broadly determine how each kind of input or output format behaves.

Function: bool fmt_is_string (enum fmt_type type) ¶

Function: bool fmt_is_numeric (enum fmt_type type) ¶

Returns true if type is a format for numeric or string values, respectively, false otherwise.

Function: enum fmt_category fmt_get_category (enum fmt_type type) ¶

Returns the category within which type falls.

Enumeration: enum fmt_category ¶

A group of format types. Format type categories correspond to the input and output categories described in the PSPP user documentation (see Input and Output Formats in PSPP Users Guide).

Each format is in exactly one category. The categories have bitwise disjoint values to make it easy to test whether a format type is in one of multiple categories, e.g.

if (fmt_get_category (type) & (FMT_CAT_DATE | FMT_CAT_TIME))
  {
    /* …type is a date or time format… */
  }

The format categories are:

FMT_CAT_BASIC

Basic numeric formats.

FMT_CAT_CUSTOM

Custom currency formats.

FMT_CAT_LEGACY

Legacy numeric formats.

FMT_CAT_BINARY

Binary formats.

FMT_CAT_HEXADECIMAL

Hexadecimal formats.

FMT_CAT_DATE

Date formats.

FMT_CAT_TIME

Time formats.

FMT_CAT_DATE_COMPONENT

Date component formats.

FMT_CAT_STRING

String formats.

The PSPP input and output routines use the following pair of functions to convert enum fmt_types to and from the separate set of codes used in system and portable files:

Function: int fmt_to_io (enum fmt_type type) ¶

Returns the format code used in system and portable files that corresponds to type.

Function: bool fmt_from_io (int io, enum fmt_type *type) ¶

Converts io, a format code used in system and portable files, into a enum fmt_type in *type. Returns true if successful, false if io is not valid.

These functions reflect the relationship between input and output formats.

Function: enum fmt_type fmt_input_to_output (enum fmt_type type) ¶

Returns the output format type that is used by default by DATA LIST and other input procedures when type is specified as an input format. The conversion from input format to output format is more complicated than simply changing the format. See fmt_for_output_from_input, for a function that performs the entire conversion.

Function: bool fmt_usable_for_input (enum fmt_type type) ¶

Returns true if type may be used as an input format type, false otherwise. The custom currency formats, in particular, may be used for output but not for input.

All format types are valid for output.

The final group of format type property functions obtain human-readable templates that illustrate the formats graphically.

Function: const char *fmt_date_template (enum fmt_type type) ¶

Returns a formatting template for type, which must be a date or time format type. These formats are used by data_in and data_out to guide parsing and formatting date and time data.

Function: char *fmt_dollar_template (const struct fmt_spec *format) ¶

Returns a string of the form $#,###.## according to format, which must be of type FMT_DOLLAR. The caller must free the string with free.

2.2.4 Numeric Formatting Styles

Each of the basic numeric formats (F, E, COMMA, DOT, DOLLAR, PCT) and custom currency formats (CCA, CCB, CCC, CCD, CCE) has an associated numeric formatting style, represented by struct fmt_number_style. Input and output conversion of formats that have numeric styles is determined mainly by the style, although the formatting rules have special cases that are not represented within the style.

Structure: struct fmt_number_style ¶

A structure type with the following members:

struct substring neg_prefix

struct substring prefix

struct substring suffix

struct substring neg_suffix

A set of strings used a prefix to negative numbers, a prefix to every number, a suffix to every number, and a suffix to negative numbers, respectively. Each of these strings is no more than FMT_STYLE_AFFIX_MAX bytes (currently 16) bytes in length. These strings must be freed with ss_dealloc when no longer needed.

decimal

The character used as a decimal point. It must be either ‘.’ or ‘,’.

grouping

The character used for grouping digits to the left of the decimal point. It may be ‘.’ or ‘,’, in which case it must not be equal to decimal, or it may be set to 0 to disable grouping.

The following functions are provided for working with numeric formatting styles.

Function: void fmt_number_style_init (struct fmt_number_style *style) ¶

Initialises a struct fmt_number_style with all of the prefixes and suffixes set to the empty string, ‘.’ as the decimal point character, and grouping disables.

Function: void fmt_number_style_destroy (struct fmt_number_style *style) ¶

Destroys style, freeing its storage.

Function: struct fmt_number_style *fmt_create (void) ¶

A function which creates an array of all the styles used by pspp, and calls fmt_number_style_init on each of them.

Function: void fmt_done (struct fmt_number_style *styles) ¶

A wrapper function which takes an array of struct fmt_number_style, calls fmt_number_style_destroy on each of them, and then frees the array.

Function: int fmt_affix_width (const struct fmt_number_style *style) ¶

Returns the total length of style’s prefix and suffix.

Function: int fmt_neg_affix_width (const struct fmt_number_style *style) ¶

Returns the total length of style’s neg_prefix and neg_suffix.

PSPP maintains a global set of number styles for each of the basic numeric formats and custom currency formats. The following functions work with these global styles:

Function: const struct fmt_number_style * fmt_get_style (enum fmt_type type) ¶

Returns the numeric style for the given format type.

Function: const char * fmt_name (enum fmt_type type) ¶

Returns the name of the given format type.

2.2.5 Formatted Data Input and Output

These functions provide the ability to convert data fields into union values and vice versa.

Function: bool data_in (struct substring input, const char *encoding, enum fmt_type type, int implied_decimals, int first_column, const struct dictionary *dict, union value *output, int width) ¶

Parses input as a field containing data in the given format type. The resulting value is stored in output, which the caller must have initialized with the given width. For consistency, width must be 0 if type is a numeric format type and greater than 0 if type is a string format type. encoding should be set to indicate the character encoding of input. dict must be a pointer to the dictionary with which output is associated.

If input is the empty string (with length 0), output is set to the value set on SET BLANKS (see SET BLANKS in PSPP Users Guide) for a numeric value, or to all spaces for a string value. This applies regardless of the usual parsing requirements for type.

If implied_decimals is greater than zero, then the numeric result is shifted right by implied_decimals decimal places if input does not contain a decimal point character or an exponent. Only certain numeric format types support implied decimal places; for string formats and other numeric formats, implied_decimals has no effect. DATA LIST FIXED is the primary user of this feature (see DATA LIST FIXED in PSPP Users Guide). Other callers should generally specify 0 for implied_decimals, to disable this feature.

When input contains invalid input data, data_in outputs a message using msg. If first_column is nonzero, it is included in any such error message as the 1-based column number of the start of the field. The last column in the field is calculated as first_column + input - 1. To suppress error output, enclose the call to data_in by calls to msg_disable and msg_enable.

This function returns true on success, false if a message was output (even if suppressed). Overflow and underflow provoke warnings but are not propagated to the caller as errors.

This function is declared in data/data-in.h.

Function: char * data_out (const union value *input, const struct fmt_spec *format) ¶

Function: char * data_out_legacy (const union value *input, const char *encoding, const struct fmt_spec *format) ¶

Converts the data pointed to by input into a string value, which will be encoded in UTF-8, according to output format specifier format. Format must be a valid output format. The width of input is inferred from format using an algorithm equivalent to fmt_var_width.

When input contains data that cannot be represented in the given format, data_out may output a message using msg, although the current implementation does not consistently do so. To suppress error output, enclose the call to data_out by calls to msg_disable and msg_enable.

This function is declared in data/data-out.h.

2.3.1 Testing for Missing Values

The most often useful functions for missing values are those for testing whether a given value is missing, described here. However, using one of the corresponding missing value testing functions for variables can be even easier (see Variable Missing Values).

Function: bool mv_is_value_missing (const struct missing_values *mv, const union value *value, enum mv_class class) ¶

Function: bool mv_is_num_missing (const struct missing_values *mv, double value, enum mv_class class) ¶

Function: bool mv_is_str_missing (const struct missing_values *mv, const char value[], enum mv_class class) ¶

Tests whether value is in one of the categories of missing values given by class. Returns true if so, false otherwise.

mv determines the width of value and provides the set of user-missing values to test.

The only difference among these functions in the form in which value is provided, so you may use whichever function is most convenient.

The class argument determines the exact kinds of missing values that the functions test for:

Enumeration: enum mv_class ¶

MV_USER

Returns true if value is in the set of user-missing values given by mv.

MV_SYSTEM

Returns true if value is system-missing. (If mv represents a set of string values, then value is never system-missing.)

MV_ANY

MV_USER | MV_SYSTEM

Returns true if value is user-missing or system-missing.

MV_NONE

Always returns false, that is, value is never considered missing.

2.3.2 Creation and Destruction

These functions create and destroy struct missing_values objects.

Function: void mv_init (struct missing_values *mv, int width) ¶

Initializes mv as a set of user-missing values. The set is initially empty. Any values added to it must have the specified width.

Function: void mv_destroy (struct missing_values *mv) ¶

Destroys mv, which must not be referred to again.

Function: void mv_copy (struct missing_values *mv, const struct missing_values *old) ¶

Initializes mv as a copy of the existing set of user-missing values old.

Function: void mv_clear (struct missing_values *mv) ¶

Empties the user-missing value set mv, retaining its existing width.

2.3.3 Changing User-Missing Value Set Width

A few PSPP language constructs copy sets of user-missing values from one variable to another. When the source and target variables have the same width, this is simple. But when the target variable’s width might be different from the source variable’s, it takes a little more work. The functions described here can help.

In fact, it is usually unnecessary to call these functions directly. Most of the time var_set_missing_values, which uses mv_resize internally to resize the new set of missing values to the required width, may be used instead. See var_set_missing_values, for more information.

Function: bool mv_is_resizable (const struct missing_values *mv, int new_width) ¶

Tests whether mv’s width may be changed to new_width using mv_resize. Returns true if it is allowed, false otherwise.

If mv contains any missing values, then it may be resized only if each missing value may be resized, as determined by value_is_resizable (see value_is_resizable).

Function: void mv_resize (struct missing_values *mv, int width) ¶

Changes mv’s width to width. mv and width must satisfy the constraints explained above.

When a string missing value set’s width is increased, each user-missing value is padded on the right with spaces to the new width.

2.3.4 Inspecting User-Missing Value Sets

These functions inspect the properties and contents of struct missing_values objects.

The first set of functions inspects the discrete values that sets of user-missing values may contain:

Function: bool mv_is_empty (const struct missing_values *mv) ¶

Returns true if mv contains no user-missing values, false if it contains at least one user-missing value (either a discrete value or a numeric range).

Function: int mv_get_width (const struct missing_values *mv) ¶

Returns the width of the user-missing values that mv represents.

Function: int mv_n_values (const struct missing_values *mv) ¶

Returns the number of discrete user-missing values included in mv. The return value will be between 0 and 3. For sets of numeric user-missing values that include a range, the return value will be 0 or 1.

Function: bool mv_has_value (const struct missing_values *mv) ¶

Returns true if mv has at least one discrete user-missing values, that is, if mv_n_values would return nonzero for mv.

Function: const union value * mv_get_value (const struct missing_values *mv, int index) ¶

Returns the discrete user-missing value in mv with the given index. The caller must not modify or free the returned value or refer to it after modifying or freeing mv. The index must be less than the number of discrete user-missing values in mv, as reported by mv_n_values.

The second set of functions inspects the single range of values that numeric sets of user-missing values may contain:

Function: bool mv_has_range (const struct missing_values *mv) ¶

Returns true if mv includes a range, false otherwise.

Function: void mv_get_range (const struct missing_values *mv, double *low, double *high) ¶

Stores the low endpoint of mv’s range in *low and the high endpoint of the range in *high. mv must include a range.

2.3.5 Modifying User-Missing Value Sets

These functions modify the contents of struct missing_values objects.

The next set of functions applies to all sets of user-missing values:

Function: bool mv_add_value (struct missing_values *mv, const union value *value) ¶

Function: bool mv_add_str (struct missing_values *mv, const char value[]) ¶

Function: bool mv_add_num (struct missing_values *mv, double value) ¶

Attempts to add the given discrete value to set of user-missing values mv. value must have the same width as mv. Returns true if value was successfully added, false if the set could not accept any more discrete values or if value is not an acceptable user-missing value (see mv_is_acceptable below).

These functions are equivalent, except for the form in which value is provided, so you may use whichever function is most convenient.

Function: void mv_pop_value (struct missing_values *mv, union value *value) ¶

Removes a discrete value from mv (which must contain at least one discrete value) and stores it in value.

Function: bool mv_replace_value (struct missing_values *mv, const union value *value, int index) ¶

Attempts to replace the discrete value with the given index in mv (which must contain at least index + 1 discrete values) by value. Returns true if successful, false if value is not an acceptable user-missing value (see mv_is_acceptable below).

Function: bool mv_is_acceptable (const union value *value, int width) ¶

Returns true if value, which must have the specified width, may be added to a missing value set of the same width, false if it cannot. As described above, all numeric values and string values of width MV_MAX_STRING or less may be added, but string value of greater width may be added only if bytes beyond the first MV_MAX_STRING are all spaces.

The second set of functions applies only to numeric sets of user-missing values:

Function: bool mv_add_range (struct missing_values *mv, double low, double high) ¶

Attempts to add a numeric range covering low…high (inclusive on both ends) to mv, which must be a numeric set of user-missing values. Returns true if the range is successful added, false on failure. Fails if mv already contains a range, or if mv contains more than one discrete value, or if low > high.

Function: void mv_pop_range (struct missing_values *mv, double *low, double *high) ¶

Given mv, which must be a numeric set of user-missing values that contains a range, removes that range from mv and stores its low endpoint in *low and its high endpoint in *high.

2.4.1 Creation and Destruction

These functions create and destroy struct val_labs objects.

Function: struct val_labs * val_labs_create (int width) ¶

Creates and returns an initially empty set of value labels with the given width.

Function: struct val_labs * val_labs_clone (const struct val_labs *val_labs) ¶

Creates and returns a set of value labels whose width and contents are the same as those of var_labs.

Function: void val_labs_clear (struct val_labs *var_labs) ¶

Deletes all value labels from var_labs.

Function: void val_labs_destroy (struct val_labs *var_labs) ¶

Destroys var_labs, which must not be referenced again.

2.4.2 Value Labels Properties

These functions inspect and manipulate basic properties of struct val_labs objects.

Function: size_t val_labs_count (const struct val_labs *val_labs) ¶

Returns the number of value labels in val_labs.

Function: bool val_labs_can_set_width (const struct val_labs *val_labs, int new_width) ¶

Tests whether val_labs’s width may be changed to new_width using val_labs_set_width. Returns true if it is allowed, false otherwise.

A set of value labels may be resized to a given width only if each value in it may be resized to that width, as determined by value_is_resizable (see value_is_resizable).

Function: void val_labs_set_width (struct val_labs *val_labs, int new_width) ¶

Changes the width of val_labs’s values to new_width, which must be a valid new width as determined by val_labs_can_set_width.

2.4.3 Adding and Removing Labels

These functions add and remove value labels from a struct val_labs object.

Function: bool val_labs_add (struct val_labs *val_labs, union value value, const char *label) ¶

Adds label to in var_labs as a label for value, which must have the same width as the set of value labels. Returns true if successful, false if value already has a label.

Function: void val_labs_replace (struct val_labs *val_labs, union value value, const char *label) ¶

Adds label to in var_labs as a label for value, which must have the same width as the set of value labels. If value already has a label in var_labs, it is replaced.

Function: bool val_labs_remove (struct val_labs *val_labs, union value value) ¶

Removes from val_labs any label for value, which must have the same width as the set of value labels. Returns true if a label was removed, false otherwise.

2.4.4 Iterating through Value Labels

These functions allow iteration through the set of value labels represented by a struct val_labs object. They may be used in the context of a for loop:

struct val_labs val_labs;
const struct val_lab *vl;

…

for (vl = val_labs_first (val_labs); vl != NULL;
     vl = val_labs_next (val_labs, vl))
  {
    …do something with vl…
  }

Value labels should not be added or deleted from a struct val_labs as it is undergoing iteration.

Function: const struct val_lab * val_labs_first (const struct val_labs *val_labs) ¶

Returns the first value label in var_labs, if it contains at least one value label, or a null pointer if it does not contain any value labels.

Function: const struct val_lab * val_labs_next (const struct val_labs *val_labs, const struct val_labs_iterator **vl) ¶

Returns the value label in var_labs following vl, if vl is not the last value label in val_labs, or a null pointer if there are no value labels following vl.

Function: const struct val_lab ** val_labs_sorted (const struct val_labs *val_labs) ¶

Allocates and returns an array of pointers to value labels, which are sorted in increasing order by value. The array has val_labs_count (val_labs) elements. The caller is responsible for freeing the array with free (but must not free any of the struct val_lab elements that the array points to).

The iteration functions above work with pointers to struct val_lab which is an opaque data structure that users of struct val_labs must not modify or free directly. The following functions work with objects of this type:

Function: const union value * val_lab_get_value (const struct val_lab *vl) ¶

Returns the value of value label vl. The caller must not modify or free the returned value. (To achieve a similar result, remove the value label with val_labs_remove, then add the new value with val_labs_add.)

The width of the returned value cannot be determined directly from vl. It may be obtained by calling val_labs_get_width on the struct val_labs that vl is in.

Function: const char * val_lab_get_label (const struct val_lab *vl) ¶

Returns the label in vl as a null-terminated string. The caller must not modify or free the returned string. (Use val_labs_replace to change a value label.)

2.5.1 Variable Name

A variable name is a string between 1 and ID_MAX_LEN bytes long that satisfies the rules for PSPP identifiers (see Tokens in PSPP Users Guide). Variable names are mixed-case and treated case-insensitively.

Macro: int ID_MAX_LEN ¶

Maximum length of a variable name, in bytes, currently 64.

Only one commonly useful function relates to variable names:

Function: const char * var_get_name (const struct variable *var) ¶

Returns var’s variable name as a C string.

A few other functions are much more rarely used. Some of these functions are used internally by the dictionary implementation:

Function: void var_set_name (struct variable *var, const char *new_name) ¶

Changes the name of var to new_name, which must be a “plausible” name as defined below.

This function cannot be applied to a variable that is part of a dictionary. Use dict_rename_var instead (see Renaming Variables).

Function: enum dict_class var_get_dict_class (const struct variable *var) ¶

Returns the dictionary class of var’s name (see Dictionary Class).

2.5.2 Variable Type and Width

A variable’s type and width are the type and width of its values (see Values).

Function: enum val_type var_get_type (const struct variable *var) ¶

Returns the type of variable var.

Function: int var_get_width (const struct variable *var) ¶

Returns the width of variable var.

Function: void var_set_width (struct variable *var, int width) ¶

Sets the width of variable var to width. The width of a variable should not normally be changed after the variable is created, so this function is rarely used. This function cannot be applied to a variable that is part of a dictionary.

Function: bool var_is_numeric (const struct variable *var) ¶

Returns true if var is a numeric variable, false otherwise.

Function: bool var_is_alpha (const struct variable *var) ¶

Returns true if var is an alphanumeric (string) variable, false otherwise.

2.5.3 Variable Missing Values

A numeric or short string variable may have a set of user-missing values (see MISSING VALUES in PSPP Users Guide), represented as a struct missing_values (see User-Missing Values).

The most frequent operation on a variable’s missing values is to query whether a value is user- or system-missing:

Function: bool var_is_value_missing (const struct variable *var, const union value *value, enum mv_class class) ¶

Function: bool var_is_num_missing (const struct variable *var, double value, enum mv_class class) ¶

Function: bool var_is_str_missing (const struct variable *var, const char value[], enum mv_class class) ¶

Tests whether value is a missing value of the given class for variable var and returns true if so, false otherwise. var_is_num_missing may only be applied to numeric variables; var_is_str_missing may only be applied to string variables. value must have been initialized with the same width as var.

var_is_type_missing (var, value, class) is equivalent to mv_is_type_missing (var_get_missing_values (var), value, class).

In addition, a few functions are provided to work more directly with a variable’s struct missing_values:

Function: const struct missing_values * var_get_missing_values (const struct variable *var) ¶

Returns the struct missing_values associated with var. The caller must not modify the returned structure. The return value is always non-null.

Function: void var_set_missing_values (struct variable *var, const struct missing_values *miss) ¶

Changes var’s missing values to a copy of miss, or if miss is a null pointer, clears var’s missing values. If miss is non-null, it must have the same width as var or be resizable to var’s width (see mv_resize). The caller retains ownership of miss.

Function: void var_clear_missing_values (struct variable *var) ¶

Clears var’s missing values. Equivalent to var_set_missing_values (var, NULL).

Function: bool var_has_missing_values (const struct variable *var) ¶

Returns true if var has any missing values, false if it has none. Equivalent to mv_is_empty (var_get_missing_values (var)).

2.5.4 Variable Value Labels

A numeric or short string variable may have a set of value labels (see VALUE LABELS in PSPP Users Guide), represented as a struct val_labs (see Value Labels). The most commonly useful functions for value labels return the value label associated with a value:

Function: const char * var_lookup_value_label (const struct variable *var, const union value *value) ¶

Looks for a label for value in var’s set of value labels. value must have the same width as var. Returns the label if one exists, otherwise a null pointer.

Function: void var_append_value_name (const struct variable *var, const union value *value, struct string *str) ¶

Looks for a label for value in var’s set of value labels. value must have the same width as var. If a label exists, it will be appended to the string pointed to by str. Otherwise, it formats value using var’s print format (see Input and Output Formats) and appends the formatted string.

The underlying struct val_labs structure may also be accessed directly using the functions described below.

Function: bool var_has_value_labels (const struct variable *var) ¶

Returns true if var has at least one value label, false otherwise.

Function: const struct val_labs * var_get_value_labels (const struct variable *var) ¶

Returns the struct val_labs associated with var. If var has no value labels, then the return value may or may not be a null pointer.

The variable retains ownership of the returned struct val_labs, which the caller must not attempt to modify.

Function: void var_set_value_labels (struct variable *var, const struct val_labs *val_labs) ¶

Replaces var’s value labels by a copy of val_labs. The caller retains ownership of val_labs. If val_labs is a null pointer, then var’s value labels, if any, are deleted.

Function: void var_clear_value_labels (struct variable *var) ¶

Deletes var’s value labels. Equivalent to var_set_value_labels (var, NULL).

A final group of functions offers shorthands for operations that would otherwise require getting the value labels from a variable, copying them, modifying them, and then setting the modified value labels into the variable (making a second copy):

Function: bool var_add_value_label (struct variable *var, const union value *value, const char *label) ¶

Attempts to add a copy of label as a label for value for the given var. value must have the same width as var. If value already has a label, then the old label is retained. Returns true if a label is added, false if there was an existing label for value. Either way, the caller retains ownership of value and label.

Function: void var_replace_value_label (struct variable *var, const union value *value, const char *label) ¶

Attempts to add a copy of label as a label for value for the given var. value must have the same width as var. If value already has a label, then label replaces the old label. Either way, the caller retains ownership of value and label.

2.5.5 Variable Print and Write Formats

Each variable has an associated pair of output formats, called its print format and write format. See Input and Output Formats in PSPP Users Guide, for an introduction to formats. See Input and Output Formats, for a developer’s description of format representation.

The print format is used to convert a variable’s data values to strings for human-readable output. The write format is used similarly for machine-readable output, primarily by the WRITE transformation (see WRITE in PSPP Users Guide). Most often a variable’s print and write formats are the same.

A newly created variable by default has format F8.2 if it is numeric or an A format with the same width as the variable if it is string. Many creators of variables override these defaults.

Both the print format and write format are output formats. Input formats are not part of struct variable. Instead, input programs and transformations keep track of variable input formats themselves.

The following functions work with variable print and write formats.

Function: const struct fmt_spec * var_get_print_format (const struct variable *var) ¶

Function: const struct fmt_spec * var_get_write_format (const struct variable *var) ¶

Returns var’s print or write format, respectively.

Function: void var_set_print_format (struct variable *var, const struct fmt_spec *format) ¶

Function: void var_set_write_format (struct variable *var, const struct fmt_spec *format) ¶

Function: void var_set_both_formats (struct variable *var, const struct fmt_spec *format) ¶

Sets var’s print format, write format, or both formats, respectively, to a copy of format.

2.5.6 Variable Labels

A variable label is a string that describes a variable. Variable labels may contain spaces and punctuation not allowed in variable names. See VARIABLE LABELS in PSPP Users Guide, for a user-level description of variable labels.

The most commonly useful functions for variable labels are those to retrieve a variable’s label:

Function: const char * var_to_string (const struct variable *var) ¶

Returns var’s variable label, if it has one, otherwise var’s name. In either case the caller must not attempt to modify or free the returned string.

This function is useful for user output.

Function: const char * var_get_label (const struct variable *var) ¶

Returns var’s variable label, if it has one, or a null pointer otherwise.

A few other variable label functions are also provided:

Function: void var_set_label (struct variable *var, const char *label) ¶

Sets var’s variable label to a copy of label, or removes any label from var if label is a null pointer or contains only spaces. Leading and trailing spaces are removed from the variable label and its remaining content is truncated at 255 bytes.

Function: void var_clear_label (struct variable *var) ¶

Removes any variable label from var.

Function: bool var_has_label (const struct variable *var) ¶

Returns true if var has a variable label, false otherwise.

2.5.7 GUI Attributes

These functions and types access and set attributes that are mainly used by graphical user interfaces. Their values are also stored in and retrieved from system files (but not portable files).

The first group of functions relate to the measurement level of numeric data. New variables are assigned a nominal level of measurement by default.

Enumeration: enum measure ¶

Measurement level. Available values are:

MEASURE_NOMINAL

Numeric data values are arbitrary. Arithmetic operations and numerical comparisons of such data are not meaningful.

MEASURE_ORDINAL

Numeric data values indicate progression along a rank order. Arbitrary arithmetic operations such as addition are not meaningful on such data, but inequality comparisons (less, greater, etc.) have straightforward interpretations.

MEASURE_SCALE

Ratios, sums, etc. of numeric data values have meaningful interpretations.

PSPP does not have a separate category for interval data, which would naturally fall between the ordinal and scale measurement levels.

Function: bool measure_is_valid (enum measure measure) ¶

Returns true if measure is a valid level of measurement, that is, if it is one of the enum measure constants listed above, and false otherwise.

Function: enum measure var_get_measure (const struct variable *var) ¶

Function: void var_set_measure (struct variable *var, enum measure measure) ¶

Gets or sets var’s measurement level.

The following set of functions relates to the width of on-screen columns used for displaying variable data in a graphical user interface environment. The unit of measurement is the width of a character. For proportionally spaced fonts, this is based on the average width of a character.

Function: int var_get_display_width (const struct variable *var) ¶

Function: void var_set_display_width (struct variable *var, int display_width) ¶

Gets or sets var’s display width.

Function: int var_default_display_width (int width) ¶

Returns the default display width for a variable with the given width. The default width of a numeric variable is 8. The default width of a string variable is width or 32, whichever is less.

The final group of functions work with the justification of data when it is displayed in on-screen columns. New variables are by default right-justified.

Enumeration: enum alignment ¶

Text justification. Possible values are ALIGN_LEFT, ALIGN_RIGHT, and ALIGN_CENTRE.

Function: bool alignment_is_valid (enum alignment alignment) ¶

Returns true if alignment is a valid alignment, that is, if it is one of the enum alignment constants listed above, and false otherwise.

Function: enum alignment var_get_alignment (const struct variable *var) ¶

Function: void var_set_alignment (struct variable *var, enum alignment alignment) ¶

Gets or sets var’s alignment.

2.5.8 Variable Leave Status

Commonly, most or all data in a case come from an input file, read with a command such as DATA LIST or GET, but data can also be generated with transformations such as COMPUTE. In the latter case the question of a datum’s “initial value” can arise. For example, the value of a piece of generated data can recursively depend on its own value:

COMPUTE X = X + 1.

Another situation where the initial value of a variable arises is when its value is not set at all for some cases, e.g. below, Y is set only for the first 10 cases:

DO IF #CASENUM <= 10.
+ COMPUTE Y = 1.
END IF.

By default, the initial value of a datum in either of these situations is the system-missing value for numeric values and spaces for string values. This means that, above, X would be system-missing and that Y would be 1 for the first 10 cases and system-missing for the remainder.

PSPP also supports retaining the value of a variable from one case to another, using the LEAVE command (see LEAVE in PSPP Users Guide). The initial value of such a variable is 0 if it is numeric and spaces if it is a string. If the command ‘LEAVE X Y’ is appended to the above example, then X would have value 1 in the first case and increase by 1 in every succeeding case, and Y would have value 1 for the first 10 cases and 0 for later cases.

The LEAVE command has no effect on data that comes from an input file or whose values do not depend on a variable’s initial value.

The value of scratch variables (see Scratch Variables in PSPP Users Guide) are always left from one case to another.

The following functions work with a variable’s leave status.

Function: bool var_get_leave (const struct variable *var) ¶

Returns true if var’s value is to be retained from case to case, false if it is reinitialized to system-missing or spaces.

Function: void var_set_leave (struct variable *var, bool leave) ¶

If leave is true, marks var to be left from case to case; if leave is false, marks var to be reinitialized for each case.

If var is a scratch variable, leave must be true.

Function: bool var_must_leave (const struct variable *var) ¶

Returns true if var must be left from case to case, that is, if var is a scratch variable.

2.5.9 Dictionary Class

Occasionally it is useful to classify variables into dictionary classes based on their names. Dictionary classes are represented by enum dict_class. This type and other declarations for dictionary classes are in the <data/dict-class.h> header.

Enumeration: enum dict_class ¶

The dictionary classes are:

DC_ORDINARY

An ordinary variable, one whose name does not begin with ‘$’ or ‘#’.

DC_SYSTEM

A system variable, one whose name begins with ‘$’. See System Variables in PSPP Users Guide.

DC_SCRATCH

A scratch variable, one whose name begins with ‘#’. See Scratch Variables in PSPP Users Guide.

The values for dictionary classes are bitwise disjoint, which allows them to be used in bit-masks. An extra enumeration constant DC_ALL, whose value is the bitwise-or of all of the above constants, is provided to aid in this purpose.

One example use of dictionary classes arises in connection with PSPP syntax that uses a TO b to name the variables in a dictionary from a to b (see Sets of Variables in PSPP Users Guide). This syntax requires a and b to be in the same dictionary class. It limits the variables that it includes to those in that dictionary class.

The following functions relate to dictionary classes.

Function: enum dict_class dict_class_from_id (const char *name) ¶

Returns the “dictionary class” for the given variable name, by looking at its first letter.

Function: const char * dict_class_to_name (enum dict_class dict_class) ¶

Returns a name for the given dict_class as an adjective, e.g. "scratch".

This function should probably not be used in new code as it can lead to difficulties for internationalization.

2.5.10 Variable Creation and Destruction

Only rarely should PSPP code create or destroy variables directly. Ordinarily, variables are created within a dictionary and destroying by individual deletion from the dictionary or by destroying the entire dictionary at once. The functions here enable the exceptional case, of creation and destruction of variables that are not associated with any dictionary. These functions are used internally in the dictionary implementation.

Function: struct variable * var_create (const char *name, int width) ¶

Creates and returns a new variable with the given name and width. The new variable is not part of any dictionary. Use dict_create_var, instead, to create a variable in a dictionary (see Creating Variables).

name should be a valid variable name and must be a “plausible” variable name (see Variable Name). width must be between 0 and MAX_STRING, inclusive (see Values).

The new variable has no user-missing values, value labels, or variable label. Numeric variables initially have F8.2 print and write formats, right-justified display alignment, and scale level of measurement. String variables are created with A print and write formats, left-justified display alignment, and nominal level of measurement. The initial display width is determined by var_default_display_width (see var_default_display_width).

The new variable initially has no short name (see Variable Short Names) and no auxiliary data (see Variable Auxiliary Data).

Function: struct variable * var_clone (const struct variable *old_var) ¶

Creates and returns a new variable with the same attributes as old_var, with a few exceptions. First, the new variable is not part of any dictionary, regardless of whether old_var was in a dictionary. Use dict_clone_var, instead, to add a clone of a variable to a dictionary.

Second, the new variable is not given any short name, even if old_var had a short name. This is because the new variable is likely to be immediately renamed, in which case the short name would be incorrect (see Variable Short Names).

Finally, old_var’s auxiliary data, if any, is not copied to the new variable (see Variable Auxiliary Data).

Function: void var_destroy (struct variable *var) ¶

Destroys var and frees all associated storage, including its auxiliary data, if any. var must not be part of a dictionary. To delete a variable from a dictionary and destroy it, use dict_delete_var (see Deleting Variables).

2.5.11 Variable Short Names

PSPP variable names may be up to 64 (ID_MAX_LEN) bytes long. The system and portable file formats, however, were designed when variable names were limited to 8 bytes in length. Since then, the system file format has been augmented with an extension record that explains how the 8-byte short names map to full-length names (see Long Variable Names Record), but the short names are still present. Thus, the continued presence of the short names is more or less invisible to PSPP users, but every variable in a system file still has a short name that must be unique.

PSPP can generate unique short names for variables based on their full names at the time it creates the data file. If all variables’ full names are unique in their first 8 bytes, then the short names are simply prefixes of the full names; otherwise, PSPP changes them so that they are unique.

By itself this algorithm interoperates well with other software that can read system files, as long as that software understands the extension record that maps short names to long names. When the other software does not understand the extension record, it can produce surprising results. Consider a situation where PSPP reads a system file that contains two variables named RANKINGSCORE, then the user adds a new variable named RANKINGSTATUS, then saves the modified data as a new system file. A program that does not understand long names would then see one of these variables under the name RANKINGS—either one, depending on the algorithm’s details—and the other under a different name. The effect could be very confusing: by adding a new and apparently unrelated variable in PSPP, the user effectively renamed the existing variable.

To counteract this potential problem, every struct variable may have a short name. A variable created by the system or portable file reader receives the short name from that data file. When a variable with a short name is written to a system or portable file, that variable receives priority over other long names whose names begin with the same 8 bytes but which were not read from a data file under that short name.

Variables not created by the system or portable file reader have no short name by default.

A variable with a full name of 8 bytes or less in length has absolute priority for that name when the variable is written to a system file, even over a second variable with that assigned short name.

PSPP does not enforce uniqueness of short names, although the short names read from any given data file will always be unique. If two variables with the same short name are written to a single data file, neither one receives priority.

The following macros and functions relate to short names.

Macro: SHORT_NAME_LEN ¶

Maximum length of a short name, in bytes. Its value is 8.

Function: const char * var_get_short_name (const struct variable *var) ¶

Returns var’s short name, or a null pointer if var has not been assigned a short name.

Function: void var_set_short_name (struct variable *var, const char *short_name) ¶

Sets var’s short name to short_name, or removes var’s short name if short_name is a null pointer. If it is non-null, then short_name must be a plausible name for a variable. The name will be truncated to 8 bytes in length and converted to all-uppercase.

Function: void var_clear_short_name (struct variable *var) ¶

Removes var’s short name.

2.5.12 Variable Relationships

Variables have close relationships with dictionaries (see Dictionaries) and cases (see Cases). A variable is usually a member of some dictionary, and a case is often used to store data for the set of variables in a dictionary.

These functions report on these relationships. They may be applied only to variables that are in a dictionary.

Function: size_t var_get_dict_index (const struct variable *var) ¶

Returns var’s index within its dictionary. The first variable in a dictionary has index 0, the next variable index 1, and so on.

The dictionary index can be influenced using dictionary functions such as dict_reorder_var (see dict_reorder_var).

Function: size_t var_get_case_index (const struct variable *var) ¶

Returns var’s index within a case. The case index is an index into an array of union value large enough to contain all the data in the dictionary.

The returned case index can be used to access the value of var within a case for its dictionary, as in e.g. case_data_idx (case, var_get_case_index (var)), but ordinarily it is more convenient to use the data access functions that do variable-to-index translation internally, as in e.g. case_data (case, var).

2.5.13 Variable Auxiliary Data

Each struct variable can have a single pointer to auxiliary data of type void *. These functions manipulate a variable’s auxiliary data.

Use of auxiliary data is discouraged because of its lack of flexibility. Only one client can make use of auxiliary data on a given variable at any time, even though many clients could usefully associate data with a variable.

To prevent multiple clients from attempting to use a variable’s single auxiliary data field at the same time, we adopt the convention that use of auxiliary data in the active dataset dictionary is restricted to the currently executing command. In particular, transformations must not attach auxiliary data to a variable in the active dataset in the expectation that it can be used later when the active dataset is read and the transformation is executed. To help enforce this restriction, auxiliary data is deleted from all variables in the active dataset dictionary after the execution of each PSPP command.

This convention for safe use of auxiliary data applies only to the active dataset dictionary. Rules for other dictionaries may be established separately.

Auxiliary data should be replaced by a more flexible mechanism at some point, but no replacement mechanism has been designed or implemented so far.

The following functions work with variable auxiliary data.

Function: void * var_get_aux (const struct variable *var) ¶

Returns var’s auxiliary data, or a null pointer if none has been assigned.

Function: void * var_attach_aux (const struct variable *var, void *aux, void (*aux_dtor) (struct variable *)) ¶

Sets var’s auxiliary data to aux, which must not be null. var must not already have auxiliary data.

Before var’s auxiliary data is cleared by var_clear_aux, aux_dtor, if non-null, will be called with var as its argument. It should free any storage associated with aux, if necessary. var_dtor_free may be appropriate for use as aux_dtor:

Function: void var_dtor_free (struct variable *var) ¶

Frees var’s auxiliary data by calling free.

Function: void var_clear_aux (struct variable *var) ¶

Removes auxiliary data, if any, from var, first calling the destructor passed to var_attach_aux, if one was provided.

Use dict_clear_aux to remove auxiliary data from every variable in a dictionary.

Function: void * var_detach_aux (struct variable *var) ¶

Removes auxiliary data, if any, from var, and returns it. Returns a null pointer if var had no auxiliary data.

Any destructor passed to var_attach_aux is not called, so the caller is responsible for freeing storage associated with the returned auxiliary data.

2.5.14 Variable Categorical Values

Some statistical procedures require a list of all the values that a categorical variable takes on. Arranging such a list requires making a pass through the data, so PSPP caches categorical values in struct variable.

When variable auxiliary data is revamped to support multiple clients as described in the previous section, categorical values are an obvious candidate. The form in which they are currently supported is inelegant.

Categorical values are not robust against changes in the data. That is, there is currently no way to detect that a transformation has changed data values, meaning that categorical values lists for the changed variables must be recomputed. PSPP is in fact in need of a general-purpose caching and cache-invalidation mechanism, but none has yet been designed and built.

The following functions work with cached categorical values.

Function: struct cat_vals * var_get_obs_vals (const struct variable *var) ¶

Returns var’s set of categorical values. Yields undefined behavior if var does not have any categorical values.

Function: void var_set_obs_vals (const struct variable *var, struct cat_vals *cat_vals) ¶

Destroys var’s categorical values, if any, and replaces them by cat_vals, ownership of which is transferred to var. If cat_vals is a null pointer, then var’s categorical values are cleared.

Function: bool var_has_obs_vals (const struct variable *var) ¶

Returns true if var has a set of categorical values, false otherwise.

2.6.1 Accessing Variables

The most common operations on a dictionary simply retrieve a struct variable * of an individual variable based on its name or position.

Function: struct variable * dict_lookup_var (const struct dictionary *dict, const char *name) ¶

Function: struct variable * dict_lookup_var_assert (const struct dictionary *dict, const char *name) ¶

Looks up and returns the variable with the given name within dict. Name lookup is not case-sensitive.

dict_lookup_var returns a null pointer if dict does not contain a variable named name. dict_lookup_var_assert asserts that such a variable exists.

Function: struct variable * dict_get_var (const struct dictionary *dict, size_t position) ¶

Returns the variable at the given position in dict. position must be less than the number of variables in dict (see below).

Function: size_t dict_get_n_vars (const struct dictionary *dict) ¶

Returns the number of variables in dict.

Another pair of functions allows retrieving a number of variables at once. These functions are more rarely useful.

Function: void dict_get_vars (const struct dictionary *dict, const struct variable ***vars, size_t *cnt, enum dict_class exclude) ¶

Function: void dict_get_vars_mutable (const struct dictionary *dict, struct variable ***vars, size_t *cnt, enum dict_class exclude) ¶

Retrieves all of the variables in dict, in their original order, except that any variables in the dictionary classes specified exclude, if any, are excluded (see Dictionary Class). Pointers to the variables are stored in an array allocated with malloc, and a pointer to the first element of this array is stored in *vars. The caller is responsible for freeing this memory when it is no longer needed. The number of variables retrieved is stored in *cnt.

The presence or absence of DC_SYSTEM in exclude has no effect, because dictionaries never include system variables.

One additional function is available. This function is most often used in assertions, but it is not restricted to such use.

Function: bool dict_contains_var (const struct dictionary *dict, const struct variable *var) ¶

Tests whether var is one of the variables in dict. Returns true if so, false otherwise.

2.6.2 Creating Variables

These functions create a new variable and insert it into a dictionary in a single step.

There is no provision for inserting an already created variable into a dictionary. There is no reason that such a function could not be written, but so far there has been no need for one.

The names provided to one of these functions should be valid variable names and must be plausible variable names.

If a variable with the same name already exists in the dictionary, the non-assert variants of these functions return a null pointer, without modifying the dictionary. The assert variants, on the other hand, assert that no duplicate name exists.

A variable may be in only one dictionary at any given time.

Function: struct variable * dict_create_var (struct dictionary *dict, const char *name, int width) ¶

Function: struct variable * dict_create_var_assert (struct dictionary *dict, const char *name, int width) ¶

Creates a new variable with the given name and width, as if through a call to var_create with those arguments (see var_create), appends the new variable to dict’s array of variables, and returns the new variable.

Function: struct variable * dict_clone_var (struct dictionary *dict, const struct variable *old_var) ¶

Function: struct variable * dict_clone_var_assert (struct dictionary *dict, const struct variable *old_var) ¶

Creates a new variable as a clone of var, inserts the new variable into dict, and returns the new variable. Other properties of the new variable are copied from old_var, except for those not copied by var_clone (see var_clone).

var does not need to be a member of any dictionary.

Function: struct variable * dict_clone_var_as (struct dictionary *dict, const struct variable *old_var, const char *name) ¶

Function: struct variable * dict_clone_var_as_assert (struct dictionary *dict, const struct variable *old_var, const char *name) ¶

These functions are similar to dict_clone_var and dict_clone_var_assert, respectively, except that the new variable is named name instead of keeping old_var’s name.

2.6.3 Deleting Variables

These functions remove variables from a dictionary’s array of variables. They also destroy the removed variables and free their associated storage.

Deleting a variable to which there might be external pointers is a bad idea. In particular, deleting variables from the active dataset dictionary is a risky proposition, because transformations can retain references to arbitrary variables. Therefore, no variable should be deleted from the active dataset dictionary when any transformations are active, because those transformations might reference the variable to be deleted. The safest time to delete a variable is just after a procedure has been executed, as done by DELETE VARIABLES.

Deleting a variable automatically removes references to that variable from elsewhere in the dictionary as a weighting variable, filter variable, SPLIT FILE variable, or member of a vector.

No functions are provided for removing a variable from a dictionary without destroying that variable. As with insertion of an existing variable, there is no reason that this could not be implemented, but so far there has been no need.

Function: void dict_delete_var (struct dictionary *dict, struct variable *var) ¶

Deletes var from dict, of which it must be a member.

Function: void dict_delete_vars (struct dictionary *dict, struct variable *const *vars, size_t count) ¶

Deletes the count variables in array vars from dict. All of the variables in vars must be members of dict. No variable may be included in vars more than once.

Function: void dict_delete_consecutive_vars (struct dictionary *dict, size_t idx, size_t count) ¶

Deletes the variables in sequential positions idx…idx + count (exclusive) from dict, which must contain at least idx + count variables.

Function: void dict_delete_scratch_vars (struct dictionary *dict) ¶

Deletes all scratch variables from dict.

2.6.4 Changing Variable Order

The variables in a dictionary are stored in an array. These functions change the order of a dictionary’s array of variables without changing which variables are in the dictionary.

Function: void dict_reorder_var (struct dictionary *dict, struct variable *var, size_t new_index) ¶

Moves var, which must be in dict, so that it is at position new_index in dict’s array of variables. Other variables in dict, if any, retain their relative positions. new_index must be less than the number of variables in dict.

Function: void dict_reorder_vars (struct dictionary *dict, struct variable *const *new_order, size_t count) ¶

Moves the count variables in new_order to the beginning of dict’s array of variables in the specified order. Other variables in dict, if any, retain their relative positions.

All of the variables in new_order must be in dict. No duplicates are allowed within new_order, which means that count must be no greater than the number of variables in dict.

2.6.5 Renaming Variables

These functions change the names of variables within a dictionary. The var_set_name function (see var_set_name) cannot be applied directly to a variable that is in a dictionary, because struct dictionary contains an index by name that var_set_name would not update. The following functions take care to update the index as well. They also ensure that variable renaming does not cause a dictionary to contain a duplicate variable name.

Function: void dict_rename_var (struct dictionary *dict, struct variable *var, const char *new_name) ¶

Changes the name of var, which must be in dict, to new_name. A variable named new_name must not already be in dict, unless new_name is the same as var’s current name.

Function: bool dict_rename_vars (struct dictionary *dicT, struct variable **vars, char **new_names, size_t count, char **err_name) ¶

Renames each of the count variables in vars to the name in the corresponding position of new_names. If the renaming would result in a duplicate variable name, returns false and stores one of the names that would be duplicated into *err_name, if err_name is non-null. Otherwise, the renaming is successful, and true is returned.

2.6.6 Weight Variable

A data set’s cases may optionally be weighted by the value of a numeric variable. See WEIGHT in PSPP Users Guide, for a user view of weight variables.

The weight variable is written to and read from system and portable files.

The most commonly useful function related to weighting is a convenience function to retrieve a weighting value from a case.

Function: double dict_get_case_weight (const struct dictionary *dict, const struct ccase *case, bool *warn_on_invalid) ¶

Retrieves and returns the value of the weighting variable specified by dict from case. Returns 1.0 if dict has no weighting variable.

Returns 0.0 if c’s weight value is user- or system-missing, zero, or negative. In such a case, if warn_on_invalid is non-null and *warn_on_invalid is true, dict_get_case_weight also issues an error message and sets *warn_on_invalid to false. To disable error reporting, pass a null pointer or a pointer to false as warn_on_invalid or use a msg_disable/msg_enable pair.

The dictionary also has a pair of functions for getting and setting the weight variable.

Function: struct variable * dict_get_weight (const struct dictionary *dict) ¶

Returns dict’s current weighting variable, or a null pointer if the dictionary does not have a weighting variable.

Function: void dict_set_weight (struct dictionary *dict, struct variable *var) ¶

Sets dict’s weighting variable to var. If var is non-null, it must be a numeric variable in dict. If var is null, then dict’s weighting variable, if any, is cleared.

2.6.7 Filter Variable

When the active dataset is read by a procedure, cases can be excluded from analysis based on the values of a filter variable. See FILTER in PSPP Users Guide, for a user view of filtering.

These functions store and retrieve the filter variable. They are rarely useful, because the data analysis framework automatically excludes from analysis the cases that should be filtered.

Function: struct variable * dict_get_filter (const struct dictionary *dict) ¶

Returns dict’s current filter variable, or a null pointer if the dictionary does not have a filter variable.

Function: void dict_set_filter (struct dictionary *dict, struct variable *var) ¶

Sets dict’s filter variable to var. If var is non-null, it must be a numeric variable in dict. If var is null, then dict’s filter variable, if any, is cleared.

2.6.8 Case Limit

The limit on cases analyzed by a procedure, set by the N OF CASES command (see N OF CASES in PSPP Users Guide), is stored as part of the dictionary. The dictionary does not, on the other hand, play any role in enforcing the case limit (a job done by data analysis framework code).

A case limit of 0 means that the number of cases is not limited.

These functions are rarely useful, because the data analysis framework automatically excludes from analysis any cases beyond the limit.

Function: casenumber dict_get_case_limit (const struct dictionary *dict) ¶

Returns the current case limit for dict.

Function: void dict_set_case_limit (struct dictionary *dict, casenumber limit) ¶

Sets dict’s case limit to limit.

2.6.9 Split Variables

The user may use the SPLIT FILE command (see SPLIT FILE in PSPP Users Guide) to select a set of variables on which to split the active dataset into groups of cases to be analyzed independently in each statistical procedure. The set of split variables is stored as part of the dictionary, although the effect on data analysis is implemented by each individual statistical procedure.

Split variables may be numeric or short or long string variables.

The most useful functions for split variables are those to retrieve them. Even these functions are rarely useful directly: for the purpose of breaking cases into groups based on the values of the split variables, it is usually easier to use casegrouper_create_splits.

Function: const struct variable *const * dict_get_split_vars (const struct dictionary *dict) ¶

Returns a pointer to an array of pointers to split variables. If and only if there are no split variables, returns a null pointer. The caller must not modify or free the returned array.

Function: size_t dict_get_n_splits (const struct dictionary *dict) ¶

Returns the number of split variables.

The following functions are also available for working with split variables.

Function: void dict_set_split_vars (struct dictionary *dict, struct variable *const *vars, size_t cnt) ¶

Sets dict’s split variables to the cnt variables in vars. If cnt is 0, then dict will not have any split variables. The caller retains ownership of vars.

Function: void dict_unset_split_var (struct dictionary *dict, struct variable *var) ¶

Removes var, which must be a variable in dict, from dict’s split of split variables.

2.6.10 File Label

A dictionary may optionally have an associated string that describes its contents, called its file label. The user may set the file label with the FILE LABEL command (see FILE LABEL in PSPP Users Guide).

These functions set and retrieve the file label.

Function: const char * dict_get_label (const struct dictionary *dict) ¶

Returns dict’s file label. If dict does not have a label, returns a null pointer.

Function: void dict_set_label (struct dictionary *dict, const char *label) ¶

Sets dict’s label to label. If label is non-null, then its content, truncated to at most 60 bytes, becomes the new file label. If label is null, then dict’s label is removed.

The caller retains ownership of label.

2.6.11 Documents

A dictionary may include an arbitrary number of lines of explanatory text, called the dictionary’s documents. For compatibility, document lines have a fixed width, and lines that are not exactly this width are truncated or padded with spaces as necessary to bring them to the correct width.

PSPP users can use the DOCUMENT (see DOCUMENT in PSPP Users Guide), ADD DOCUMENT (see ADD DOCUMENT in PSPP Users Guide), and DROP DOCUMENTS (see DROP DOCUMENTS in PSPP Users Guide) commands to manipulate documents.

Macro: int DOC_LINE_LENGTH ¶

The fixed length of a document line, in bytes, defined to 80.

The following functions work with whole sets of documents. They accept or return sets of documents formatted as null-terminated strings that are an exact multiple of DOC_LINE_LENGTH bytes in length.

Function: const char * dict_get_documents (const struct dictionary *dict) ¶

Returns the documents in dict, or a null pointer if dict has no documents.

Function: void dict_set_documents (struct dictionary *dict, const char *new_documents) ¶

Sets dict’s documents to new_documents. If new_documents is a null pointer or an empty string, then dict’s documents are cleared. The caller retains ownership of new_documents.

Function: void dict_clear_documents (struct dictionary *dict) ¶

Clears the documents from dict.

The following functions work with individual lines in a dictionary’s set of documents.

Function: void dict_add_document_line (struct dictionary *dict, const char *content) ¶

Appends content to the documents in dict. The text in content will be truncated or padded with spaces as necessary to make it exactly DOC_LINE_LENGTH bytes long. The caller retains ownership of content.

If content is over DOC_LINE_LENGTH, this function also issues a warning using msg. To suppress the warning, enclose a call to one of this function in a msg_disable/msg_enable pair.

Function: size_t dict_get_document_n_lines (const struct dictionary *dict) ¶

Returns the number of line of documents in dict. If the dictionary contains no documents, returns 0.

Function: void dict_get_document_line (const struct dictionary *dict, size_t idx, struct string *content) ¶

Replaces the text in content (which must already have been initialized by the caller) by the document line in dict numbered idx, which must be less than the number of lines of documents in dict. Any trailing white space in the document line is trimmed, so that content will have a length between 0 and DOC_LINE_LENGTH.

6.1.1 The user interface locale

This is the locale which is visible to the person using pspp. Error messages and confidence indications are written in this locale. For example “Cannot open file” will be written in the user interface locale.

This locale is set from the environment of the user who starts pspp{ire} or from the system locale if not set.

6.1.2 The output locale

This locale is the one that should be visible to the person reading a report generated by pspp. Non-data related strings (Eg: “Page number”, “Standard Deviation” etc.) will appear in this locale.

6.1.3 The data locale

This locale is the one associated with the data being analysed with pspp. The only important aspect of this locale is the character encoding. ¹ The dictionary pertaining to the data contains a field denoting the encoding. Any string data stored in a union value will be encoded in the dictionary’s character set.

6.3.1 Filenames

The GLib API has some special functions for dealing with filenames. Strings returned from functions like gtk_file_chooser_dialog_get_name are not, in general, encoded in UTF8, but in “filename” encoding. If that filename is passed to another GLib function which expects a filename, no conversion is necessary. If it’s passed to a function for the purposes of displaying it (eg. in a window’s title-bar) it must be converted to UTF8 — there is a special function for this: g_filename_display_name or g_filename_basename. If however, a filename needs to be passed outside of GTK+/GLib (for example to fopen) it must be converted to the local system encoding.