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
|
<?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.4 2006/04/17 22:58:08 ivan Exp $
-->
<refentry id="fn_dict_list_keys">
<refmeta>
<refentrytitle>dict_list_keys</refentrytitle>
<refmiscinfo>dict</refmiscinfo>
</refmeta>
<refnamediv>
<refname>dict_list_keys</refname>
<refpurpose>Returns an array of all keys stored in the given dictionary.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_dict_list_keys">
<funcprototype id="fproto_dict_list_keys">
<funcdef>vector <function>dict_list_keys</function></funcdef>
<paramdef>inout <parameter>dict</parameter> dictionary</paramdef>
<paramdef>in <parameter>destructive</parameter> any</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_dict_list_keys">
<title>Description</title>
<para>The function returns an array of all keys stored in the given dictionary, ignoring dependent parts of key-value pairs.
This is especially useful when dictionary is used to form a set of distinct keys, when dependent parts are fake (typically zeroes).
If the <parameter>destructive</parameter> parameter is 1 or 2 then the function may avoid copying of keys to the resulting array
by moving them out from the dictionary. This is faster but the dictionary will become empty at the end of operation.
The <parameter>destructive</parameter> parameter equal to 1 does not have any effect if the dictionary is used as a value of more than one variable.
Thus it is safe to make this parameter equal to 1 as soon as the variable passed to the function as <parameter>dict</parameter> is no longer in use after
the function call and there's no need to inspect the whole program to check if other variables may be affected.
The parameter equal to 2 ignores the presence of multiple variables so the operation may cause unexpected results in other fragments of code that share the dictionary.
</para>
<para>
The created array can not be longer than the system limit and even if it is below limit but longer than hundreds of thousands items then memory allocation can be inefficient.
If the dictionary can be large and it is possible to process the content of the dictionary in parts, consider using
<link linkend="fn_dict_destructive_list_rnd_keys"><function>dict_destructive_list_rnd_keys</function></link>() instead.
</para>
</refsect1>
<refsect1 id="params_dict_list_keys">
<title>Parameters</title>
<refsect2><title>dict</title>
<para>The dictionary to scan</para>
</refsect2>
<refsect2><title>destructive</title>
<para>Flag that indicates whether the dictionary can be cleaned during the operation (0 = never clean, 1 = only if there is no other variables, 2 = clean unconditionally).</para>
</refsect2>
</refsect1>
<refsect1 id="ret_dict_list_keys"><title>Return Types</title>
<para>The function returns a vector.</para>
</refsect1>
<!-- <refsect1 id="examples_dict_list_keys">
<title>Examples</title>
<example id="ex_dict_list_keys"><title></title>
<para></para>
<screen><![CDATA[
]]>
</screen>
</example>
</refsect1> -->
<refsect1 id="seealso_dict_list_keys">
<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_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>
<para><link linkend="fn_dict_iter_next"><function>dict_iter_next()</function></link></para>
</refsect1>
</refentry>
|
