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
|
<?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_destructive_list_rnd_keys">
<refmeta>
<refentrytitle>dict_destructive_list_rnd_keys</refentrytitle>
<refmiscinfo>dict</refmiscinfo>
</refmeta>
<refnamediv>
<refname>dict_destructive_list_rnd_keys</refname>
<refpurpose>Returns all or some keys from the given dictionary</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_dict_destructive_list_rnd_keys">
<funcprototype id="fproto_dict_destructive_list_rnd_keys">
<funcdef><function>dict_destructive_list_rnd_keys</function></funcdef>
<paramdef>inout <parameter>dict</parameter> dictionary</paramdef>
<paramdef>in <parameter>batch_size</parameter> integer</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_dict_destructive_list_rnd_keys">
<title>Description</title>
<para>The function returns an array of keys stored in the given dictionary, ignoring dependent parts of key-value pairs, but unlike
<link linkend="fn_dict_list_keys"><function>dict_list_keys</function></link> it may return only some keys, not all, and it always remove the returned keys from the dictionary.
The returned array is <parameter>batch_size</parameter> items long (if the dictionary is big enough to fill it).</para>
<para>The order of items returned (and hence the content of the dictionary after function call) is undefined.
It is not randomized artificially but it may vary from run to run depending on barely predictable factors.
As a result, the most typical use of the function is calling it in a loop that ends when the size of returned array falls down to zero indicating that the dictionary is exausted.
</para>
</refsect1>
<refsect1 id="params_dict_destructive_list_rnd_keys">
<title>Parameters</title>
<refsect2><title>dict</title>
<para>The dictionary where result keys come from.</para>
</refsect2>
<refsect2><title>batch_size</title>
<para>The maximum size of array to be constructed. The value can not be less than 65535 and more than the maximum allowed length of array (1250000 for 64-bit machines, 25000000 for 32-bit machines).
All other equal, it is preferable to keep it below 200000.</para>
</refsect2>
</refsect1>
<refsect1 id="ret_dict_destructive_list_rnd_keys"><title>Return Types</title>
<para>The function always returns an array; the array is empty if <parameter>dict</parameter> is NULL or an empty dictionary.</para>
</refsect1>
<refsect1 id="examples_dict_destructive_list_rnd_keys">
<title>Example</title>
<example id="ex_dict_destructive_list_rnd_keys"><title>Simple Use</title>
<para>The function gets a dictionary with RDF triples stored as keys and inserts all these triples into a given graph.</para>
<screen><![CDATA[
create function DB.DBA.INSERT_DICT_IN_GRAPH (in graph_iri varchar, in triples_dict any) returns varchar
{
declare triples any;
declare ins_count integer;
ins_count := 0;
while (dict_size (triples_dict) > 0)
{
triples := dict_destructive_list_rnd_keys (triples_dict, 80000);
DB.DBA.RDF_INSERT_TRIPLES (graph_iri, triples, 1);
ins_count := ins_count + length (triples);
}
return sprintf ('The function INSERT_DICT_IN_GRAPH has inserted %d triples in graph <%s>',
ins_count, graph_iri );
}
;
]]>
</screen>
</example>
</refsect1>
<refsect1 id="seealso_dict_destructive_list_rnd_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_list_keys"><function>dict_list_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>
|
