---

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.