Previous: Value Labels Adding and Removing Labels, Up: Value Labels


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 are usually used in the context of a for loop:

     struct val_labs val_labs;
     struct val_labs_iterator *i;
     struct val_lab *vl;
     
     ...
     
     for (vl = val_labs_first (val_labs, &i); vl != NULL;
          vl = val_labs_next (val_labs, &i))
       {
         ...do something with vl...
       }

The value labels in a struct val_labs must not be modified as it is undergoing iteration.

— Structure: struct val_lab

Represents a value label for iteration purposes, with two client-visible members:

union value value
Value being labeled, of the same width as the struct val_labs being iterated.
const char *label
The label, as a null-terminated string.

— Structure: struct val_labs_iterator

Opaque object that represents the current state of iteration through a set of value value labels. Automatically destroyed by successful completion of iteration. Must be destroyed manually in other circumstances, by calling val_labs_done.

— Function: struct val_lab * val_labs_first (const struct val_labs *val_labs, struct val_labs_iterator **iterator)

If val_labs contains at least one value label, starts an iteration through val_labs, initializes *iterator to point to a newly allocated iterator, and returns the first value label in val_labs. If val_labs is empty, sets *iterator to null and returns a null pointer.

This function creates iterators that traverse sets of value labels in no particular order.

— Function: struct val_lab * val_labs_first_sorted (const struct val_labs *val_labs, struct val_labs_iterator **iterator)

Same as val_labs_first, except that the created iterator traverses the set of value labels in ascending order of value.

— Function: struct val_lab * val_labs_next (const struct val_labs *val_labs, struct val_labs_iterator **iterator)

Advances an iterator created with val_labs_first or val_labs_first_sorted to the next value label, which is returned. If the set of value labels is exhausted, returns a null pointer after freeing *iterator and setting it to a null pointer.

— Function: void val_labs_done (struct val_labs_iterator **iterator)

Frees *iterator and sets it to a null pointer. Does not need to be called explicitly if val_labs_next returns a null pointer, indicating that all value labels have been visited.