Skip to content
Snippets Groups Projects
Commit 6a982f73 authored by Konstantin Shulgin's avatar Konstantin Shulgin
Browse files

Merge branch 'doc-lua-iterators'

parents ae0537b5 8a2f9b84
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/developer/developer.xml
+ 40
− 3
View file @ 6a982f73
......@@ -53,18 +53,55 @@ The other alternative, if you have actually modified
<title>How to build the XML manual</title>
<para>
To build XML manual, you'll need:
<itemizedlist>
<itemizedlist>
<listitem><para>xsltproc</para></listitem>
<listitem><para>docbook5-xml</para></listitem>
<listitem><para>docbook-xsl-ns</para></listitem>
<listitem><para>libsaxon-java- for saxon processing</para></listitem>
<listitem><para>libxml-commons-resolver1.1-java</para></listitem>
<listitem><para>libxml2-utils</para></listitem>
<listitem><para>libxerces2-java</para></listitem>
<listitem><para>libxslthl-java</para></listitem>
<listitem><para>lynx</para></listitem>
<listitem><para>jing</para></listitem>
</itemizedlist>
Once all pre-requisites are met, <computeroutput>make html</computeroutput>
to build the user guide.
When all pre-requisites are met, you should run:
<programlisting>
<prompt>$ </prompt> cmake . -DENABLE_DOC=yes
</programlisting>
to enable documentation builder.
If you want to make tarantool user guide, you should run the following command
from taratnool root directory:
<programlisting>
<prompt>$ </prompt> make html
</programlisting>
or
<programlisting>
<prompt>$ </prompt> cd doc/user
<prompt>$ </prompt> make
</programlisting>
The html version of the user guide will be generated in doc/www-data.
To building the developer guilde, you should run:
<programlisting>
<prompt>$ </prompt> cd doc/developer
<prompt>$ </prompt> make
</programlisting>
The html version of the developer guide will be generated in doc/www-data.
</para>
</section>
</chapter>
......
doc/user/stored-procedures.xml
+ 104
− 43
View file @ 6a982f73
......@@ -984,87 +984,148 @@ xreflabel="box.index">box.index</code></title>
</simpara>
</listitem>
</varlistentry>
</variablelist>
<para>
The following functions provide iteration support within an index.
<code>next</code> and <code>next_equal</code> provide common
iterators which go from the beginning to the end of the index.
<code>prev</code> and <code>prev_equal</code> provide reverse
iterators which travers the index in the reverse order.
In a non-unique index the routines with the <code>'_equal'</code>
suffix will traverse sequences of tuples with the same key value.
</para>
<variablelist>
<varlistentry>
<term>
<emphasis role="lua">index:pairs()</emphasis>
<emphasis role="lua">index:next(iteration_state, key)</emphasis>
</term>
<listitem><simpara>
A helper function to iterate over all tuples in an
index.
</simpara>
</listitem>
<listitem><simpara></simpara></listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="lua">index:prev(iteration_state, key)</emphasis>
</term>
<listitem><simpara></simpara></listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="lua">index:next_equal(iteration_state, key)</emphasis>
</term>
<listitem><simpara></simpara></listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="lua">index:next(iteration_state, key)</emphasis>
<emphasis role="lua">index:prev_equal(iteration_state, key)</emphasis>
</term>
<listitem><simpara>
This function can be used for positioned iteration, or
resuming iteration from a given key. It follows the
<link xlink:href='http://pgl.yoyo.org/luai/i/next'>Lua
iteration pattern</link> and returns a pair
<code>&lt;iteration_state, tuple&gt;</code>.
When called with no arguments, it starts iteration
from the beginning. If called with userdata
<code>iteration_state</code>, it returns a tuple
corresponding to iterator position, plus a new
<code>iteration_state</code>. When called with a key,
it positions the iterator on the key, and returns the
respective tuple and <code>iteration_state</code>.
</simpara>
<listitem>
<para>
The first argument is the iteration state and the second one is the
key. The functions create a new iterator if <code>iteration_state
</code> is not defined or <code>nil</code>.
The new iterator is positioned at the begining (or the end -- for
reverse iterators) of the sequence of tuples satifsying the key.
If the key is <code>nil</code> (or empty) the first (last) member
of the sequence will be the first (last) member of the index.
</para>
<para>
The functions follow the
<link xlink:href='http://pgl.yoyo.org/luai/i/next'>Lua iteration
pattern</link> returning <code>{iteration_state, tuple}</code> pair,
where <code>iteration_state</code> is the iterator and
<code>tuple</code> is the tuple the iterator points at.
The function returns <code>nil</code> if the iterator reaches the
end of the index or there are no more tuples satifsying the
<code>key</code> (for <code>_equal</code> functions).
</para>
<bridgehead renderas="sect4">Example</bridgehead>
<programlisting>
localhost> insert into t0 values (1, 'Russia')
Insert OK, 1 rows affected
localhost> insert into t0 values (2, 'Serbia')
Insert OK, 1 rows affected
localhost> insert into t0 values (3, 'Bulgaria')
Insert OK, 1 rows affected
localhost> lua i = box.space[0].index[0]
localhost> lua box.insert(0, "United Kingdom, The", "Europe")
localhost> lua box.insert(0, "France", "Europe")
localhost> lua box.insert(0, "Netherlands", "Europe")
localhost> lua box.insert(0, "Australia", "Oceania")
localhost> lua box.insert(0, "Vanuatu", "Oceania")
localhost> lua box.insert(0, "United States of America, The", "North America")
localhost> lua box.insert(0, "Canada", "North America")
localhost> lua box.insert(0, "Mexico", "North America")
localhost> lua pi = box.space[0].index[0] -- primary index
localhost> lua si = box.space[0].index[1] -- secondary index
localhost> lua k,v=pi:next() -- init iterator by primary from the begining
---
...
localhost> lua k,v=i:next()
localhost> lua print(v)
---
'Australia': {'Oceania'}
...
localhost> lua k,v=pi:next(k) -- move to next
---
...
localhost> lua print(v)
--
1: {'Russia'}
---
'Canada': {'North America'}
...
localhost> lua k,v=i:next(k)
localhost> lua k,v=pi:next(k) -- move to next
---
...
localhost> lua print(v)
---
2: {'Serbia'}
'France': {'Europe'}
...
localhost> lua k,v=i:next(k)
localhost> lua k,v=si:next_equal() -- init iterator by secondary from the begining
---
...
localhost> lua print(v)
---
3: {'Bulgaria'}
'United Kingdom, The': {'Europe'}
...
localhost> lua k,v=i:next(k)
localhost> lua k,v=si:next_equal(k) -- move to next
---
...
localhost> lua print(v)
---
nil
'France': {'Europe'}
...
localhost> lua k,v=i:next(2)
localhost> lua k,v=si:next_equal(k) -- move to next
---
...
localhost> lua print(v)
---
2: {'Serbia'}
'Netherlands': {'Europe'}
...
localhost> lua for k,v in pi.next, pi, nil do print(v) end
---
'Australia': {'Oceania'}
'Canada': {'North America'}
'France': {'Europe'}
'Mexico': {'North America'}
'Netherlands': {'Europe'}
'United Kingdom, The': {'Europe'}
'United States of America, The': {'North America'}
'Vanuatu': {'Oceania'}
...
localhost> lua for k,v in pi.prev, pi, nil do print(v) end
---
'Vanuatu': {'Oceania'}
'United States of America, The': {'North America'}
'United Kingdom, The': {'Europe'}
'Netherlands': {'Europe'}
'Mexico': {'North America'}
'France': {'Europe'}
'Canada': {'North America'}
'Australia': {'Oceania'}
...
localhost> lua for k,v in si.next_equal, si, 'Oceania' do print(v) end
---
'Australia': {'Oceania'}
'Vanuatu': {'Oceania'}
...
localhost> lua for k,v in i.next, i, nil do print(v) end
localhost> lua for k,v in si.prev_equal, si, 'North America' do print(v) end
---
1: {'Russia'}
2: {'Serbia'}
3: {'Bulgaria'}
'Mexico': {'North America'}
'Canada': {'North America'}
'United States of America, The': {'North America'}
...
</programlisting>
</listitem>
......
mod/box/box.lua
+ 5
− 0
View file @ 6a982f73
......@@ -259,6 +259,11 @@ function box.on_reload_configuration()
return index.idx:next(...) end
index_mt.prev = function(index, ...)
return index.idx:prev(...) end
index_mt.next_equal = function(index, ...)
return index.idx:next_equal(...) end
index_mt.prev_equal = function(index, ...)
return index.idx:prev_equal(...) end
--
index_mt.select_range = function(index, limit, ...)
local range = {}
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment