---

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.