<!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"/>
<title>Elektra Projekt: KeySet :: Class Methods</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.1 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>KeySet :: Class Methods</h1>
<p>Methods to manipulate KeySets.
<a href="#_details">More...</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">KeySet * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a> (size_t alloc,...)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">KeySet * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#gac59e4b328245463f1451f68d5106151c">ksDup</a> (const KeySet *source)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#gaba1f1dbea191f4d7e7eb3e4296ae7d5e">ksCopy</a> (KeySet *dest, const KeySet *source)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a> (KeySet *ks)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort</a> (KeySet *ks)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#ga7474ad6b0a0fa969dbdf267ba5770eee">ksGetSize</a> (const KeySet *ks)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a> (KeySet *ks, Key *toAppend)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#ga21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend</a> (KeySet *ks, const KeySet *toAppend)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">Key * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop</a> (KeySet *ks)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind</a> (KeySet *ks)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">Key * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext</a> (KeySet *ks)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">Key * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent</a> (const KeySet *ks)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">Key * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#gae7dbf3aef70e67b5328475eb3d1f92f5">ksHead</a> (const KeySet *ks)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">Key * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#gadca442c4ab43cf532b15091d7711559e">ksTail</a> (const KeySet *ks)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">cursor_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#gaffe507ab9281c322eb16c3e992075d29">ksGetCursor</a> (const KeySet *ks)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#gad94c9ffaa3e8034564c0712fd407c345">ksSetCursor</a> (KeySet *ks, cursor_t cursor)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">Key * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup</a> (KeySet *ks, Key *key, option_t options)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">Key * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyset.html#gad2e30fb6d4739d917c5abb2ac2f9c1a1">ksLookupByName</a> (KeySet *ks, const char *name, option_t options)</td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>Methods to manipulate KeySets. </p>
<p>A KeySet is a unsorted set of keys.</p>
<p>Terminate with ksNew(0) or ksNew(20, ..., KS_END) This is because there is a list of Key* required and KS_END has the length of (Key*).</p>
<p>It can be implemented in various ways like a linked list or with a dynamically allocated array.</p>
<p>With <a class="el" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew()</a> you can create a new KeySet.</p>
<p>You can add keys with <a class="el" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey()</a> in the keyset. <a class="el" href="group__keyset.html#ga7474ad6b0a0fa969dbdf267ba5770eee">ksGetSize()</a> tells you the current size of the keyset.</p>
<p>With <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a> and <a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a> you can navigate through the keyset. Don't expect any particular order, but it is assured that you will get every key of the set.</p>
<p>KeySets have an <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">internal cursor </a>. This is used for <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> and <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a>.</p>
<p>KeySet has a fundamental meaning inside elektra. It makes it possible to get and store many keys at once inside the database. In addition to that the class can be used as high level datastructure in applications. With <a class="el" href="group__keyset.html#gad2e30fb6d4739d917c5abb2ac2f9c1a1">ksLookupByName()</a> it is possible to fetch easily specific keys out of the list of keys.</p>
<p>You can easily create and iterate keys: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <kdb.h></span>
<span class="comment">// create a new keyset with 3 keys</span>
<span class="comment">// with a hint that about 20 keys will be inside</span>
KeySet *myConfig = <a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a>(20,
<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (<span class="stringliteral">"user/name1"</span>, 0),
<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (<span class="stringliteral">"user/name2"</span>, 0),
<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (<span class="stringliteral">"user/name3"</span>, 0),
KS_END);
<span class="comment">// append a key in the keyset</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(myConfig, <a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/name4"</span>, 0));
Key *current;
<a class="code" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind</a>(myConfig);
<span class="keywordflow">while</span> ((current=<a class="code" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext</a>(myConfig))!=0) {
printf(<span class="stringliteral">"Key name is %s.\n"</span>, <a class="code" href="group__keyname.html#ga8e805c726a60da921d3736cda7813513">keyName</a> (current));
}
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a> (myConfig); <span class="comment">// delete keyset and all keys appended</span>
</pre></div> <hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga21eb9c3a14a604ee3a8bdc779232e7b7"></a><!-- doxytag: member="keyset.c::ksAppend" ref="ga21eb9c3a14a604ee3a8bdc779232e7b7" args="(KeySet *ks, const KeySet *toAppend)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t ksAppend </td>
<td>(</td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>ks</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const KeySet * </td>
<td class="paramname"> <em>toAppend</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Append all <code>toAppend</code> contained keys to the end of the <code>ks</code>.</p>
<p><code>toAppend</code> KeySet will be left unchanged.</p>
<p>Makes the keyset dirty, see <a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a>.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>the size of the KeySet after transfer </dd>
<dd>
-1 on NULL pointers </dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>the KeySet that will receive the keys </td></tr>
<tr><td valign="top"></td><td valign="top"><em>toAppend</em> </td><td>the KeySet that provides the keys that will be transfered </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey()</a>, ksInsert(), ksInsertKeys() </dd></dl>
</div>
</div>
<a class="anchor" id="gaa5a1d467a4d71041edce68ea7748ce45"></a><!-- doxytag: member="keyset.c::ksAppendKey" ref="gaa5a1d467a4d71041edce68ea7748ce45" args="(KeySet *ks, Key *toAppend)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t ksAppendKey </td>
<td>(</td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>ks</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>toAppend</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Appends a Key to the end of <code>ks</code>.</p>
<p>A pointer to the key will be stored, and not a private copy. So a future <a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel()</a> on <code>ks</code> may <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> the <code>toAppend</code> object, see <a class="el" href="group__key.html#ga4aabc4272506dd63161db2bbb42de8ae">keyGetRef()</a>.</p>
<p>The reference counter of the key will be incremented, and thus toAppend is not const.</p>
<p>The KeySet internal cursor is not moved.</p>
<p>Makes the keyset dirty, see <a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a>.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>the size of the KeySet after insertion </dd>
<dd>
-1 on NULL pointers </dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>KeySet that will receive the key </td></tr>
<tr><td valign="top"></td><td valign="top"><em>toAppend</em> </td><td>Key that will be appended to ks </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd>ksInsert(), ksInsertKeys(), <a class="el" href="group__keyset.html#ga21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a>, <a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a>, <a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel()</a> </dd>
<dd>
<a class="el" href="group__key.html#ga6970a6f254d67af7e39f8e469bb162f1">keyIncRef()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gaba1f1dbea191f4d7e7eb3e4296ae7d5e"></a><!-- doxytag: member="keyset.c::ksCopy" ref="gaba1f1dbea191f4d7e7eb3e4296ae7d5e" args="(KeySet *dest, const KeySet *source)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int ksCopy </td>
<td>(</td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>dest</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const KeySet * </td>
<td class="paramname"> <em>source</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Copy a keyset.</p>
<p>Most often you may want a duplicate of a keyset, see <a class="el" href="group__keyset.html#gac59e4b328245463f1451f68d5106151c">ksDup()</a> or append keys, see <a class="el" href="group__keyset.html#ga21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a>. But in some situations you need to copy a keyset to a existing keyset, for that this function exists.</p>
<p>You can also use it to clear a keyset when you pass a NULL pointer as <code>source</code>.</p>
<p>Note that all keys in <code>dest</code> will be deleted. Afterwards the content of the source will be added to the destination and the <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> is set properly in <code>dest</code>.</p>
<p>A flat copy is made, so the keys will not be duplicated, but there reference counter is updated, so both keysets need to be <a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel()</a>.</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> f (KeySet *ks)
{
KeySet *c = <a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a> (20, ..., KS_END);
<span class="comment">// c receives keys</span>
<a class="code" href="group__keyset.html#gaba1f1dbea191f4d7e7eb3e4296ae7d5e">ksCopy</a> (ks, c); <span class="comment">// pass the keyset to the caller</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a> (c);
} <span class="comment">// caller needs to ksDel (ks)</span>
</pre></div><dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>source</em> </td><td>has to be an initialized source KeySet or NULL </td></tr>
<tr><td valign="top"></td><td valign="top"><em>dest</em> </td><td>has to be an initialized KeySet where to write the keys </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>1 on success </dd>
<dd>
0 if dest was cleared successfully (source is NULL) </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew()</a>, <a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel()</a>, <a class="el" href="group__keyset.html#gac59e4b328245463f1451f68d5106151c">ksDup()</a> </dd>
<dd>
<a class="el" href="group__key.html#ga6a12cbbe656a1ad9f41b8c681d7a2f92">keyCopy()</a> for copying keys </dd></dl>
</div>
</div>
<a class="anchor" id="ga4287b9416912c5f2ab9c195cb74fb094"></a><!-- doxytag: member="keyset.c::ksCurrent" ref="ga4287b9416912c5f2ab9c195cb74fb094" args="(const KeySet *ks)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Key* ksCurrent </td>
<td>(</td>
<td class="paramtype">const KeySet * </td>
<td class="paramname"> <em>ks</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return the current Key.</p>
<p>The pointer is NULL if you reached the end or after <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a>.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>You must not delete the key or change the key, use <a class="el" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop()</a> if you want to delete it.</dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>the keyset object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>pointer to the Key pointed by <code>ks's</code> cursor </dd>
<dd>
0 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a>, <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a> </dd>
<dd>
kdbMonitorKeys() for a usage example </dd></dl>
</div>
</div>
<a class="anchor" id="ga27e5c16473b02a422238c8d970db7ac8"></a><!-- doxytag: member="keyset.c::ksDel" ref="ga27e5c16473b02a422238c8d970db7ac8" args="(KeySet *ks)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int ksDel </td>
<td>(</td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>ks</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>A destructor for KeySet objects.</p>
<p>Cleans all internal dynamic attributes, decrement all reference pointers to all keys and then <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> all contained Keys, and free()s the release the KeySet object memory (that was previously allocated by <a class="el" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew()</a>).</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>the keyset object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 when the keyset was freed </dd>
<dd>
-1 on null pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gac59e4b328245463f1451f68d5106151c"></a><!-- doxytag: member="keyset.c::ksDup" ref="gac59e4b328245463f1451f68d5106151c" args="(const KeySet *source)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">KeySet* ksDup </td>
<td>(</td>
<td class="paramtype">const KeySet * </td>
<td class="paramname"> <em>source</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return a duplicate of a keyset.</p>
<p>Objects created with <a class="el" href="group__keyset.html#gac59e4b328245463f1451f68d5106151c">ksDup()</a> must be destroyed with <a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel()</a>.</p>
<p>Memory will be allocated as needed for dynamic properties, so you need to <a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel()</a> the returned pointer.</p>
<p>A flat copy is made, so the keys will not be duplicated, but there reference counter is updated, so both keysets need <a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel()</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>source</em> </td><td>has to be an initializised source KeySet </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a flat copy of source on success </dd>
<dd>
0 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew()</a>, <a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel()</a> </dd>
<dd>
<a class="el" href="group__key.html#gae6ec6a60cc4b8c1463fa08623d056ce3">keyDup()</a> for <a class="el" href="group__key.html" title="Key construction and initialization methods.">Key :: Basic Methods</a> duplication </dd></dl>
</div>
</div>
<a class="anchor" id="gaffe507ab9281c322eb16c3e992075d29"></a><!-- doxytag: member="keyset.c::ksGetCursor" ref="gaffe507ab9281c322eb16c3e992075d29" args="(const KeySet *ks)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">cursor_t ksGetCursor </td>
<td>(</td>
<td class="paramtype">const KeySet * </td>
<td class="paramname"> <em>ks</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get the KeySet internal cursor.</p>
<p>Use it to get the cursor of the actual position.</p>
<dl class="warning"><dt><b>Warning:</b></dt><dd>Cursors are getting invalid when the key was <a class="el" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop()</a>ed or <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> with KDB_O_POP was used.</dd></dl>
<h2><a class="anchor" id="readahead">
Read ahead</a></h2>
<p>With the cursors it is possible to read ahead in a keyset:</p>
<div class="fragment"><pre class="fragment">cursor_t jump;
<a class="code" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind</a> (ks);
<span class="keywordflow">while</span> ((key = keyNext (ks))!=0)
{
<span class="comment">// now mark this key</span>
jump = <a class="code" href="group__keyset.html#gaffe507ab9281c322eb16c3e992075d29">ksGetCursor</a>(ks);
<span class="comment">//code..</span>
keyNext (ks); <span class="comment">// now browse on</span>
<span class="comment">// use ksCurrent(ks) to check the keys</span>
<span class="comment">//code..</span>
<span class="comment">// jump back to the position marked before</span>
<a class="code" href="group__keyset.html#gad94c9ffaa3e8034564c0712fd407c345">ksSetCursor</a>(ks, jump);
}
</pre></div><h2><a class="anchor" id="restore">
Restoring state</a></h2>
<p>It can also be used to restore the state of a keyset in a function</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> f (KeySet *ks)
{
cursor_t state = <a class="code" href="group__keyset.html#gaffe507ab9281c322eb16c3e992075d29">ksGetCursor</a>(ks);
<span class="comment">// work with keyset</span>
<span class="comment">// now bring the keyset to the state before</span>
<a class="code" href="group__keyset.html#gad94c9ffaa3e8034564c0712fd407c345">ksSetCursor</a> (ks, state);
}
</pre></div><p>It is of course possible to make the KeySet const and cast its const away to set the cursor. Another way to achieve the same is to <a class="el" href="group__keyset.html#gac59e4b328245463f1451f68d5106151c">ksDup()</a> the keyset, but it is not as efficient.</p>
<p>An invalid cursor will be returned directly after <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a>. When you set an invalid cursor <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> is 0 and <a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a> == <a class="el" href="group__keyset.html#gae7dbf3aef70e67b5328475eb3d1f92f5">ksHead()</a>.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>Only use a cursor for the same keyset which it was made for.</dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>the keyset object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a valid cursor on success </dd>
<dd>
an invalid cursor on NULL pointer or after <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a> </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a>, <a class="el" href="group__keyset.html#gad94c9ffaa3e8034564c0712fd407c345">ksSetCursor()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga7474ad6b0a0fa969dbdf267ba5770eee"></a><!-- doxytag: member="keyset.c::ksGetSize" ref="ga7474ad6b0a0fa969dbdf267ba5770eee" args="(const KeySet *ks)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t ksGetSize </td>
<td>(</td>
<td class="paramtype">const KeySet * </td>
<td class="paramname"> <em>ks</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return the number of keys that <code>ks</code> contains.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>the keyset object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the number of keys that <code>ks</code> contains. </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd>ksNew(0), <a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gae7dbf3aef70e67b5328475eb3d1f92f5"></a><!-- doxytag: member="keyset.c::ksHead" ref="gae7dbf3aef70e67b5328475eb3d1f92f5" args="(const KeySet *ks)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Key* ksHead </td>
<td>(</td>
<td class="paramtype">const KeySet * </td>
<td class="paramname"> <em>ks</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return the first key in the KeySet.</p>
<p>The KeySets cursor will not be effected.</p>
<p>If <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a>==ksHead() you know you are on the first key.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>the keyset object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the first Key of a keyset </dd>
<dd>
0 on NULL pointer or empty keyset </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#gadca442c4ab43cf532b15091d7711559e">ksTail()</a> for the last <a class="el" href="group__key.html" title="Key construction and initialization methods.">Key :: Basic Methods</a> </dd>
<dd>
<a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a>, <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> and <a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a> for iterating over the <a class="el" href="group__keyset.html" title="Methods to manipulate KeySets.">KeySet :: Class Methods</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gaa34fc43a081e6b01e4120daa6c112004"></a><!-- doxytag: member="keyset.c::ksLookup" ref="gaa34fc43a081e6b01e4120daa6c112004" args="(KeySet *ks, Key *key, option_t options)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Key* ksLookup </td>
<td>(</td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>ks</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">option_t </td>
<td class="paramname"> <em>options</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Look for a Key contained in <code>ks</code> that matches the name of the <code>key</code>.</p>
<h2><a class="anchor" id="Introduction">
Introduction</a></h2>
<p><code><a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a></code> is designed to let you work with entirely pre-loaded KeySets, so instead of <a class="el" href="group__kdbhighlevel.html#gaa62877888f0cad395898859395e6635f">kdbGetKey()</a>, key by key, the idea is to fully <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> for your application root key and process it all at once with <code><a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a></code>.</p>
<p>This function is very efficient by using binary search. Together with <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> which can you load the whole configuration with only some communication to backends you can write very effective but short code for configuration.</p>
<h2><a class="anchor" id="Usage">
Usage</a></h2>
<p>If found, <code>ks</code> internal cursor will be positioned in the matched key (also accessible by <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a>), and a pointer to the Key is returned. If not found, <code>ks</code> internal cursor will not move, and a NULL pointer is returned.</p>
<p>Cascading is done if the first character is a /. This leads to ignoring the prefix like system/ and user/. </p>
<div class="fragment"><pre class="fragment"> <span class="keywordflow">if</span> (<a class="code" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet</a>(handle, <span class="stringliteral">"user/myapp"</span>, myConfig, 0 ) == -1)
ErrorHandler (<span class="stringliteral">"Could not get Keys"</span>);
<span class="keywordflow">if</span> (<a class="code" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet</a>(handle, <span class="stringliteral">"system/myapp"</span>, myConfig, 0 ) == -1)
ErrorHandler (<span class="stringliteral">"Could not get Keys"</span>);
<span class="keywordflow">if</span> ((myKey = <a class="code" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup</a>(myConfig, key, 0)) == NULL)
ErrorHandler (<span class="stringliteral">"Could not Lookup Key"</span>);
</pre></div><p>This is the way multi user Programs should get there configuration and search after the values. It is guaranteed that more namespaces can be added easily and that all values can be set by admin and user.</p>
<h3><a class="anchor" id="KDB_O_NOALL">
KDB_O_NOALL</a></h3>
<p>When KDB_O_NOALL is set the keyset will be only searched from <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> to <a class="el" href="group__keyset.html#gadca442c4ab43cf532b15091d7711559e">ksTail()</a>. You need to <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a> the keyset yourself. <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> is always set properly after searching a key, so you can go on searching another key after the found key.</p>
<p>When KDB_O_NOALL is not set the cursor will stay untouched and all keys are considered. A much more efficient binary search will be used then.</p>
<p>So if you change keys, e.g. rename (<a class="el" href="group__keyname.html#ga7699091610e7f3f43d2949514a4b35d9">keySetName()</a>) or remove (<a class="el" href="group__keymeta.html#ga6e14e5f1de26e1318100631a149f2984">keyRemove()</a>) them make sure to sort the keyset with <a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a>. When the keyset is dirty, see ksNeedSort() it will be sorted automatically when needed.</p>
<h3><a class="anchor" id="KDB_O_POP">
KDB_O_POP</a></h3>
<p>When KDB_O_POP is set the key which was found will be <a class="el" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop()</a>ed. <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> will not be changed, only iff <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> is the searched key, then the keyset will be <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a>ed.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>Note that <a class="el" href="group__keymeta.html#ga6e14e5f1de26e1318100631a149f2984">keyRemove()</a> keys won't be found after the first time the keyset is resorted. Lookup automatically sorts the keyset, if needed, but it can't find it out when only keys are changed, not the keyset.</dd>
<dd>
Like in <a class="el" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop()</a> the popped key always needs to be <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> afterwards, even if it is appended to another keyset.</dd></dl>
<dl class="warning"><dt><b>Warning:</b></dt><dd>All cursors on the keyset will be invalid iff you use KDB_O_POP, so don't use this if you rely on a cursor, see <a class="el" href="group__keyset.html#gaffe507ab9281c322eb16c3e992075d29">ksGetCursor()</a>.</dd></dl>
<dl class="note"><dt><b>Note:</b></dt><dd>Never use <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> with KDB_O_POP and <a class="el" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey()</a> or <a class="el" href="group__keyset.html#ga21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a> together in a loop. Otherwise <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> will need to resort the keyset every iteration and spend 99.96% of the time in <a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a> (benchmarked with above 500k iterations).</dd></dl>
<p>You can solve this problem by using KDB_O_NOALL, risking you have to iterate n^2 instead of n.</p>
<p>The more elegant way is to separate the keyset you use for <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> and <a class="el" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey()</a>: </p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> f(KeySet *iterator, KeySet *lookup)
{
KeySet *append = <a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a> (<a class="code" href="group__keyset.html#ga7474ad6b0a0fa969dbdf267ba5770eee">ksGetSize</a>(lookup), KS_END);
Key *key;
Key *current;
<a class="code" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind</a>(iterator);
<span class="keywordflow">while</span> (current=<a class="code" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext</a>(iterator))
{
key = <a class="code" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup</a> (lookup, current, KDB_O_POP);
<span class="comment">// do something...</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(append, key); <span class="comment">// now append it to append, not lookup!</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (key); <span class="comment">// make sure to ALWAYS delete poped keys.</span>
}
<a class="code" href="group__keyset.html#ga21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend</a>(lookup, append);
<span class="comment">// now lookup needs to be sorted only once, append never</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a> (append);
}
</pre></div><dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>where to look for </td></tr>
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object you are looking for </td></tr>
<tr><td valign="top"></td><td valign="top"><em>options</em> </td><td>some <code>KDB_O_*</code> option bits:</p>
<ul>
<li><code>KDB_O_NOCASE</code> <br/>
Lookup ignoring case.</li>
<li><code>KDB_O_WITHOWNER</code> <br/>
Also consider correct owner.</li>
<li><code>KDB_O_NOALL</code> <br/>
Only search from <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> to end of keyset, see above text.</li>
<li><code>KDB_O_POP</code> <br/>
Pop the key which was found.</li>
<li><code>KDB_O_SORT</code> <br/>
Force sorting before searching, see <a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a>. Together with KDB_O_NOALL the search will start from beginning. </li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>pointer to the Key found, 0 otherwise </dd>
<dd>
0 on NULL pointers </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#gad2e30fb6d4739d917c5abb2ac2f9c1a1">ksLookupByName()</a> to search by a name given by a string </dd>
<dd>
<a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a>, <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a>, <a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a> for iterating over a <a class="el" href="group__keyset.html" title="Methods to manipulate KeySets.">KeySet :: Class Methods</a> </dd>
<dd>
<a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a> to understand how <a class="el" href="group__keyset.html" title="Methods to manipulate KeySets.">KeySet :: Class Methods</a> sort themself </dd></dl>
</div>
</div>
<a class="anchor" id="gad2e30fb6d4739d917c5abb2ac2f9c1a1"></a><!-- doxytag: member="keyset.c::ksLookupByName" ref="gad2e30fb6d4739d917c5abb2ac2f9c1a1" args="(KeySet *ks, const char *name, option_t options)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Key* ksLookupByName </td>
<td>(</td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>ks</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">option_t </td>
<td class="paramname"> <em>options</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Look for a Key contained in <code>ks</code> that matches <code>name</code>.</p>
<p><code><a class="el" href="group__keyset.html#gad2e30fb6d4739d917c5abb2ac2f9c1a1">ksLookupByName()</a></code> is designed to let you work with entirely pre-loaded KeySets, so instead of <a class="el" href="group__kdbhighlevel.html#gaa62877888f0cad395898859395e6635f">kdbGetKey()</a>, key by key, the idea is to fully <a class="el" href="group__kdbhighlevel.html#ga3013d5768bbcf3c34652f489151940e2">kdbGetByName()</a> for your application root key and process it all at once with <code><a class="el" href="group__keyset.html#gad2e30fb6d4739d917c5abb2ac2f9c1a1">ksLookupByName()</a></code>.</p>
<p>This function is very efficient by using binary search. Together with <a class="el" href="group__kdbhighlevel.html#ga3013d5768bbcf3c34652f489151940e2">kdbGetByName()</a> which can you load the whole configuration with only some communication to backends you can write very effective but short code for configuration.</p>
<p>If found, <code>ks</code> internal cursor will be positioned in the matched key (also accessible by <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a>), and a pointer to the Key is returned. If not found, <code>ks</code> internal cursor will not move, and a NULL pointer is returned.</p>
<h2><a class="anchor" id="cascading">
Cascading</a></h2>
<p>Cascading is done if the first character is a /. This leads to ignoring the prefix like system/ and user/. </p>
<div class="fragment"><pre class="fragment"> <span class="keywordflow">if</span> (<a class="code" href="group__kdbhighlevel.html#ga3013d5768bbcf3c34652f489151940e2">kdbGetByName</a>(handle, <span class="stringliteral">"/sw/myapp/current"</span>, myConfig, 0 ) == -1)
ErrorHandler (<span class="stringliteral">"Could not get Keys"</span>);
<span class="keywordflow">if</span> ((myKey = <a class="code" href="group__keyset.html#gad2e30fb6d4739d917c5abb2ac2f9c1a1">ksLookupByName</a> (myConfig, <span class="stringliteral">"/myapp/current/key"</span>, 0)) == NULL)
ErrorHandler (<span class="stringliteral">"Could not Lookup Key"</span>);
</pre></div><p>This is the way multi user Programs should get there configuration and search after the values. It is guaranteed that more namespaces can be added easily and that all values can be set by admin and user.</p>
<h2><a class="anchor" id="fullsearch">
Full Search</a></h2>
<p>When KDB_O_NOALL is set the keyset will be only searched from <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> to <a class="el" href="group__keyset.html#gadca442c4ab43cf532b15091d7711559e">ksTail()</a>. You need to <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a> the keyset yourself. <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> is always set properly after searching a key, so you can go on searching another key after the found key.</p>
<p>When KDB_O_NOALL is not set the cursor will stay untouched and all keys are considered. A much more efficient binary search will be used then.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>where to look for </td></tr>
<tr><td valign="top"></td><td valign="top"><em>name</em> </td><td>key name you are looking for </td></tr>
<tr><td valign="top"></td><td valign="top"><em>options</em> </td><td>some <code>KDB_O_*</code> option bits:</p>
<ul>
<li><code>KDB_O_NOCASE</code> <br/>
Lookup ignoring case.</li>
<li><code>KDB_O_WITHOWNER</code> <br/>
Also consider correct owner.</li>
<li><code>KDB_O_NOALL</code> <br/>
Only search from <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> to end of keyset, see above text.</li>
<li><code>KDB_O_POP</code> <br/>
Pop the key which was found.</li>
<li><code>KDB_O_SORT</code> <br/>
Force sorting before searching, see <a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a>. Together with KDB_O_NOALL the search will start from beginning.</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<p>Currently no options supported. </p>
<dl class="return"><dt><b>Returns:</b></dt><dd>pointer to the Key found, 0 otherwise </dd>
<dd>
0 on NULL pointers </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd>keyCompare() for very powerfull Key lookups in KeySets </dd>
<dd>
<a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a>, <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a>, <a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga671e1aaee3ae9dc13b4834a4ddbd2c3c"></a><!-- doxytag: member="keyset.c::ksNew" ref="ga671e1aaee3ae9dc13b4834a4ddbd2c3c" args="(size_t alloc,...)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">KeySet* ksNew </td>
<td>(</td>
<td class="paramtype">size_t </td>
<td class="paramname"> <em>alloc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"> <em>...</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Allocate, initialize and return a new KeySet object.</p>
<p>Objects created with <a class="el" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew()</a> must be destroyed with <a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel()</a>.</p>
<p>You can use a various long list of parameters to preload the keyset with a list of keys. Either your first and only parameter is 0 or your last parameter must be KEY_END.</p>
<p>For most uses </p>
<div class="fragment"><pre class="fragment">KeySet *keys = <a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a>(0);
<span class="comment">// work with it</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a> (keys);
</pre></div><p> goes ok, the alloc size will be 16, defined in kdbprivate.h. The alloc size will be doubled whenever size reaches alloc size, so it also performs out large keysets.</p>
<p>But if you have any clue how large your keyset may be you should read the next statements.</p>
<p>If you want a keyset with length 15 (because you know of your application that you normally need about 12 up to 14 keys), use: </p>
<div class="fragment"><pre class="fragment">KeySet * keys = <a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a> (15, KS_END);
<span class="comment">// work with it</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a> (keys);
</pre></div><p>If you start having 3 keys, and your application needs approximately 200-500 keys, you can use: </p>
<div class="fragment"><pre class="fragment">KeySet * config = <a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a> (500,
<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (<span class="stringliteral">"user/sw/app/fixedConfiguration/key1"</span>, KEY_SWITCH_VALUE, <span class="stringliteral">"value1"</span>, 0),
<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (<span class="stringliteral">"user/sw/app/fixedConfiguration/key2"</span>, KEY_SWITCH_VALUE, <span class="stringliteral">"value2"</span>, 0),
<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (<span class="stringliteral">"user/sw/app/fixedConfiguration/key3"</span>, KEY_SWITCH_VALUE, <span class="stringliteral">"value3"</span>, 0),
KS_END); <span class="comment">// don't forget the KS_END at the end!</span>
<span class="comment">// work with it</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a> (config);
</pre></div><p> Alloc size is 500, the size of the keyset will be 3 after ksNew. This means the keyset will reallocate when appending more than 497 keys.</p>
<p>The main benefit of taking a list of variant length parameters is to be able to have one C-Statement for any possible KeySet.</p>
<p>Due to ABI compatibility, the <code>KeySet</code> structure is only declared in kdb.h, and not defined. So you can only declare <code>pointers</code> to <code>KeySets</code> in your program. See <a href="http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html#AEN135">http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html#AEN135</a></p>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel()</a> to free the <a class="el" href="group__keyset.html" title="Methods to manipulate KeySets.">KeySet :: Class Methods</a> afterwards </dd>
<dd>
<a class="el" href="group__keyset.html#gac59e4b328245463f1451f68d5106151c">ksDup()</a> to duplicate an existing <a class="el" href="group__keyset.html" title="Methods to manipulate KeySets.">KeySet :: Class Methods</a> </dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>alloc</em> </td><td>gives a hint for the size how many Keys may be stored initially </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a ready to use KeySet object </dd>
<dd>
0 on memory error </dd></dl>
</div>
</div>
<a class="anchor" id="ga317321c9065b5a4b3e33fe1c399bcec9"></a><!-- doxytag: member="keyset.c::ksNext" ref="ga317321c9065b5a4b3e33fe1c399bcec9" args="(KeySet *ks)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Key* ksNext </td>
<td>(</td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>ks</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns the next Key in a KeySet.</p>
<p>KeySets have an internal cursor that can be reset with <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a>. Every time <a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a> is called the cursor is incremented and the new current Key is returned.</p>
<p>You'll get a NULL pointer if the key after the end of the KeySet was reached. It will set the cursor to the beginning of the KeySet and the next time the first key is returned.</p>
<p>The <code>ks</code> internal cursor will be changed, so it is not const.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>You must not delete or change the key, use <a class="el" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop()</a> if you want to delete it.</dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>the keyset object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the new current Key </dd>
<dd>
0 when the end is reached </dd>
<dd>
0 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a>, <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gae42530b04defb772059de0600159cf69"></a><!-- doxytag: member="keyset.c::ksPop" ref="gae42530b04defb772059de0600159cf69" args="(KeySet *ks)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Key* ksPop </td>
<td>(</td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>ks</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Remove and return the last key of <code>ks</code>.</p>
<p>The reference counter will be decremented by one.</p>
<p>The KeySets cursor will not be effected if it did not point to the popped key.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>You need to <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> the key afterwards, if you don't append it to another keyset. It has the same semantics like a key allocated with <a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> or <a class="el" href="group__key.html#gae6ec6a60cc4b8c1463fa08623d056ce3">keyDup()</a>.</dd></dl>
<div class="fragment"><pre class="fragment">ks1=<a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a>(0);
ks2=<a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a>(0);
k1=<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0); <span class="comment">// ref counter 0</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks1, k1); <span class="comment">// ref counter 1</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks2, k1); <span class="comment">// ref counter 2</span>
k1=<a class="code" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop</a> (ks1); <span class="comment">// ref counter 1</span>
k1=<a class="code" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop</a> (ks2); <span class="comment">// ref counter 0, like after keyNew()</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks1, k1); <span class="comment">// ref counter 1</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a> (ks1); <span class="comment">// key is deleted too</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a> (ks2);
*
</pre></div><dl class="return"><dt><b>Returns:</b></dt><dd>the last key of <code>ks</code> </dd>
<dd>
NULL if <code>ks</code> is empty or on NULL pointer </dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>KeySet to work with </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey()</a>, <a class="el" href="group__keyset.html#ga21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a> </dd>
<dd>
commandList() for an example </dd></dl>
</div>
</div>
<a class="anchor" id="gabe793ff51f1728e3429c84a8a9086b70"></a><!-- doxytag: member="keyset.c::ksRewind" ref="gabe793ff51f1728e3429c84a8a9086b70" args="(KeySet *ks)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int ksRewind </td>
<td>(</td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>ks</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Rewinds the KeySet internal cursor.</p>
<p>Use it to set the cursor to the beginning of the KeySet. <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> will then always return NULL afterwards. So you want to <a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a> first.</p>
<div class="fragment"><pre class="fragment"><a class="code" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind</a> (ks);
<span class="keywordflow">while</span> ((key = keyNext (ks))!=0) {}
</pre></div><dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>the keyset object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a>, <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gad94c9ffaa3e8034564c0712fd407c345"></a><!-- doxytag: member="keyset.c::ksSetCursor" ref="gad94c9ffaa3e8034564c0712fd407c345" args="(KeySet *ks, cursor_t cursor)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int ksSetCursor </td>
<td>(</td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>ks</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">cursor_t </td>
<td class="paramname"> <em>cursor</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set the KeySet internal cursor.</p>
<p>Use it to set the cursor to a stored position. <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> will then be the position which you got with.</p>
<dl class="warning"><dt><b>Warning:</b></dt><dd>Cursors may get invalid when the key was <a class="el" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop()</a>ed or <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> was used together with KDB_O_POP.</dd></dl>
<div class="fragment"><pre class="fragment">cursor_t cursor;
..
<span class="comment">// key now in any position here</span>
cursor = <a class="code" href="group__keyset.html#gaffe507ab9281c322eb16c3e992075d29">ksGetCursor</a> (ks);
<span class="keywordflow">while</span> ((key = keyNext (ks))!=0) {}
<a class="code" href="group__keyset.html#gad94c9ffaa3e8034564c0712fd407c345">ksSetCursor</a> (ks, cursor); <span class="comment">// reset state</span>
<a class="code" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent</a>(ks); <span class="comment">// in same position as before</span>
</pre></div><p>An invalid cursor will set the keyset to its beginning like <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a>. When you set an invalid cursor <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> is 0 and <a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a> == <a class="el" href="group__keyset.html#gae7dbf3aef70e67b5328475eb3d1f92f5">ksHead()</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>cursor</em> </td><td>the cursor to use </td></tr>
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>the keyset object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 when the keyset is <a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a>ed </dd>
<dd>
1 otherwise </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a>, <a class="el" href="group__keyset.html#gaffe507ab9281c322eb16c3e992075d29">ksGetCursor()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga023554d395ccf2319a3807b8b5d2530c"></a><!-- doxytag: member="keyset.c::ksSort" ref="ga023554d395ccf2319a3807b8b5d2530c" args="(KeySet *ks)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void ksSort </td>
<td>(</td>
<td class="paramtype">KeySet * </td>
<td class="paramname"> <em>ks</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Sorts a KeySet alphabetically by Key name.</p>
<p>You need <a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a> only in few cases directly.</p>
<h2><a class="anchor" id="sortlookup">
Don't need to sort before using ksLookup</a></h2>
<p>You don't need it if you just just <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> and subsequent <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a>. </p>
<div class="fragment"><pre class="fragment">KeySet *ks = <a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a>(0);
<a class="code" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet</a>(h, ks, k, 0);
<span class="comment">// ksPop(), ksAppend() and ksAppendKey() allowed here</span>
<a class="code" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup</a>(ks, s, 0); <span class="comment">// you dont need to sort ks</span>
</pre></div><p>This is because the KeySet tracks if it needs to be sorted and <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> will sort when needed.</p>
<h2><a class="anchor" id="sortiterate">
Sort when iterating</a></h2>
<p>Before you iterate over a keyset you have to sort it, if you need it in a sorted way.</p>
<p>To achieve that you can pass option_t::KDB_O_SORT to <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> and <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a>. Then you will receive a already sorted keyset over which you can iterate. </p>
<div class="fragment"><pre class="fragment">KeySet *ks = <a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a>(0);
<a class="code" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet</a>(h, ks, k, KDB_O_SORT);
<span class="comment">// no changes to keyset allowed</span>
<a class="code" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind</a>(ks);
<span class="comment">// now you can iterate over a sorted keyset</span>
</pre></div><p>Its of course also possible to use <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> once, because it will sort the keyset too.</p>
<h2><a class="anchor" id="sortkey">
Sort when changing key</a></h2>
<dl class="warning"><dt><b>Warning:</b></dt><dd>You should not use <a class="el" href="group__keyname.html#ga7699091610e7f3f43d2949514a4b35d9">keySetName()</a> or <a class="el" href="group__keymeta.html#ga6e14e5f1de26e1318100631a149f2984">keyRemove()</a> when a key belongs to a keyset. When you are doing this, you always need to <code>manually</code> sort <code>all</code> keysets where the key was before using <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> (otherwise <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> won't find that keys), <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> or <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a> methods.</dd></dl>
<p>When you change a key's name or its remove status the order which was previously correctly is then wrong. The keyset does not recognize this, so the programmer has to take care that <a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a> is called before any operation which needs a sorted keyset (which are all <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a>, all <a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> and all <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a> functions).</p>
<dl class="note"><dt><b>Note:</b></dt><dd>You can remember that easily that all functions which get options require one of the following:<ul>
<li>that you did not manipulate a keys name or a remove status</li>
<li>that you pass KDB_O_SORT when you know that you manipulated at least one key</li>
<li>that you <a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a> yourself after manipulating keys</li>
</ul>
</dd></dl>
<h2><a class="anchor" id="dirty">
Dirty KeySet</a></h2>
<p>When you use <a class="el" href="group__keyset.html#ga21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a>, <a class="el" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey()</a>, <a class="el" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop()</a> the keyset is dirty afterwards, which means that it needs to be sorted. This is done automatically using a <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> method and in ksGet() or ksSet() (All methods which accept options).</p>
<p>It won't be done if you just iterate over the keyset, so you might use a <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> or <a class="el" href="group__keyset.html#ga023554d395ccf2319a3807b8b5d2530c">ksSort()</a> first. <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> will be more efficient in that case, because it will only sort when needed. Don't pass KDB_O_NOALL (it will deactivate the sorting feature), see <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> for more information.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>KeySet to be sorted </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__kdb.html#ga37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a>, <a class="el" href="group__kdb.html#ga953cf29721e6000c2516cd6b5d36f571">kdbSet()</a>, <a class="el" href="group__keyset.html#gaa34fc43a081e6b01e4120daa6c112004">ksLookup()</a> for some functions which may need sorting before they are called. (All functions which take options as arguments) </dd>
<dd>
<a class="el" href="group__keyname.html#ga7699091610e7f3f43d2949514a4b35d9">keySetName()</a>, <a class="el" href="group__keyname.html#ga6e804bd453f98c28b0ff51430d1df407">keySetBaseName()</a>, <a class="el" href="group__keyname.html#gaa942091fc4bd5c2699e49ddc50829524">keyAddBaseName()</a> and <a class="el" href="group__keymeta.html#ga6e14e5f1de26e1318100631a149f2984">keyRemove()</a> for all methods which change the sorting state where the <a class="el" href="group__keyset.html" title="Methods to manipulate KeySets.">KeySet :: Class Methods</a> can't track the change. </dd>
<dd>
<a class="el" href="group__keyset.html#ga21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a>, <a class="el" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey()</a>, <a class="el" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop()</a> for all methods which make a <a class="el" href="group__keyset.html" title="Methods to manipulate KeySets.">KeySet :: Class Methods</a> dirty. </dd></dl>
</div>
</div>
<a class="anchor" id="gadca442c4ab43cf532b15091d7711559e"></a><!-- doxytag: member="keyset.c::ksTail" ref="gadca442c4ab43cf532b15091d7711559e" args="(const KeySet *ks)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Key* ksTail </td>
<td>(</td>
<td class="paramtype">const KeySet * </td>
<td class="paramname"> <em>ks</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return the last key in the KeySet.</p>
<p>The KeySets cursor will not be effected.</p>
<p>If <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a>==ksTail() you know you are on the last key. <a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a> will return a NULL pointer afterwards.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ks</em> </td><td>the keyset object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the last Key of a keyset </dd>
<dd>
0 on NULL pointer or empty keyset </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#gae7dbf3aef70e67b5328475eb3d1f92f5">ksHead()</a> for the first <a class="el" href="group__key.html" title="Key construction and initialization methods.">Key :: Basic Methods</a> </dd>
<dd>
<a class="el" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind()</a>, <a class="el" href="group__keyset.html#ga4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> and <a class="el" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a> for iterating over the <a class="el" href="group__keyset.html" title="Methods to manipulate KeySets.">KeySet :: Class Methods</a> </dd></dl>
</div>
</div>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on 8 Nov 2009 for Elektra Projekt by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
