Name
dict_iter_next — Fetches a pair of key and value from a dictionary iterator and moves the iterator to the next pair.
Synopsis
dict_iter_next ( |
inout dict dictionary , |
out ret_key any , | |
out ret_value any
) ; |
Description
The function gets the dictionary iterator initialized earlier by
dict_iter_rewind
and checks whether the
iterator is still valid and not in conflict with any changes made
by dict_put
or the like.
After that, if the iterator is in the position past the last item
of the dictionary then zero is returned. If the iterator points to
some item then ret_key
and
ret_value
parameters are
set to the key and value of the current item, the iterator is
advanced to the next position (next item if present, otherwise past
the end of the dictionary) and a nonzero integer is returned. If
ret_value
is a constant or
an expression but not a plain variable then it is left unchanged
but no error is signalled, so if the caller procedure needs only
values of keys from dictionary then any constant like zero can be
passed as a third parameter. Similarly, ret_key
is not necessarily a
variable.
Note that the values of ret_key
and ret_value
are left unchanged if the
iterator points past the end of the dictionary. They are not filled
in with NULLs or something like that.
Parameters
dict
Dictionary iterator
ret_key
The variable to be filled in with the key of the item. The parameter is ignored if it is not a plain variable.
ret_value
The variable to be filled in with the value (dependant part) of the item. The parameter is ignored if it is not a plain variable.
Return Types
The function returns a nonzero integer if the item is successfully fetched, zero otherwise
Errors
This function can generate the following errors:
Table24.25.
Error Code | Description |
---|---|
22023 | SR630 Function dict_iter_next()
tries to iterate a volatile dictionary changed after last dict_iter_rewind (). Not every change in the
dictionary results in this error. If the dict_iter_next() and
dict_put () (or
similar function) are both called with same variable passed as
dict parameter then the
function might adjust the iterator to match the changed state of
the dictionary so it remains valid. In addition, if dict_put () changes only the value associated
with some key but does not extend the dictionary with a new item
then it does not invalidate any iterators. |
Example
Example24.92.Simplest read throughout the dictionary.
The procedure creates a dictionary, puts couple of items into it and then print them to the server's console
create function dict_iterator_test () { declare dict, dkey, dvalue any; dict := dict_new (10); dict_put (dict, 'a', 1); dict_put (dict, 'b', 2); dict_iter_rewind (dict); while (dict_iter_next (dict, dkey, dvalue)) dbg_obj_princ (' key is ' dkey, ', corresponding value is ', dvalue); }