1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
project.
Copyright (C) 1998-2018 OpenLink Software
This project is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; only version 2 of the License, dated June 1991.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
: template.sh,v 1.6 2009/04/14 11:39:26 source Exp $
-->
<refentry id="fn_dict_iter_next">
<refmeta>
<refentrytitle>dict_iter_next</refentrytitle>
<refmiscinfo>dict</refmiscinfo>
</refmeta>
<refnamediv>
<refname>dict_iter_next</refname>
<refpurpose>Fetches a pair of key and value from a dictionary iterator and moves the iterator to the next pair.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_dict_iter_next">
<funcprototype id="fproto_dict_iter_next">
<funcdef><function>dict_iter_next</function></funcdef>
<paramdef>inout <parameter>dict</parameter> dictionary</paramdef>
<paramdef>out <parameter>ret_key</parameter> any</paramdef>
<paramdef>out <parameter>ret_value</parameter> any</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_dict_iter_next">
<title>Description</title>
<para>The function gets the dictionary iterator initialized earlier by <link linkend="fn_dict_iter_rewind"><function>dict_iter_rewind</function></link>
and checks whether the iterator is still valid and not in conflict with any changes made by <link linkend="fn_dict_put"><function>dict_put</function></link> 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 <parameter>ret_key</parameter> and <parameter>ret_value</parameter> 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 <parameter>ret_value</parameter> 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, <parameter>ret_key</parameter> is not necessarily a variable.
</para>
<para>Note that the values of <parameter>ret_key</parameter> and <parameter>ret_value</parameter> are left unchanged if the iterator points past the end of the dictionary.
They are not filled in with NULLs or something like that.
</para>
</refsect1>
<refsect1 id="params_dict_iter_next">
<title>Parameters</title>
<refsect2><title>dict</title>
<para>Dictionary iterator</para>
</refsect2>
<refsect2><title>ret_key</title>
<para>The variable to be filled in with the key of the item. The parameter is ignored if it is not a plain variable.</para>
</refsect2>
<refsect2><title>ret_value</title>
<para>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.</para>
</refsect2>
</refsect1>
<refsect1 id="ret_dict_iter_next"><title>Return Types</title>
<para>The function returns a nonzero integer if the item is successfully fetched, zero otherwise</para>
</refsect1>
<refsect1 id="errors_dict_iter_next">
<title>Errors</title>
<para>This function can generate the following errors:</para>
<tgroup cols="2">
<thead><row><entry>Error Code</entry><entry>Description</entry></row></thead>
<tbody>
<row><entry><errorcode>22023</errorcode></entry>
<entry><errorname>SR630</errorname> Function dict_iter_next() tries to iterate a volatile dictionary changed after last <link linkend="fn_dict_iter_rewind"><function>dict_iter_rewind</function></link>().
Not every change in the dictionary results in this error.
If the dict_iter_next() and <link linkend="fn_dict_put"><function>dict_put</function></link>() (or similar function) are both called with same variable passed as <parameter>dict</parameter> parameter
then the function might adjust the iterator to match the changed state of the dictionary so it remains valid.
In addition, if <link linkend="fn_dict_put"><function>dict_put</function></link>() 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.</entry></row>
</tbody>
</tgroup>
</refsect1>
<refsect1 id="examples_dict_iter_next">
<title>Example</title>
<example id="ex_dict_iter_next"><title>Simplest read throughout the dictionary.</title>
<para>The procedure creates a dictionary, puts couple of items into it and then print them to the server's console</para>
<screen><![CDATA[
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);
}
]]>
</screen>
</example>
</refsect1>
<refsect1 id="seealso_dict_iter_next">
<title>See Also</title>
<para><link linkend="fn_dict_new"><function>dict_new</function></link></para>
<para><link linkend="fn_dict_zap"><function>dict_zap</function></link></para>
<para><link linkend="fn_dict_put"><function>dict_put</function></link></para>
<para><link linkend="fn_dict_get"><function>dict_get</function></link></para>
<para><link linkend="fn_dict_remove"><function>dict_remove</function></link></para>
<para><link linkend="fn_dict_inc_or_put"><function>dict_inc_or_put</function></link></para>
<para><link linkend="fn_dict_dec_or_remove"><function>dict_dec_or_remove</function></link></para>
<para><link linkend="fn_dict_size"><function>dict_size</function></link></para>
<para><link linkend="fn_dict_duplicate"><function>dict_duplicate</function></link></para>
<para><link linkend="fn_dict_to_vector"><function>dict_to_vector</function></link></para>
<para><link linkend="fn_dict_list_keys"><function>dict_list_keys</function></link></para>
<para><link linkend="fn_dict_destructive_list_rnd_keys"><function>dict_destructive_list_rnd_keys</function></link></para>
<para><link linkend="fn_dict_iter_rewind"><function>dict_iter_rewind</function></link></para>
</refsect1>
</refentry>
|
