<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.8"/>
<title>libcollection: Iterator interface</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">libcollection
 <span id="projectnumber">0.4.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.8 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Modules</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Iterator interface<div class="ingroups"><a class="el" href="group__collection.html">COLLECTION interface</a></div></div> </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga3842589b8a402d368b521f266160b224"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__iterfunc.html#ga3842589b8a402d368b521f266160b224">col_bind_iterator</a> (struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> **iterator, struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, int mode_flags)</td></tr>
<tr class="memdesc:ga3842589b8a402d368b521f266160b224"><td class="mdescLeft"> </td><td class="mdescRight">Bind iterator to a collection. <a href="#ga3842589b8a402d368b521f266160b224">More...</a><br /></td></tr>
<tr class="separator:ga3842589b8a402d368b521f266160b224"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gab2ee69142d0fe773e90ee3d2388733ca"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__iterfunc.html#gab2ee69142d0fe773e90ee3d2388733ca">col_unbind_iterator</a> (struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> *iterator)</td></tr>
<tr class="memdesc:gab2ee69142d0fe773e90ee3d2388733ca"><td class="mdescLeft"> </td><td class="mdescRight">Unbind the iterator from the collection. <a href="#gab2ee69142d0fe773e90ee3d2388733ca">More...</a><br /></td></tr>
<tr class="separator:gab2ee69142d0fe773e90ee3d2388733ca"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gafc903de3c66b1594ad88ce602ad3ce29"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__iterfunc.html#gafc903de3c66b1594ad88ce602ad3ce29">col_iterate_collection</a> (struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> *iterator, struct <a class="el" href="structcollection__item.html">collection_item</a> **item)</td></tr>
<tr class="memdesc:gafc903de3c66b1594ad88ce602ad3ce29"><td class="mdescLeft"> </td><td class="mdescRight">Iterate collection. <a href="#gafc903de3c66b1594ad88ce602ad3ce29">More...</a><br /></td></tr>
<tr class="separator:gafc903de3c66b1594ad88ce602ad3ce29"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga7219006e97928389831cdc2d5fb5665b"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__iterfunc.html#ga7219006e97928389831cdc2d5fb5665b">col_iterate_up</a> (struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> *iterator, unsigned level)</td></tr>
<tr class="memdesc:ga7219006e97928389831cdc2d5fb5665b"><td class="mdescLeft"> </td><td class="mdescRight">Move up. <a href="#ga7219006e97928389831cdc2d5fb5665b">More...</a><br /></td></tr>
<tr class="separator:ga7219006e97928389831cdc2d5fb5665b"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga87bb9a56443a070ec7d578a99afdd1fe"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__iterfunc.html#ga87bb9a56443a070ec7d578a99afdd1fe">col_get_iterator_depth</a> (struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> *iterator, int *depth)</td></tr>
<tr class="memdesc:ga87bb9a56443a070ec7d578a99afdd1fe"><td class="mdescLeft"> </td><td class="mdescRight">Get current depth. <a href="#ga87bb9a56443a070ec7d578a99afdd1fe">More...</a><br /></td></tr>
<tr class="separator:ga87bb9a56443a070ec7d578a99afdd1fe"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gaa27c968902512d9839d514429ef6cc5d"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__iterfunc.html#gaa27c968902512d9839d514429ef6cc5d">col_get_item_depth</a> (struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> *iterator, int *depth)</td></tr>
<tr class="memdesc:gaa27c968902512d9839d514429ef6cc5d"><td class="mdescLeft"> </td><td class="mdescRight">Get depth of the last returned item. <a href="#gaa27c968902512d9839d514429ef6cc5d">More...</a><br /></td></tr>
<tr class="separator:gaa27c968902512d9839d514429ef6cc5d"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga62921b5add3b4646072ef5abc383e71a"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__iterfunc.html#ga62921b5add3b4646072ef5abc383e71a">col_pin_iterator</a> (struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> *iterator)</td></tr>
<tr class="memdesc:ga62921b5add3b4646072ef5abc383e71a"><td class="mdescLeft"> </td><td class="mdescRight">Pin iterator. <a href="#ga62921b5add3b4646072ef5abc383e71a">More...</a><br /></td></tr>
<tr class="separator:ga62921b5add3b4646072ef5abc383e71a"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga11e94d23399788f1d83a28db06177834"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__iterfunc.html#ga11e94d23399788f1d83a28db06177834">col_rewind_iterator</a> (struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> *iterator)</td></tr>
<tr class="memdesc:ga11e94d23399788f1d83a28db06177834"><td class="mdescLeft"> </td><td class="mdescRight">Rewind iterator. <a href="#ga11e94d23399788f1d83a28db06177834">More...</a><br /></td></tr>
<tr class="separator:ga11e94d23399788f1d83a28db06177834"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>The functions in this section allow iterating through a collection in a loop where the caller implements the loop. It is different from the search and traverse functions described in other sections because those functions implement the loop themselves and call provided callback in a specific situation. </p>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="ga3842589b8a402d368b521f266160b224"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_bind_iterator </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> ** </td>
<td class="paramname"><em>iterator</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"><em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>mode_flags</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Bind iterator to a collection. </p>
<p>This function creates an iterator object and binds it to the collection.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[out]</td><td class="paramname">iterator</td><td>Newly created iterator object. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">ci</td><td>Collection to iterate. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">mode_flags</td><td>Flags define how to traverse the collection. For more information see <a class="el" href="group__traverseconst.html">constants defining traverse modes</a>.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 - Iterator was created successfully. </dd>
<dd>
ENOMEM - No memory. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd></dl>
</div>
</div>
<a class="anchor" id="gab2ee69142d0fe773e90ee3d2388733ca"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void col_unbind_iterator </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> * </td>
<td class="paramname"><em>iterator</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Unbind the iterator from the collection. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">iterator</td><td>Iterator object to free. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="gafc903de3c66b1594ad88ce602ad3ce29"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_iterate_collection </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> * </td>
<td class="paramname"><em>iterator</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> ** </td>
<td class="paramname"><em>item</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Iterate collection. </p>
<p>Advance to next item in the collection. After the iterator is bound it does not point to any item in the collection. Use this function in the loop to step through all items in the collection. See unit test for code examples.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">iterator</td><td>Iterator object to use. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">item</td><td>Pointer to the collection item. Do not destroy or alter this pointer in any ways. To access the internals of the item use <a class="el" href="group__getitem.html">item management</a> functions. The value of the item will be set to NULL if the end of the collection is reached.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 - Item was successfully retrieved. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd></dl>
</div>
</div>
<a class="anchor" id="ga7219006e97928389831cdc2d5fb5665b"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_iterate_up </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> * </td>
<td class="paramname"><em>iterator</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned </td>
<td class="paramname"><em>level</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Move up. </p>
<p>Stop processing this sub collection and move to the next item in the collection some levels up.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">iterator</td><td>Iterator object to use. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">level</td><td>Indicates how many levels up you want to jump. If 0 - call is a no op. If the depth is less then requested level the iterator will get to the 0 level and next call to <a class="el" href="group__iterfunc.html#gafc903de3c66b1594ad88ce602ad3ce29">col_iterate_collection</a> will return NULL item.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 - Iterator was successfully repositioned. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd></dl>
</div>
</div>
<a class="anchor" id="ga87bb9a56443a070ec7d578a99afdd1fe"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_get_iterator_depth </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> * </td>
<td class="paramname"><em>iterator</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>depth</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Get current depth. </p>
<p>How deep are we relative to the top level? This function will report depth that in some cases might look misleading. The reason is that traverse flags affect the internal level we are on at each moment. For example the default traverse behavior is to show references to the sub collections. So when the item reference is returned the depth automatically adjusted to level inside the sub collection. So if function is called in this situation the level returned will denote the level inside collection. Now imagine that this collection is empty so the attempt to read element will push you automatically one level up (in absence of the <a class="el" href="group__traverseconst.html#ga86d3337570601f58b54cff7271b442eb">COL_TRAVERSE_END</a> flag). If in this situation you encounter another collection the reference will be returned and level automatically adjusted to level inside the collection. The point is that the level is reliable only after a data item was returned. To avoid this ambiguity another function <a class="el" href="group__iterfunc.html#gaa27c968902512d9839d514429ef6cc5d">col_get_item_depth</a> was introduced.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">iterator</td><td>Iterator object to use. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">depth</td><td>The variable will receive the depth the iterator is on. The value is 0 if the iterator is on the top level.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 - Success. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd></dl>
</div>
</div>
<a class="anchor" id="gaa27c968902512d9839d514429ef6cc5d"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_get_item_depth </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> * </td>
<td class="paramname"><em>iterator</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>depth</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Get depth of the last returned item. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">iterator</td><td>Iterator object to use. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">depth</td><td>The variable will receive the depth the iterator is on. Item from the top level will have depth equal to 0. The value of 0 will also be returned if no item was read so far.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 - Success. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd></dl>
</div>
</div>
<a class="anchor" id="ga62921b5add3b4646072ef5abc383e71a"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void col_pin_iterator </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> * </td>
<td class="paramname"><em>iterator</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Pin iterator. </p>
<p>Pins down the iterator to loop around current point.</p>
<p>This feature allows some search optimization. The idea is to be able to put a 'pin' into a specific place while iterating the collection and make this place a new "wrap around" place for the collection. This means that next time you iterate this collection you will start iterating from the next item and the item you got before setting pin will be the last in your iteration cycle.</p>
<p>Here is the example:</p>
<p>Assume you have two collections that you need to compare and perform some action on collection 1 based on the presence of the item in collection 2.</p><ul>
<li>Collection1 = A, B, C, D, E, F</li>
<li>Collection2 = A, C, F</li>
</ul>
<p>The usual approach is to try A from collection 1 against A, B, C from collection 2. "A" will be found right away. But to find "F" it has to be compared to "A" and "C" first. The fact that the collections are to some extent ordered can in some cases help to reduce the number of comparisons. If we found "C" in the list we can put a "pin" into the collection there causing the iterator to warp at this "pin" point. Since "D" and "E" are not in the second collection we will have to make same amount of comparisons in traditional or "pinned" case to not find them. To find "F" in pinned case there will be just one comparison.</p><ul>
<li>Traditional case = 1 + 3 + 2 + 3 + 3 + 3 = 15</li>
<li>Pinned case = 1 + 3 + 1 + 3 + 3 + 1 = 12</li>
</ul>
<p>It is a 20% comparison reduction.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">iterator</td><td>Iterator object to use. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga11e94d23399788f1d83a28db06177834"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void col_rewind_iterator </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__iterator.html">collection_iterator</a> * </td>
<td class="paramname"><em>iterator</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Rewind iterator. </p>
<p>Rewinds iterator to the current pin point which is by default the beginning of the collection until changed by <a class="el" href="group__iterfunc.html#ga62921b5add3b4646072ef5abc383e71a">col_pin_iterator</a> function.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">iterator</td><td>Iterator object to use. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.8
</small></address>
</body>
</html>
distrib
>
Mageia
>
5
>
x86_64
>
media
>
core-release
>
by-pkgid
>
36966fecacfa2685274a9735a0090042
>
files
>
46
