---

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.