The most common operations on a dictionary simply retrieve a
struct variable *
of an individual variable based on its name
or position.
struct variable *
dict_lookup_var (const struct dictionary *dict, const char *name)
¶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.
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).
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.
void
dict_get_vars (const struct dictionary *dict, const struct variable ***vars, size_t *cnt, enum dict_class exclude)
¶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.
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.