2.4.4 Iterating through Value Labels

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.

Function: 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.

Function: 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.

Function: 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:

Function: 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.

Function: 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.)