Next: , Previous: Dictionary Class, Up: Variables


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 Dictionary 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 Dictionary Deleting Variables).