These functions allow iteration through the set of value labels
represented by a struct val_labs
object. They may be used in the
context of a for
loop:
struct val_labs val_labs;
const struct val_lab *vl;
…
for (vl = val_labs_first (val_labs); vl != NULL;
vl = val_labs_next (val_labs, vl))
{
…do something with vl
…
}
Value labels should not be added or deleted from a struct val_labs
as it is undergoing iteration.
const struct val_lab *
val_labs_first (const struct val_labs *val_labs)
¶Returns the first value label in var_labs, if it contains at least one value label, or a null pointer if it does not contain any value labels.
const struct val_lab *
val_labs_next (const struct val_labs *val_labs, const struct val_labs_iterator **vl)
¶Returns the value label in var_labs following vl, if vl is not the last value label in val_labs, or a null pointer if there are no value labels following vl.
const struct val_lab **
val_labs_sorted (const struct val_labs *val_labs)
¶Allocates and returns an array of pointers to value labels, which are
sorted in increasing order by value. The array has
val_labs_count (val_labs)
elements. The caller is
responsible for freeing the array with free
(but must not free
any of the struct val_lab
elements that the array points to).
The iteration functions above work with pointers to struct val_lab
which is an opaque data structure that users of struct val_labs
must
not modify or free directly. The following functions work with
objects of this type:
const union value *
val_lab_get_value (const struct val_lab *vl)
¶Returns the value of value label vl. The caller must not modify
or free the returned value. (To achieve a similar result, remove the
value label with val_labs_remove
, then add the new value with
val_labs_add
.)
The width of the returned value cannot be determined directly from
vl. It may be obtained by calling val_labs_get_width
on
the struct val_labs
that vl is in.
const char *
val_lab_get_label (const struct val_lab *vl)
¶Returns the label in vl as a null-terminated string. The caller
must not modify or free the returned string. (Use
val_labs_replace
to change a value label.)