\hypertarget{group__keyset}{}\doxysection{Key\+Set}
\label{group__keyset}\index{KeySet@{KeySet}}


Methods to manipulate Key\+Sets.  


\doxysubsection*{Macros}
\begin{DoxyCompactItemize}
\item 
\#define \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\+\_\+\+END}}~((Key $\ast$) 0)
\begin{DoxyCompactList}\small\item\em End of a list of keys. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Enumerations}
\begin{DoxyCompactItemize}
\item 
enum \mbox{\hyperlink{group__keyset_gada05f4bbf46fde81d0d57df86e73d914}{elektra\+Lookup\+Flags}} \{ \mbox{\hyperlink{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a00738455e0ae843c8720809d8287f370}{KDB\+\_\+\+O\+\_\+\+NONE}} = 0
, \mbox{\hyperlink{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a66a5380c120f25f28f49848c4a863ead}{KDB\+\_\+\+O\+\_\+\+DEL}} = 1
, \mbox{\hyperlink{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a52fb5f2cc86773d393da62bebebf7984}{KDB\+\_\+\+O\+\_\+\+POP}} = 1 $<$$<$ 1
 \}
\begin{DoxyCompactList}\small\item\em Options to change the default behavior of \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} functions. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
Key\+Set $\ast$ \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New}} (size\+\_\+t alloc,...)
\begin{DoxyCompactList}\small\item\em Allocate, initialize and return a new Key\+Set object. \end{DoxyCompactList}\item 
Key\+Set $\ast$ \mbox{\hyperlink{group__keyset_ga4ff760f56693b51ab785ed7ce628e649}{ks\+VNew}} (size\+\_\+t alloc, va\+\_\+list va)
\begin{DoxyCompactList}\small\item\em Allocate, initialize and return a new Key\+Set object. \end{DoxyCompactList}\item 
Key\+Set $\ast$ \mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ks\+Dup}} (const Key\+Set $\ast$source)
\begin{DoxyCompactList}\small\item\em Return a duplicate of a Key\+Set. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keyset_gaba1f1dbea191f4d7e7eb3e4296ae7d5e}{ks\+Copy}} (Key\+Set $\ast$dest, const Key\+Set $\ast$source)
\begin{DoxyCompactList}\small\item\em Replace the content of a Key\+Set with another one. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del}} (Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em A destructor for Key\+Set objects. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keyset_ga304d5770a30ef760d1b6d4bcd13f1ece}{ks\+Clear}} (Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Empties a Key\+Set. \end{DoxyCompactList}\item 
uint16\+\_\+t \mbox{\hyperlink{group__keyset_ga5a656d35588d0c2f35c1e58653e46791}{ks\+Inc\+Ref}} (Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Increment the reference counter of a Key\+Set object. \end{DoxyCompactList}\item 
uint16\+\_\+t \mbox{\hyperlink{group__keyset_gae27a4c9538a99d9de30f57ef6a8f3fc2}{ks\+Dec\+Ref}} (Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Decrement the reference counter of a Key\+Set object. \end{DoxyCompactList}\item 
uint16\+\_\+t \mbox{\hyperlink{group__keyset_gad40b98651a293a255cd6a7b9e4bd7b71}{ks\+Get\+Ref}} (const Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Return the current reference counter value of a Key\+Set object. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyset_ga7474ad6b0a0fa969dbdf267ba5770eee}{ks\+Get\+Size}} (const Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Return the number of Keys that {\ttfamily ks} contains. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyset_gac59817ac58072708092fbeb87600beb1}{ks\+Search}} (const Key\+Set $\ast$ks, const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Search in a key set, either yielding the actual index of the key, if the ley has been found within the key set, or a negative value indicating the insertion index of the key, if the key would be inserted. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key}} (Key\+Set $\ast$ks, Key $\ast$to\+Append)
\begin{DoxyCompactList}\small\item\em Appends a Key to the end of {\ttfamily ks}. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyset_ga21eb9c3a14a604ee3a8bdc779232e7b7}{ks\+Append}} (Key\+Set $\ast$ks, const Key\+Set $\ast$to\+Append)
\begin{DoxyCompactList}\small\item\em Append all Keys in {\ttfamily to\+Append} to the end of the Key\+Set {\ttfamily ks}. \end{DoxyCompactList}\item 
ssize\+\_\+t \mbox{\hyperlink{group__keyset_gaa9b59d3a7ccd58511b562755454d1fae}{ks\+Rename}} (Key\+Set $\ast$ks, const Key $\ast$root, const Key $\ast$new\+Root)
\begin{DoxyCompactList}\small\item\em Moves all keys below {\ttfamily root} to below {\ttfamily new\+Root}. \end{DoxyCompactList}\item 
elektra\+Cursor \mbox{\hyperlink{group__keyset_gaf29e567a3a733160303a452cc2366e69}{ks\+Find\+Hierarchy}} (const Key\+Set $\ast$ks, const Key $\ast$root, elektra\+Cursor $\ast$end)
\begin{DoxyCompactList}\small\item\em Searches for the start and optionally end of the key hierachy rooted at {\ttfamily root} in {\ttfamily ks}. \end{DoxyCompactList}\item 
Key\+Set $\ast$ \mbox{\hyperlink{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}{ks\+Cut}} (Key\+Set $\ast$ks, const Key $\ast$cutpoint)
\begin{DoxyCompactList}\small\item\em Cuts out all Keys from Key\+Set {\ttfamily ks} that are below or at {\ttfamily cutpoint}. \end{DoxyCompactList}\item 
Key $\ast$ \mbox{\hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{ks\+Pop}} (Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Remove and return the last Key of {\ttfamily ks}. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind}} (Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Rewinds the Key\+Set internal cursor. \end{DoxyCompactList}\item 
Key $\ast$ \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next}} (Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Returns the next Key in a Key\+Set. \end{DoxyCompactList}\item 
Key $\ast$ \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current}} (const Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Return the current Key. \end{DoxyCompactList}\item 
Key $\ast$ \mbox{\hyperlink{group__keyset_gae7dbf3aef70e67b5328475eb3d1f92f5}{ks\+Head}} (const Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Return the first Key in the Key\+Set. \end{DoxyCompactList}\item 
Key $\ast$ \mbox{\hyperlink{group__keyset_gadca442c4ab43cf532b15091d7711559e}{ks\+Tail}} (const Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Return the last Key in the Key\+Set. \end{DoxyCompactList}\item 
elektra\+Cursor \mbox{\hyperlink{group__keyset_gace0444eb8ec958a429794f8586fc72e7}{ks\+Get\+Cursor}} (const Key\+Set $\ast$ks)
\begin{DoxyCompactList}\small\item\em Get the internal cursor of the Key\+Set. \end{DoxyCompactList}\item 
Key $\ast$ \mbox{\hyperlink{group__keyset_ga12b8fefaa20546e4790d60338b0db836}{ks\+At\+Cursor}} (Key\+Set $\ast$ks, elektra\+Cursor pos)
\begin{DoxyCompactList}\small\item\em Return Key at given position {\ttfamily pos}. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keyset_ga28b2a7d13c620b3c9d4815a0608c738f}{ks\+Set\+Cursor}} (Key\+Set $\ast$ks, elektra\+Cursor cursor)
\begin{DoxyCompactList}\small\item\em Set the Key\+Set internal cursor to {\ttfamily cursor}. \end{DoxyCompactList}\item 
Key $\ast$ \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup}} (Key\+Set $\ast$ks, Key $\ast$key, \mbox{\hyperlink{group__keyset_gada05f4bbf46fde81d0d57df86e73d914}{elektra\+Lookup\+Flags}} options)
\begin{DoxyCompactList}\small\item\em Look for a Key contained in {\ttfamily ks} that matches the name of the {\ttfamily key}. \end{DoxyCompactList}\item 
Key $\ast$ \mbox{\hyperlink{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}{ks\+Lookup\+By\+Name}} (Key\+Set $\ast$ks, const char $\ast$name, \mbox{\hyperlink{group__keyset_gada05f4bbf46fde81d0d57df86e73d914}{elektra\+Lookup\+Flags}} options)
\begin{DoxyCompactList}\small\item\em Convenience method to look for a Key contained in {\ttfamily ks} with name {\ttfamily name}. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Methods to manipulate Key\+Sets. 

A Key\+Set is a set of keys.

Most important properties of a Key\+Set\+:


\begin{DoxyItemize}
\item Allows us to iterate over all keys (in any depth)
\item Iteration is always sorted
\item Fast key lookup
\item A Key may be shared among many Key\+Sets.
\end{DoxyItemize}

The most important methods of Key\+Set\+:


\begin{DoxyItemize}
\item With \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}} you can create a new Key\+Set.
\item You can append keys with \mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()}} or with \mbox{\hyperlink{group__keyset_ga21eb9c3a14a604ee3a8bdc779232e7b7}{ks\+Append()}} you can append a whole keyset.
\item Using \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} you can lookup (or pop with \mbox{\hyperlink{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a52fb5f2cc86773d393da62bebebf7984}{KDB\+\_\+\+O\+\_\+\+POP}}) a key.
\item With \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}} and \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} you can iterate through the keyset. Be assured that you will get every key of the set in a stable order (parents before children).
\end{DoxyItemize}

\begin{DoxyNote}{Note}
Because the key is not copied, also the pointer to the current metadata \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}} will be shared.
\end{DoxyNote}
Key\+Sets have an \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{internal cursor }}. Methods should avoid to change this cursor, unless they want to communicate something with it. The internal cursor is used\+:


\begin{DoxyItemize}
\item in \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}}\+: points to the found key
\item in \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}}\+: points to the key which caused an error
\end{DoxyItemize}

Key\+Set is the most important data structure in 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 and it can be used in plugins to manipulate or check configuration.

With \mbox{\hyperlink{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}{ks\+Lookup\+By\+Name()}} it is possible to fetch easily specific keys out of the list of keys.

You can easily create and iterate keys\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{comment}{// create a new keyset with 3 keys}}
\DoxyCodeLine{\textcolor{comment}{// with a hint that about 20 keys will be inside}}
\DoxyCodeLine{KeySet * myConfig = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (20, \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/name1"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}), \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/name2"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}), \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/name3"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}), \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{\textcolor{comment}{// append a key in the keyset}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}} (myConfig, \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/name4"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}));}
\DoxyCodeLine{}
\DoxyCodeLine{Key * current;}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ksRewind}} (myConfig);}
\DoxyCodeLine{\textcolor{keywordflow}{while} ((current = \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ksNext}} (myConfig)) != 0)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        printf (\textcolor{stringliteral}{"{}Key name is \%s.\(\backslash\)n"{}}, \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (current));}
\DoxyCodeLine{\}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (myConfig); \textcolor{comment}{// delete keyset and all keys appended}}

\end{DoxyCodeInclude}


\doxysubsection{Macro Definition Documentation}
\mbox{\Hypertarget{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}\label{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}} 
\index{KeySet@{KeySet}!KS\_END@{KS\_END}}
\index{KS\_END@{KS\_END}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{KS\_END}{KS\_END}}
{\footnotesize\ttfamily \#define KS\+\_\+\+END~((Key $\ast$) 0)}



End of a list of keys. 

Use this macro to define the end of a variable-\/length list of keys.

\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}} and \mbox{\hyperlink{group__keyset_ga4ff760f56693b51ab785ed7ce628e649}{ks\+VNew()}} 
\end{DoxySeeAlso}


\doxysubsection{Enumeration Type Documentation}
\mbox{\Hypertarget{group__keyset_gada05f4bbf46fde81d0d57df86e73d914}\label{group__keyset_gada05f4bbf46fde81d0d57df86e73d914}} 
\index{KeySet@{KeySet}!elektraLookupFlags@{elektraLookupFlags}}
\index{elektraLookupFlags@{elektraLookupFlags}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{elektraLookupFlags}{elektraLookupFlags}}
{\footnotesize\ttfamily enum \mbox{\hyperlink{group__keyset_gada05f4bbf46fde81d0d57df86e73d914}{elektra\+Lookup\+Flags}}}



Options to change the default behavior of \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} functions. 

These options can be ORed. That is the $\vert$-\/\+Operator in C.

\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}, \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} 
\end{DoxySeeAlso}
\begin{DoxyEnumFields}{Enumerator}
\raisebox{\heightof{T}}[0pt][0pt]{\index{KDB\_O\_NONE@{KDB\_O\_NONE}!KeySet@{KeySet}}\index{KeySet@{KeySet}!KDB\_O\_NONE@{KDB\_O\_NONE}}}\mbox{\Hypertarget{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a00738455e0ae843c8720809d8287f370}\label{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a00738455e0ae843c8720809d8287f370}} 
KDB\+\_\+\+O\+\_\+\+NONE&No Option set. \begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} 
\end{DoxySeeAlso}
\\
\hline

\raisebox{\heightof{T}}[0pt][0pt]{\index{KDB\_O\_DEL@{KDB\_O\_DEL}!KeySet@{KeySet}}\index{KeySet@{KeySet}!KDB\_O\_DEL@{KDB\_O\_DEL}}}\mbox{\Hypertarget{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a66a5380c120f25f28f49848c4a863ead}\label{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a66a5380c120f25f28f49848c4a863ead}} 
KDB\+\_\+\+O\+\_\+\+DEL&Delete parent\+Key key in \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}}. \begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} 
\end{DoxySeeAlso}
\\
\hline

\raisebox{\heightof{T}}[0pt][0pt]{\index{KDB\_O\_POP@{KDB\_O\_POP}!KeySet@{KeySet}}\index{KeySet@{KeySet}!KDB\_O\_POP@{KDB\_O\_POP}}}\mbox{\Hypertarget{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a52fb5f2cc86773d393da62bebebf7984}\label{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a52fb5f2cc86773d393da62bebebf7984}} 
KDB\+\_\+\+O\+\_\+\+POP&Pop Parent out of keyset key in \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}}. \begin{DoxyVerb}   @see ksPop().
\end{DoxyVerb}
 \\
\hline

\end{DoxyEnumFields}


\doxysubsection{Function Documentation}
\mbox{\Hypertarget{group__keyset_ga21eb9c3a14a604ee3a8bdc779232e7b7}\label{group__keyset_ga21eb9c3a14a604ee3a8bdc779232e7b7}} 
\index{KeySet@{KeySet}!ksAppend@{ksAppend}}
\index{ksAppend@{ksAppend}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksAppend()}{ksAppend()}}
{\footnotesize\ttfamily ssize\+\_\+t ks\+Append (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks,  }\item[{const Key\+Set $\ast$}]{to\+Append }\end{DoxyParamCaption})}



Append all Keys in {\ttfamily to\+Append} to the end of the Key\+Set {\ttfamily ks}. 

{\ttfamily to\+Append} Key\+Set will be left unchanged.

If a Key is both in {\ttfamily to\+Append} and {\ttfamily ks}, the Key in {\ttfamily ks} will be overwritten.

\begin{DoxyNote}{Note}
Because the key is not copied, also the pointer to the current metadata \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}} will be shared.
\end{DoxyNote}
\begin{DoxyPostcond}{Postcondition}
Sorted Key\+Set ks with all Keys it had before and additionally the Keys from to\+Append
\end{DoxyPostcond}

\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set that will receive the Keys \\
\hline
{\em to\+Append} & the Key\+Set that provides the Keys that will be transferred\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the size of the Key\+Set {\ttfamily ks} after transfer 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & on NULL pointers\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()}} 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}\label{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}} 
\index{KeySet@{KeySet}!ksAppendKey@{ksAppendKey}}
\index{ksAppendKey@{ksAppendKey}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksAppendKey()}{ksAppendKey()}}
{\footnotesize\ttfamily ssize\+\_\+t ks\+Append\+Key (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks,  }\item[{Key $\ast$}]{to\+Append }\end{DoxyParamCaption})}



Appends a Key to the end of {\ttfamily ks}. 

Hands the ownership of the Key {\ttfamily to\+Append} to the Key\+Set {\ttfamily ks}. ks\+Del(ks) uses key\+Del(k) to delete every Key unless it got its reference counter incremented by \mbox{\hyperlink{group__key_ga0b477b584c8be68519a8d92f90355136}{key\+Inc\+Ref()}}, e.\+g. by another Key\+Set that contains this Key.

The reference counter of the Key will be incremented to indicate this ownership, and thus {\ttfamily to\+Append} is not const.

\begin{DoxyNote}{Note}
Because the key is not copied, also the pointer to the current metadata \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}} will be shared.
\end{DoxyNote}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__key_ga0d82ce48529821aa43d82c035ba30c4f}{key\+Get\+Ref()}}
\end{DoxySeeAlso}
If the Key\textquotesingle{}s name already exists in the Key\+Set, it will be replaced with the new Key.

\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()}} will also lock the Key\textquotesingle{}s name from {\ttfamily to\+Append}. This is necessary so that the order of the Key\+Set cannot be destroyed via calls to \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}}.

The Key\+Set internal cursor will be set to the new Key.

It is safe to directly append newly created Keys\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{KeySet * ks = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (1, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}} (ks, \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/my/new/key"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}));}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (ks);}
\DoxyCodeLine{\textcolor{comment}{// key deleted, too!}}

\end{DoxyCodeInclude}
 If you want the key to outlive the Key\+Set, make sure to do proper ref counting\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{KeySet * ks = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (1, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{Key * k = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/ref/key"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga0b477b584c8be68519a8d92f90355136}{keyIncRef}} (k);}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}} (ks, k);}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (ks);}
\DoxyCodeLine{\textcolor{comment}{// now we still can work with the key k!}}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga0c4d031ab6ee02cf884c64e28a2ad151}{keyDecRef}} (k);}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (k);}

\end{DoxyCodeInclude}
 You can duplicate the Key to avoid aliasing, but then the Key in the Key\+Set has another identity\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{KeySet * ks = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (1, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{Key * k = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/ref/key"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}} (ks, keyDup (k, \mbox{\hyperlink{group__key_gga9ff42b1e9a97222562bfda3dd1f8c735a3e04e17514f102f1e9217308d44e7612}{KEY\_CP\_ALL}}));}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (ks);}
\DoxyCodeLine{\textcolor{comment}{// now we still can work with the key k!}}
\DoxyCodeLine{\mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (k);}

\end{DoxyCodeInclude}
 
\begin{DoxyParams}{Parameters}
{\em ks} & Key\+Set where {\ttfamily to\+Append} should be append \\
\hline
{\em to\+Append} & Key that will be appended to {\ttfamily ks} or deleted\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the size of the Key\+Set after appending 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & on NULL pointers \\
\hline
{\em -\/1} & if appending failed (only on memory problems). The Key will be deleted then.\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga21eb9c3a14a604ee3a8bdc779232e7b7}{ks\+Append()}} for appending a Key\+Set to another Key\+Set 

\mbox{\hyperlink{group__key_ga0b477b584c8be68519a8d92f90355136}{key\+Inc\+Ref()}} for manually increasing a Key\textquotesingle{}s reference counter 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga12b8fefaa20546e4790d60338b0db836}\label{group__keyset_ga12b8fefaa20546e4790d60338b0db836}} 
\index{KeySet@{KeySet}!ksAtCursor@{ksAtCursor}}
\index{ksAtCursor@{ksAtCursor}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksAtCursor()}{ksAtCursor()}}
{\footnotesize\ttfamily Key$\ast$ ks\+At\+Cursor (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks,  }\item[{elektra\+Cursor}]{pos }\end{DoxyParamCaption})}



Return Key at given position {\ttfamily pos}. 

The position is a number starting from 0.


\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set to get the Key from \\
\hline
{\em pos} & the position of the Key that should be retrieved\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the Key at the cursor {\ttfamily pos} on success 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em NULL} & on NULL pointer, negative cursor position or a position that does not lie within the Key\+Set {\ttfamily ks} \\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gace0444eb8ec958a429794f8586fc72e7}{ks\+Get\+Cursor()}} for getting the cursor at the current position 

\mbox{\hyperlink{group__keyset_ga28b2a7d13c620b3c9d4815a0608c738f}{ks\+Set\+Cursor()}} for setting the cursor to a specific position 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga304d5770a30ef760d1b6d4bcd13f1ece}\label{group__keyset_ga304d5770a30ef760d1b6d4bcd13f1ece}} 
\index{KeySet@{KeySet}!ksClear@{ksClear}}
\index{ksClear@{ksClear}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksClear()}{ksClear()}}
{\footnotesize\ttfamily int ks\+Clear (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Empties a Key\+Set. 

This function
\begin{DoxyItemize}
\item {\bfseries{does not}} check or modify the reference count of {\ttfamily ks}
\item decrements the reference count of all keys contained in {\ttfamily ks}
\item deletes all keys that where only referenced by {\ttfamily ks}
\item resets size of {\ttfamily ks} to 0
\end{DoxyItemize}


\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set to clear\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & on success \\
\hline
{\em -\/1} & on failure (memory) or ks == NULL \\
\hline
\end{DoxyRetVals}
\mbox{\Hypertarget{group__keyset_gaba1f1dbea191f4d7e7eb3e4296ae7d5e}\label{group__keyset_gaba1f1dbea191f4d7e7eb3e4296ae7d5e}} 
\index{KeySet@{KeySet}!ksCopy@{ksCopy}}
\index{ksCopy@{ksCopy}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksCopy()}{ksCopy()}}
{\footnotesize\ttfamily int ks\+Copy (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{dest,  }\item[{const Key\+Set $\ast$}]{source }\end{DoxyParamCaption})}



Replace the content of a Key\+Set with another one. 

Most often you may want a duplicate of a Key\+Set, see \mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ks\+Dup()}} or append keys, see \mbox{\hyperlink{group__keyset_ga21eb9c3a14a604ee3a8bdc779232e7b7}{ks\+Append()}}. In some situations you need to copy Keys from a Key\+Set to another Key\+Set, for which this function exists.

\begin{DoxyNote}{Note}
You can also use it to clear a Key\+Set when you pass a NULL pointer as {\ttfamily source}.
\end{DoxyNote}
\begin{DoxyParagraph}{Implementation\+:}
First all Keys in {\ttfamily dest} will be deleted. Afterwards the content of {\ttfamily source} will be added to the destination and \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} will be set properly in {\ttfamily dest}.
\end{DoxyParagraph}
A flat copy is made, so Keys will not be duplicated, but their reference counter is updated, so both Key\+Sets need to be deleted via \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}}.

\begin{DoxyNote}{Note}
Because the key is not copied, also the pointer to the current metadata \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{key\+Next\+Meta()}} will be shared.
\end{DoxyNote}

\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int} f (KeySet *ks)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        KeySet *c = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (20, ..., \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{        \textcolor{comment}{// c receives keys}}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_gaba1f1dbea191f4d7e7eb3e4296ae7d5e}{ksCopy}} (ks, c); \textcolor{comment}{// pass the KeySet to the caller}}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (c);}
\DoxyCodeLine{\}       \textcolor{comment}{// caller needs to ksDel (ks)}}

\end{DoxyCode}



\begin{DoxyParams}{Parameters}
{\em source} & an initialized Key\+Set or NULL \\
\hline
{\em dest} & an initialized Key\+Set, where the Keys from {\ttfamily source} get copied to\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & on success \\
\hline
{\em 0} & if {\ttfamily dest} was cleared successfully ({\ttfamily source} is NULL) \\
\hline
{\em -\/1} & when {\ttfamily dest} is a NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}} for creating a new Key\+Set 

\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}} for deleting an existing Key\+Set 

\mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ks\+Dup()}} for duplicating an existing Key\+Set 

\mbox{\hyperlink{group__key_ga505575ebef060066984fe0f590081e37}{key\+Copy()}} for copying Keys 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}\label{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}} 
\index{KeySet@{KeySet}!ksCurrent@{ksCurrent}}
\index{ksCurrent@{ksCurrent}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksCurrent()}{ksCurrent()}}
{\footnotesize\ttfamily Key$\ast$ ks\+Current (\begin{DoxyParamCaption}\item[{const Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Return the current Key. 

The returned pointer is NULL if you reached the end or after \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}}.

\begin{DoxyNote}{Note}
You must not delete the Key or change the Key, use \mbox{\hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{ks\+Pop()}} if you want to delete it.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set object to get the current Key from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
pointer to the Key pointed by {\ttfamily ks\textquotesingle{}s} cursor 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} to get the next Key in the Key\+Set 

\mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}} for resetting the internal cursor of the Key\+Set 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}\label{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}} 
\index{KeySet@{KeySet}!ksCut@{ksCut}}
\index{ksCut@{ksCut}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksCut()}{ksCut()}}
{\footnotesize\ttfamily Key\+Set$\ast$ ks\+Cut (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks,  }\item[{const Key $\ast$}]{cutpoint }\end{DoxyParamCaption})}



Cuts out all Keys from Key\+Set {\ttfamily ks} that are below or at {\ttfamily cutpoint}. 

Searches for the {\ttfamily cutpoint} inside the Key\+Set {\ttfamily ks}. If found, it cuts out this Key and everything which is below (see \mbox{\hyperlink{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}{key\+Is\+Below()}}) this Key. These Keys will be missing in the keyset {\ttfamily ks}. Instead, they will be moved to the returned Key\+Set. If {\ttfamily cutpoint} is not found an empty Key\+Set is returned and {\ttfamily ks} is not changed.

The cursor will stay at the same Key as it was before. If the cursor was inside the region of cut (moved) Keys, the cursor will be set to the Key before the {\ttfamily cutpoint}.

If you use \mbox{\hyperlink{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}{ks\+Cut()}} on a Key\+Set you got from \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} and plan to use \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} later, make sure that you keep all Keys that should not be removed permanently. You have to keep the Key\+Set that was returned and the Key\+Set {\ttfamily ks}.

\begin{DoxyParagraph}{Example\+:}

\end{DoxyParagraph}
You have the keyset {\ttfamily ks\+:} 
\begin{DoxyItemize}
\item {\ttfamily system\+:/mountpoint/interest} 
\item {\ttfamily system\+:/mountpoint/interest/folder} 
\item {\ttfamily system\+:/mountpoint/interest/folder/key1} 
\item {\ttfamily system\+:/mountpoint/interest/folder/key2} 
\item {\ttfamily system\+:/mountpoint/other/key1} 
\end{DoxyItemize}

When you use 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        Key * parentKey = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}system:/mountpoint/interest"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{        KDB * \mbox{\hyperlink{namespacekdb}{kdb}} = \mbox{\hyperlink{group__kdb_ga844e1299a84c3fbf1d3a905c5c893ba5}{kdbOpen}} (NULL, parentKey);}
\DoxyCodeLine{        KeySet * ks = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (0, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}} (\mbox{\hyperlink{namespacekdb}{kdb}}, ks, parentKey);}
\DoxyCodeLine{        KeySet * returned = \mbox{\hyperlink{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}{ksCut}} (ks, parentKey);}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdbSet}} (\mbox{\hyperlink{namespacekdb}{kdb}}, ks, parentKey); \textcolor{comment}{// all keys below cutpoint are now removed}}
\DoxyCodeLine{        \mbox{\hyperlink{group__kdb_gadb54dc9fda17ee07deb9444df745c96f}{kdbClose}} (\mbox{\hyperlink{namespacekdb}{kdb}}, parentKey);}

\end{DoxyCodeInclude}
 Then in {\ttfamily returned} are\+:
\begin{DoxyItemize}
\item {\ttfamily system\+:/mountpoint/interest} 
\item {\ttfamily system\+:/mountpoint/interest/folder} 
\item {\ttfamily system\+:/mountpoint/interest/folder/key1} 
\item {\ttfamily system\+:/mountpoint/interest/folder/key2} 
\end{DoxyItemize}

And in {\ttfamily ks} are\+:
\begin{DoxyItemize}
\item {\ttfamily system\+:/mountpoint/other/key1} 
\end{DoxyItemize}

So \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} permanently removes all keys at or below {\ttfamily system\+:/mountpoint/interest}.


\begin{DoxyParams}{Parameters}
{\em ks} & the Keyset to cut. It will be modified by removing all Keys at or below the cutpoint. \\
\hline
{\em cutpoint} & the point where to cut out the Keyset\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a new allocated Key\+Set which needs to deleted with \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}}. The Key\+Set consists of all Keys (of the original Key\+Set ks) below the cutpoint. If the Key cutpoint exists, it will also be appended. 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & on NULL pointers, no Key name or allocation problems\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} for an explanation on why you might get more Keys than you requested. 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_gae27a4c9538a99d9de30f57ef6a8f3fc2}\label{group__keyset_gae27a4c9538a99d9de30f57ef6a8f3fc2}} 
\index{KeySet@{KeySet}!ksDecRef@{ksDecRef}}
\index{ksDecRef@{ksDecRef}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksDecRef()}{ksDecRef()}}
{\footnotesize\ttfamily uint16\+\_\+t ks\+Dec\+Ref (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Decrement the reference counter of a Key\+Set object. 

As long as the reference counter is non-\/zero, {\ttfamily \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}}} operations on {\ttfamily key} will be a no-\/op and return an error code.


\begin{DoxyParams}{Parameters}
{\em key} & the Key\+Set object whose reference counter should get decreased\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the updated value of the reference counter 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em UINT16\+\_\+\+MAX} & on NULL pointer \\
\hline
{\em 0} & when the reference counter already was the minimum value 0, the reference counter will not be modified in this case\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gad40b98651a293a255cd6a7b9e4bd7b71}{ks\+Get\+Ref()}} to retrieve the current reference count 

\mbox{\hyperlink{group__keyset_ga5a656d35588d0c2f35c1e58653e46791}{ks\+Inc\+Ref()}} for increasing the reference counter and for a more complete explanation of the reference counting system 

\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}} for deleting a Key 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}\label{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}} 
\index{KeySet@{KeySet}!ksDel@{ksDel}}
\index{ksDel@{ksDel}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksDel()}{ksDel()}}
{\footnotesize\ttfamily int ks\+Del (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



A destructor for Key\+Set objects. 

Every Key\+Set created by \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}} must be deleted with \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}}.

When the reference counter of {\ttfamily ks} is non-\/zero, this function will do nothing and simply return the current value of the reference counter.

It is therefore safe to call {\ttfamily ks\+Del (ks)} on any {\ttfamily Key\+Set $\ast$ ks}.


\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set object to delete\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & when the Key\+Set was freed \\
\hline
{\em -\/1} & on NULL pointers \\
\hline
\end{DoxyRetVals}
\begin{DoxyReturn}{Returns}
the value of the reference counter, if it was non-\/zero
\end{DoxyReturn}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}} for creating a new Key\+Set 

\mbox{\hyperlink{group__keyset_ga5a656d35588d0c2f35c1e58653e46791}{ks\+Inc\+Ref()}} for more information about the reference counter 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_gac59e4b328245463f1451f68d5106151c}\label{group__keyset_gac59e4b328245463f1451f68d5106151c}} 
\index{KeySet@{KeySet}!ksDup@{ksDup}}
\index{ksDup@{ksDup}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksDup()}{ksDup()}}
{\footnotesize\ttfamily Key\+Set$\ast$ ks\+Dup (\begin{DoxyParamCaption}\item[{const Key\+Set $\ast$}]{source }\end{DoxyParamCaption})}



Return a duplicate of a Key\+Set. 

Objects created with \mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ks\+Dup()}} must be destroyed with \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}}.

Memory will be allocated as needed for dynamic properties, so you need to \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}} the returned pointer.

A flat copy is made, so the Keys will not be duplicated, but their reference counter is updated, so both Key\+Sets need to be deleted via \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}}.


\begin{DoxyParams}{Parameters}
{\em source} & has to be an initialized Key\+Set\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a flat copy of source on success 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}} for creating a new Key\+Set 

\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}} for deleting a Key\+Set 

key\+Dup() for Key duplication 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_gaf29e567a3a733160303a452cc2366e69}\label{group__keyset_gaf29e567a3a733160303a452cc2366e69}} 
\index{KeySet@{KeySet}!ksFindHierarchy@{ksFindHierarchy}}
\index{ksFindHierarchy@{ksFindHierarchy}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksFindHierarchy()}{ksFindHierarchy()}}
{\footnotesize\ttfamily elektra\+Cursor ks\+Find\+Hierarchy (\begin{DoxyParamCaption}\item[{const Key\+Set $\ast$}]{ks,  }\item[{const Key $\ast$}]{root,  }\item[{elektra\+Cursor $\ast$}]{end }\end{DoxyParamCaption})}



Searches for the start and optionally end of the key hierachy rooted at {\ttfamily root} in {\ttfamily ks}. 

The main use-\/case for this function is this kind of loop\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{elektraCursor end;}
\DoxyCodeLine{\textcolor{keywordflow}{for} (elektraCursor it = \mbox{\hyperlink{group__keyset_gaf29e567a3a733160303a452cc2366e69}{ksFindHierarchy}} (ks, root, \&end); it < end; ++it)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        Key * cur = \mbox{\hyperlink{group__keyset_ga12b8fefaa20546e4790d60338b0db836}{ksAtCursor}} (ks, it);}
\DoxyCodeLine{\}}

\end{DoxyCode}



\begin{DoxyParams}{Parameters}
{\em ks} & The keyset to search in \\
\hline
{\em root} & The root of the hierachy to find \\
\hline
{\em end} & If this is not NULL, it will be set to position of the first key after {\ttfamily root} that is not below {\ttfamily root}. This is useful for loops like the one above. If not keys below {\ttfamily root} exist in {\ttfamily ks}, {\ttfamily end} will always be set to the size of {\ttfamily ks}. This way a loop like the one above will still work correctly.\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & if {\ttfamily ks} or {\ttfamily root} are NULL \\
\hline
\end{DoxyRetVals}
\begin{DoxyReturn}{Returns}
the position of either {\ttfamily root} itself or the first key below {\ttfamily root} that is part of {\ttfamily ks}. If no keys below {\ttfamily root} exist in {\ttfamily ks}, the size of {\ttfamily ks} is returned. The snippet above shows why this is useful. 
\end{DoxyReturn}
\mbox{\Hypertarget{group__keyset_gace0444eb8ec958a429794f8586fc72e7}\label{group__keyset_gace0444eb8ec958a429794f8586fc72e7}} 
\index{KeySet@{KeySet}!ksGetCursor@{ksGetCursor}}
\index{ksGetCursor@{ksGetCursor}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksGetCursor()}{ksGetCursor()}}
{\footnotesize\ttfamily elektra\+Cursor ks\+Get\+Cursor (\begin{DoxyParamCaption}\item[{const Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Get the internal cursor of the Key\+Set. 

\begin{DoxyWarning}{Warning}
Cursors are getting invalid when the Key was \mbox{\hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{ks\+Pop()}}ed or \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} with KDB\+\_\+\+O\+\_\+\+POP was used.
\end{DoxyWarning}
\hypertarget{group__keyset_readahead}{}\doxysubsection{Read ahead}\label{group__keyset_readahead}
With the cursors it is possible to read ahead in a Key\+Set\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{elektraCursor jump;}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ksRewind}} (ks);}
\DoxyCodeLine{\textcolor{keywordflow}{while} ((key = \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{keyNextMeta}} (ks))!=0)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        \textcolor{comment}{// now mark this key}}
\DoxyCodeLine{        jump = \mbox{\hyperlink{group__keyset_gace0444eb8ec958a429794f8586fc72e7}{ksGetCursor}}(ks);}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{comment}{//code..}}
\DoxyCodeLine{        \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{keyNextMeta}} (ks); \textcolor{comment}{// now browse on}}
\DoxyCodeLine{        \textcolor{comment}{// use ksCurrent(ks) to check the keys}}
\DoxyCodeLine{        \textcolor{comment}{//code..}}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{comment}{// jump back to the position marked before}}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_ga28b2a7d13c620b3c9d4815a0608c738f}{ksSetCursor}}(ks, jump);}
\DoxyCodeLine{\}}

\end{DoxyCode}
\hypertarget{group__keyset_restore}{}\doxysubsection{Restoring state}\label{group__keyset_restore}
It can also be used to restore the state of a Key\+Set in a function


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{keywordtype}{int} f (KeySet *ks)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        elektraCursor state = \mbox{\hyperlink{group__keyset_gace0444eb8ec958a429794f8586fc72e7}{ksGetCursor}}(ks);}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{comment}{// work with keyset}}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{comment}{// now bring the keyset to the state before}}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_ga28b2a7d13c620b3c9d4815a0608c738f}{ksSetCursor}} (ks, state);}
\DoxyCodeLine{\}}

\end{DoxyCode}


It is of course possible to make the Key\+Set const and cast its const away to set the cursor. Another way to achieve the same is to \mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ks\+Dup()}} the Key\+Set, but it is not as efficient.

An invalid cursor will be returned directly after \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}}. When you set an invalid cursor \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} is 0 and \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} == \mbox{\hyperlink{group__keyset_gae7dbf3aef70e67b5328475eb3d1f92f5}{ks\+Head()}}.\hypertarget{group__keyset_cursor_directly}{}\doxysubsection{Using Cursor directly}\label{group__keyset_cursor_directly}
You can also use the cursor directly by initializing it to some index in the Key\+Set and then incrementing or decrementing it, to iterate over the Key\+Set.


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        Key * cur;}
\DoxyCodeLine{        \textcolor{keywordflow}{for} (elektraCursor cursor = 0; (cur = \mbox{\hyperlink{group__keyset_ga12b8fefaa20546e4790d60338b0db836}{ksAtCursor}} (ks, cursor)) != NULL; ++cursor)}
\DoxyCodeLine{        \{}
\DoxyCodeLine{                printf (\textcolor{stringliteral}{"{}\%s\(\backslash\)n"{}}, \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (cur));}
\DoxyCodeLine{        \}}

\end{DoxyCodeInclude}
 You can also use a while loop if you need access to the last cursor position.


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        elektraCursor cursor = 0;}
\DoxyCodeLine{        Key * cur;}
\DoxyCodeLine{}
\DoxyCodeLine{        \textcolor{keywordflow}{while} ((cur = \mbox{\hyperlink{group__keyset_ga12b8fefaa20546e4790d60338b0db836}{ksAtCursor}} (ks, cursor)) != 0)}
\DoxyCodeLine{        \{}
\DoxyCodeLine{                printf (\textcolor{stringliteral}{"{}\%s\(\backslash\)n"{}}, \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{keyName}} (cur));}
\DoxyCodeLine{                ++cursor;}
\DoxyCodeLine{        \}}

\end{DoxyCodeInclude}
 \begin{DoxyNote}{Note}
Only use a cursor for the same Key\+Set which it was made for.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set object to get the cursor from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a valid cursor on success 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & on NULL pointer \\
\hline
{\em -\/1} & on an invalid internal cursor or after ks\+Rewind\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} for moving the internal cursor forward 

\mbox{\hyperlink{group__keyset_ga28b2a7d13c620b3c9d4815a0608c738f}{ks\+Set\+Cursor()}} for setting the cursor to a specific position 

\mbox{\hyperlink{group__keyset_ga12b8fefaa20546e4790d60338b0db836}{ks\+At\+Cursor()}} for getting the Key at a specific position 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_gad40b98651a293a255cd6a7b9e4bd7b71}\label{group__keyset_gad40b98651a293a255cd6a7b9e4bd7b71}} 
\index{KeySet@{KeySet}!ksGetRef@{ksGetRef}}
\index{ksGetRef@{ksGetRef}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksGetRef()}{ksGetRef()}}
{\footnotesize\ttfamily uint16\+\_\+t ks\+Get\+Ref (\begin{DoxyParamCaption}\item[{const Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Return the current reference counter value of a Key\+Set object. 


\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set whose reference counter to retrieve\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the value of the {\ttfamily key\textquotesingle{}s} reference counter 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga5a656d35588d0c2f35c1e58653e46791}{ks\+Inc\+Ref()}} for increasing the reference counter and for a more complete explanation of the reference counting system 

\mbox{\hyperlink{group__keyset_gae27a4c9538a99d9de30f57ef6a8f3fc2}{ks\+Dec\+Ref()}} for decreasing the reference counter 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga7474ad6b0a0fa969dbdf267ba5770eee}\label{group__keyset_ga7474ad6b0a0fa969dbdf267ba5770eee}} 
\index{KeySet@{KeySet}!ksGetSize@{ksGetSize}}
\index{ksGetSize@{ksGetSize}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksGetSize()}{ksGetSize()}}
{\footnotesize\ttfamily ssize\+\_\+t ks\+Get\+Size (\begin{DoxyParamCaption}\item[{const Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Return the number of Keys that {\ttfamily ks} contains. 


\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set object to get the size from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the number of Keys that {\ttfamily ks} contains. 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\mbox{\Hypertarget{group__keyset_gae7dbf3aef70e67b5328475eb3d1f92f5}\label{group__keyset_gae7dbf3aef70e67b5328475eb3d1f92f5}} 
\index{KeySet@{KeySet}!ksHead@{ksHead}}
\index{ksHead@{ksHead}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksHead()}{ksHead()}}
{\footnotesize\ttfamily Key$\ast$ ks\+Head (\begin{DoxyParamCaption}\item[{const Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Return the first Key in the Key\+Set. 

The Key\+Set\textquotesingle{}s cursor will not be affected.

If \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}}==\mbox{\hyperlink{group__keyset_gae7dbf3aef70e67b5328475eb3d1f92f5}{ks\+Head()}} you know you are on the first Key.


\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set object to get the first Key from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the first Key of a Key\+Set 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & on NULL pointer or empty Key\+Set\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gadca442c4ab43cf532b15091d7711559e}{ks\+Tail()}} for getting the last Key of the Key\+Set 

\mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}}, \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} and \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} for iterating over the Key\+Set 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga5a656d35588d0c2f35c1e58653e46791}\label{group__keyset_ga5a656d35588d0c2f35c1e58653e46791}} 
\index{KeySet@{KeySet}!ksIncRef@{ksIncRef}}
\index{ksIncRef@{ksIncRef}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksIncRef()}{ksIncRef()}}
{\footnotesize\ttfamily uint16\+\_\+t ks\+Inc\+Ref (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Increment the reference counter of a Key\+Set object. 

As long as the reference counter is non-\/zero, {\ttfamily \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}}} operations on {\ttfamily key} will be a no-\/op and return an error code.

Elektra\textquotesingle{}s system for reference counting is not based on a concept of shared ownership. It is more similar to a shared lock, where the counter is used to keep track of how many clients hold the lock.

Initially, the reference counter will be 0. This can be interpreted as the lock being unlocked. When you increment the reference counter, the lock becomes locked and {\ttfamily \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}}} is blocked and fails. Only when the reference counter is fully decremented back down to 0 again, will {\ttfamily \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}}} work again.

\begin{DoxyNote}{Note}
The reference counter can never exceed {\ttfamily UINT16\+\_\+\+MAX -\/ 1}. {\ttfamily UINT16\+\_\+\+MAX} is reserved as an error code.
\end{DoxyNote}
\begin{DoxyPostcond}{Postcondition}
{\ttfamily ks\textquotesingle{}s} reference counter is $>$ 0 

{\ttfamily ks\textquotesingle{}s} reference counter is $<$= UINT16\+\_\+\+MAX -\/ 1
\end{DoxyPostcond}

\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set object whose reference counter should be increased\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the updated value of the reference counter 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em UINT16\+\_\+\+MAX} & on NULL pointer \\
\hline
{\em UINT16\+\_\+\+MAX} & when the reference counter already was the maximum value {\ttfamily UINT16\+\_\+\+MAX -\/ 1}, the reference counter will not be modified in this case\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gad40b98651a293a255cd6a7b9e4bd7b71}{ks\+Get\+Ref()}} to retrieve the current reference count 

\mbox{\hyperlink{group__keyset_gae27a4c9538a99d9de30f57ef6a8f3fc2}{ks\+Dec\+Ref()}} for decreasing the reference counter 

\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}} for deleting a Key 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}\label{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}} 
\index{KeySet@{KeySet}!ksLookup@{ksLookup}}
\index{ksLookup@{ksLookup}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksLookup()}{ksLookup()}}
{\footnotesize\ttfamily Key$\ast$ ks\+Lookup (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks,  }\item[{Key $\ast$}]{key,  }\item[{\mbox{\hyperlink{group__keyset_gada05f4bbf46fde81d0d57df86e73d914}{elektra\+Lookup\+Flags}}}]{options }\end{DoxyParamCaption})}



Look for a Key contained in {\ttfamily ks} that matches the name of the {\ttfamily key}. 

\begin{DoxyNote}{Note}
Applications should only use \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} with cascading Keys (Key name starting with {\ttfamily /}). Furthermore, a lookup should be done for every Key (also when iterating over Keys) so that the specifications are honored correctly. Keys of all namespaces need to be present so that \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} can work correctly, so make sure to also use \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} with a cascading Key.
\end{DoxyNote}
\mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} is designed to let you work with a Key\+Set containing all Keys of the application. The idea is to fully \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} the whole configuration of your application and process it all at once with many {\ttfamily \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}}}.

This function is efficient (at least using binary search). Together with \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}}, which you can use to load the whole configuration, you can write very effective and short code for configuration\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{Key * key = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}/sw/tests/myapp/\#0/current/"{}},  \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{KDB * handle = \mbox{\hyperlink{group__kdb_ga844e1299a84c3fbf1d3a905c5c893ba5}{kdbOpen}} (NULL, key);}
\DoxyCodeLine{\mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdbGet}} (handle, myConfig, key);}
\DoxyCodeLine{Key * result = \mbox{\hyperlink{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}{ksLookupByName}} (myConfig, \textcolor{stringliteral}{"{}/sw/tests/myapp/\#0/current/testkey1"{}}, 0);}

\end{DoxyCodeInclude}
 This is the way programs should get their configuration and search for the values. It is guaranteed, that more namespaces can be added easily and that all values can be set by admin and user. Furthermore, using the kdb-\/tool, it is possible to introspect which values an application will get (by doing the same cascading lookup).

If found, {\ttfamily ks} internal cursor will be positioned in the matched Key (also accessible by \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}}), and a pointer to the Key is returned. If not found, {\ttfamily ks} internal cursor will not move, and a NULL pointer is returned.

Cascading lookups will by default search in all namespaces (proc\+:/, dir\+:/, user\+:/ and system\+:/), but will also correctly consider the specification (=metadata) in spec\+:/\+:


\begin{DoxyItemize}
\item {\ttfamily override/\#} will make sure that another Key is considered before
\item {\ttfamily namespace/\#} will change the number and/or order in which the namespaces are searched
\item {\ttfamily fallback/\#} will search for other Keys when the other possibilities up to now were not successful
\item {\ttfamily default} to return the given value when not even {\ttfamily fallback} Keys were found.
\end{DoxyItemize}

\begin{DoxyNote}{Note}
override and fallback work recursively, while default does not.
\end{DoxyNote}
This process is very flexible, but it would be boring to manually follow all this links to find out which Key will be taken in the end. Use {\ttfamily kdb get -\/v} to trace the Keys.

\begin{DoxyParagraph}{KDB\+\_\+\+O\+\_\+\+POP}
When \mbox{\hyperlink{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a52fb5f2cc86773d393da62bebebf7984}{KDB\+\_\+\+O\+\_\+\+POP}} is set the Key which was found will be \mbox{\hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{ks\+Pop()}}ed. \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} will not be changed, only iff \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} is the searched Key, then the Key\+Set will be \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}}ed.
\end{DoxyParagraph}
\begin{DoxyNote}{Note}
Like in \mbox{\hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{ks\+Pop()}} the popped Key always needs to be \mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{key\+Del()}} afterwards, even if it is appended to another Key\+Set.
\end{DoxyNote}
\begin{DoxyWarning}{Warning}
All cursors on the Key\+Set will be invalid iff you use \mbox{\hyperlink{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a52fb5f2cc86773d393da62bebebf7984}{KDB\+\_\+\+O\+\_\+\+POP}}, so don\textquotesingle{}t use this if you rely on a cursor, see \mbox{\hyperlink{group__keyset_gace0444eb8ec958a429794f8586fc72e7}{ks\+Get\+Cursor()}}.
\end{DoxyWarning}
The invalidation of cursors does not matter if you use multiple Key\+Sets, e.\+g. by using \mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ks\+Dup()}}. E.\+g., to separate \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} with \mbox{\hyperlink{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a52fb5f2cc86773d393da62bebebf7984}{KDB\+\_\+\+O\+\_\+\+POP}} and \mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()}}\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keywordtype}{void} f (KeySet * iterator, KeySet * lookup)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        KeySet * append = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (\mbox{\hyperlink{group__keyset_ga7474ad6b0a0fa969dbdf267ba5770eee}{ksGetSize}} (lookup), \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{        Key * current;}
\DoxyCodeLine{}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ksRewind}} (iterator);}
\DoxyCodeLine{        \textcolor{keywordflow}{while} ((current = \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ksNext}} (iterator)))}
\DoxyCodeLine{        \{}
\DoxyCodeLine{                Key * key = \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ksLookup}} (lookup, current, \mbox{\hyperlink{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a52fb5f2cc86773d393da62bebebf7984}{KDB\_O\_POP}});}
\DoxyCodeLine{                \textcolor{comment}{// do something...}}
\DoxyCodeLine{                \mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}} (append, key); \textcolor{comment}{// now append it to append, not lookup!}}
\DoxyCodeLine{                \mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{keyDel}} (key);                \textcolor{comment}{// make sure to ALWAYS delete poped keys.}}
\DoxyCodeLine{        \}}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_ga21eb9c3a14a604ee3a8bdc779232e7b7}{ksAppend}} (lookup, append);}
\DoxyCodeLine{        \textcolor{comment}{// now lookup needs to be sorted only once, append never}}
\DoxyCodeLine{        \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (append);}
\DoxyCodeLine{\}}

\end{DoxyCodeInclude}
 This is also a nice example how a complete application with \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} can look like.

\begin{DoxyParagraph}{KDB\+\_\+\+O\+\_\+\+DEL}
Passing \mbox{\hyperlink{group__keyset_ggada05f4bbf46fde81d0d57df86e73d914a66a5380c120f25f28f49848c4a863ead}{KDB\+\_\+\+O\+\_\+\+DEL}} will cause the deletion of the parameter {\ttfamily key} using \mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{key\+Del()}}.
\end{DoxyParagraph}
\begin{DoxyParagraph}{Hybrid search}
When Elektra is compiled with {\ttfamily ENABLE\+\_\+\+OPTIMIZATIONS=ON} a hybrid search decides dynamically between the binary search and the \href{https://master.libelektra.org/doc/dev/data-structures.md\#order-preserving-minimal-perfect-hash-map-aka-opmphm}{\texttt{ OPMPHM}}. The hybrid search can be overruled by passing \mbox{\hyperlink{kdbhelper_8h_a93673533c4c8eb1fdfca76b98c5f49b0afe9f6ff6e374540baf600a918b07ee6e}{KDB\+\_\+\+O\+\_\+\+OPMPHM}} or \mbox{\hyperlink{kdbhelper_8h_a93673533c4c8eb1fdfca76b98c5f49b0ac67a43bd273203575090d26010f6c995}{KDB\+\_\+\+O\+\_\+\+BINSEARCH}} in the options to \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}}.
\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set that should be searched \\
\hline
{\em key} & the Key object you are looking for \\
\hline
{\em options} & of type \mbox{\hyperlink{group__keyset_gada05f4bbf46fde81d0d57df86e73d914}{elektra\+Lookup\+Flags}} with some {\ttfamily KDB\+\_\+\+O\+\_\+$\ast$} option bits -\/ as explained above\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
pointer to the Key found 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & if no Key has been found \\
\hline
{\em 0} & on NULL pointers\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}{ks\+Lookup\+By\+Name()}} to search by a name given by a string 

\mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}}, \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}}, \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} for iterating over a Key\+Set 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}\label{group__keyset_gad65d2cdcbb5381194a1688e169af8a83}} 
\index{KeySet@{KeySet}!ksLookupByName@{ksLookupByName}}
\index{ksLookupByName@{ksLookupByName}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksLookupByName()}{ksLookupByName()}}
{\footnotesize\ttfamily Key$\ast$ ks\+Lookup\+By\+Name (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks,  }\item[{const char $\ast$}]{name,  }\item[{\mbox{\hyperlink{group__keyset_gada05f4bbf46fde81d0d57df86e73d914}{elektra\+Lookup\+Flags}}}]{options }\end{DoxyParamCaption})}



Convenience method to look for a Key contained in {\ttfamily ks} with name {\ttfamily name}. 

There are several options that can be used in conjunction with this function. All possible option flags can be found in \mbox{\hyperlink{group__keyset_gada05f4bbf46fde81d0d57df86e73d914}{elektra\+Lookup\+Flags}}


\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set that should be searched \\
\hline
{\em name} & name of the Key you are looking for \\
\hline
{\em options} & some {\ttfamily KDB\+\_\+\+O\+\_\+$\ast$} option bits (KDB\+\_\+\+O\+\_\+\+POP, KDB\+\_\+\+O\+\_\+\+DEL)\+:
\begin{DoxyItemize}
\item See \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} or \mbox{\hyperlink{group__keyset_gada05f4bbf46fde81d0d57df86e73d914}{elektra\+Lookup\+Flags}} for possible options
\end{DoxyItemize}\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
pointer to the Key found 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & if no Key has been found \\
\hline
{\em 0} & on NULL pointers\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} for explanation of the functionality and examples. 

\mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}}, \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}}, \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} for iterating over a Key\+Set 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}\label{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}} 
\index{KeySet@{KeySet}!ksNew@{ksNew}}
\index{ksNew@{ksNew}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksNew()}{ksNew()}}
{\footnotesize\ttfamily Key\+Set$\ast$ ks\+New (\begin{DoxyParamCaption}\item[{size\+\_\+t}]{alloc,  }\item[{}]{... }\end{DoxyParamCaption})}



Allocate, initialize and return a new Key\+Set object. 

Objects created with \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}} must be destroyed with \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}}.

You can use an arbitrary long list of parameters to preload the Key\+Set with a list of Keys. Either your first and only parameter is 0 or your last parameter must be KS\+\_\+\+END.

So, terminate with ks\+New(0, KS\+\_\+\+END) or ks\+New(20, ..., KS\+\_\+\+END)

\begin{DoxyWarning}{Warning}
Never use ks\+New(0, key\+New(...), KS\+\_\+\+END). If the first parameter is 0, other arguments are ignored.
\end{DoxyWarning}
The first parameter {\ttfamily alloc} defines how many Keys can be added without reallocation. If you pass any alloc size greater than 0, but less than 16, it will default to 16.

For most uses


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{KeySet * keys = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (1, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{\textcolor{comment}{// enough memory for up to 16 keys, without needing reallocation}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (keys);}

\end{DoxyCodeInclude}
 will be fine. The alloc size will be 16 and will double whenever size reaches alloc size, so it also performs well with large Key\+Sets.

You can defer the allocation of the internal array that holds the Keys, by passing 0 as the alloc size. This is useful if it is unclear whether your Key\+Set will actually hold any Keys and you want to avoid a malloc call.


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{comment}{// Create KeySet without allocating memory for keys}}
\DoxyCodeLine{KeySet * keys = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (0, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{\textcolor{comment}{// The first allocation will happen in ksAppendKey}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}}(keys, \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key02"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value02"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}));}
\DoxyCodeLine{\textcolor{comment}{// work with the KeySet}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (keys);}

\end{DoxyCodeInclude}
 If the size of the Key\+Set is known in advance, use the {\ttfamily alloc} parameter to hint the size of the Key\+Set.

If your application only needs up to 15 Keys you can request a Key\+Set of size 15\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{KeySet * keys = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (15, \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key01"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value01"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                       \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key02"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value02"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                       \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key03"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value03"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                       \textcolor{comment}{// ...}}
\DoxyCodeLine{                       \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key15"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value15"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}), \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{\textcolor{comment}{// work with it}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (keys);}

\end{DoxyCodeInclude}
 If you start having 3 Keys, and your application needs approximately 200 up to 500 Keys, you can use\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{KeySet * config = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (500, \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key1"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value1"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                         \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key2"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value2"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                         \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key3"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value3"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                         \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}}); \textcolor{comment}{// don't forget the KS\_END at the end!}}
\DoxyCodeLine{\textcolor{comment}{// work with it}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (config);}

\end{DoxyCodeInclude}
 Alloc size is 500, the size of the Key\+Set will be 3 after ks\+New. This means the Key\+Set will reallocate when appending more than 497 keys.

The main benefit of taking a list of variant length parameters is to be able to have one C-\/\+Statement for any possible Key\+Set. If you prefer, you can always create an empty Key\+Set and use \mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()}}.

\begin{DoxyPostcond}{Postcondition}
the Key\+Set is rewinded properly
\end{DoxyPostcond}

\begin{DoxyParams}{Parameters}
{\em alloc} & gives a hint for how many Keys may be stored initially\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a ready to use Key\+Set object 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & on memory error\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}} to free the Key\+Set afterwards 

\mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ks\+Dup()}} to duplicate an existing Key\+Set 

\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()}} to append individual Keys to a Key\+Set 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}\label{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}} 
\index{KeySet@{KeySet}!ksNext@{ksNext}}
\index{ksNext@{ksNext}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksNext()}{ksNext()}}
{\footnotesize\ttfamily Key$\ast$ ks\+Next (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Returns the next Key in a Key\+Set. 

Key\+Sets have an internal cursor that can be reset with \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}}. Every time \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} is called, the cursor is incremented and the new current Key is returned.

You\textquotesingle{}ll get a NULL pointer if the Key at the end of the Key\+Set has been reached. On subsequent calls of \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} it will still return the NULL pointer.

The {\ttfamily ks} internal cursor will be changed, so it is not const.

\begin{DoxyNote}{Note}
You must not delete or change the Key, use \mbox{\hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{ks\+Pop()}} if you want to delete it.

That applications must do \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} with an cascading Key for every single Key before using it, because specifications allow to hide or override Keys.
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set object to work with\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the new current Key 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & when the end of the Key\+Set has been reached \\
\hline
{\em 0} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}} for resetting the internal cursor of the Key\+Set 

\mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} for getting the Key the cursor currently points at 

\mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} to honor specifications 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_gae42530b04defb772059de0600159cf69}\label{group__keyset_gae42530b04defb772059de0600159cf69}} 
\index{KeySet@{KeySet}!ksPop@{ksPop}}
\index{ksPop@{ksPop}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksPop()}{ksPop()}}
{\footnotesize\ttfamily Key$\ast$ ks\+Pop (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Remove and return the last Key of {\ttfamily ks}. 

The reference counter of the Key will be decremented by one.

The Key\+Set\textquotesingle{}s cursor will not be affected if it did not point to the popped Key.

\begin{DoxyNote}{Note}
You need to \mbox{\hyperlink{group__key_ga3df95bbc2494e3e6703ece5639be5bb1}{key\+Del()}} the Key afterwards, if you don\textquotesingle{}t append it to another Key\+Set. It has the same semantics like a Key allocated with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}} or key\+Dup().
\end{DoxyNote}

\begin{DoxyCode}{0}
\DoxyCodeLine{ks1=\mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}}(0, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{ks2=\mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}}(0, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{}
\DoxyCodeLine{k1=\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}user:/name"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}); \textcolor{comment}{// ref counter 0}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}}(ks1, k1); \textcolor{comment}{// ref counter 1}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}}(ks2, k1); \textcolor{comment}{// ref counter 2}}
\DoxyCodeLine{}
\DoxyCodeLine{k1=\mbox{\hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{ksPop}} (ks1); \textcolor{comment}{// ref counter 1}}
\DoxyCodeLine{k1=\mbox{\hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{ksPop}} (ks2); \textcolor{comment}{// ref counter 0, like after keyNew()}}
\DoxyCodeLine{}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}}(ks1, k1); \textcolor{comment}{// ref counter 1}}
\DoxyCodeLine{}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (ks1); \textcolor{comment}{// key is deleted too}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (ks2);}

\end{DoxyCode}



\begin{DoxyParams}{Parameters}
{\em ks} & Key\+Set to pop a Key from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the last Key of {\ttfamily ks} 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em NULL} & if {\ttfamily ks} is empty or a NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} to pop Keys by name 

\mbox{\hyperlink{group__keyset_gaba1f1dbea191f4d7e7eb3e4296ae7d5e}{ks\+Copy()}} to pop all Keys 

\mbox{\hyperlink{group__keyset_gadca442c4ab43cf532b15091d7711559e}{ks\+Tail()}} for getting the last Key of a Key\+Set without removing it 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_gaa9b59d3a7ccd58511b562755454d1fae}\label{group__keyset_gaa9b59d3a7ccd58511b562755454d1fae}} 
\index{KeySet@{KeySet}!ksRename@{ksRename}}
\index{ksRename@{ksRename}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksRename()}{ksRename()}}
{\footnotesize\ttfamily ssize\+\_\+t ks\+Rename (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks,  }\item[{const Key $\ast$}]{root,  }\item[{const Key $\ast$}]{new\+Root }\end{DoxyParamCaption})}



Moves all keys below {\ttfamily root} to below {\ttfamily new\+Root}. 

Only keys below {\ttfamily root} will be modified. The rest of {\ttfamily ks} remains untouched.

This functions is similar to the following snippet, but there are some differences.


\begin{DoxyCode}{0}
\DoxyCodeLine{KeySet * toRename = \mbox{\hyperlink{group__keyset_ga6b00cf82b59af4d883a9bad6cf4a4a4a}{ksCut}} (ks, root);}
\DoxyCodeLine{\textcolor{keywordflow}{for} (elektraCursor cursor = 0; cursor < \mbox{\hyperlink{group__keyset_ga7474ad6b0a0fa969dbdf267ba5770eee}{ksGetSize}} (toRename); cursor++)}
\DoxyCodeLine{\{}
\DoxyCodeLine{    Key * cur = keyDup (\mbox{\hyperlink{group__keyset_ga12b8fefaa20546e4790d60338b0db836}{ksAtCursor}} (ks, cursor));}
\DoxyCodeLine{    \mbox{\hyperlink{group__keyname_gae22037aad3f76f4454de4e6400637b39}{keyReplacePrefix}} (cur, root, newRoot);}
\DoxyCodeLine{    \mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}} (ks, cur);}
\DoxyCodeLine{\}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (toRename);}

\end{DoxyCode}


Firstly, the optimizations only work, if {\ttfamily ks} doesn\textquotesingle{}t contain any keys below {\ttfamily new\+Root} that aren\textquotesingle{}t below {\ttfamily root}. If such keys exist, \mbox{\hyperlink{group__keyset_gaa9b59d3a7ccd58511b562755454d1fae}{ks\+Rename()}} will still work, but it will fall back to code similar to the for-\/loop above.

The second difference is that \mbox{\hyperlink{group__keyset_gaa9b59d3a7ccd58511b562755454d1fae}{ks\+Rename()}} will modify the keys in {\ttfamily ks} directly, if they aren\textquotesingle{}t referenced from anywhere else (if their reference count is 1 (see \mbox{\hyperlink{group__key_ga0d82ce48529821aa43d82c035ba30c4f}{key\+Get\+Ref()}})). Normally, this shouldn\textquotesingle{}t cause problems, but if you have a direct {\ttfamily Key $\ast$} pointer to a key in {\ttfamily ks} or hold a reference to some data within a key of {\ttfamily ks}, you may need to call \mbox{\hyperlink{group__key_ga0b477b584c8be68519a8d92f90355136}{key\+Inc\+Ref()}} to ensure the key isn\textquotesingle{}t modified.


\begin{DoxyParams}{Parameters}
{\em ks} & the keyset to manipulate \\
\hline
{\em root} & the old prefix that will be removed, must not be a cascading key \\
\hline
{\em new\+Root} & the new prefix the will replace the old one, must not be a cascading key\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em -\/1} & if any of {\ttfamily ks}, {\ttfamily root}, {\ttfamily new\+Root} is NULL, or if {\ttfamily root} or {\ttfamily new\+Root} are cascading keys \\
\hline
{\em -\/2} & if {\ttfamily ks} already contains keys below {\ttfamily new\+Root} \\
\hline
{\em 0} & if {\ttfamily ks} contains no keys below {\ttfamily root} (and also not {\ttfamily root} itself) \\
\hline
\end{DoxyRetVals}
\begin{DoxyReturn}{Returns}
otherwise, the number of keys that have been renamed 
\end{DoxyReturn}
\mbox{\Hypertarget{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}\label{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}} 
\index{KeySet@{KeySet}!ksRewind@{ksRewind}}
\index{ksRewind@{ksRewind}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksRewind()}{ksRewind()}}
{\footnotesize\ttfamily int ks\+Rewind (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Rewinds the Key\+Set internal cursor. 

Use it to set the cursor to the beginning of the Key\+Set. \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} will always return NULL afterwards. So you want to use \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} first.


\begin{DoxyCode}{0}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ksRewind}} (ks);}
\DoxyCodeLine{\textcolor{keywordflow}{while} ((key = \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ksNext}} (ks))!=0) \{\}}

\end{DoxyCode}



\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set that should be rewound\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & on success \\
\hline
{\em -\/1} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} for moving the cursor to the next entry in the Key\+Set 

\mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} for getting the current element in the Key\+Set 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_gac59817ac58072708092fbeb87600beb1}\label{group__keyset_gac59817ac58072708092fbeb87600beb1}} 
\index{KeySet@{KeySet}!ksSearch@{ksSearch}}
\index{ksSearch@{ksSearch}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksSearch()}{ksSearch()}}
{\footnotesize\ttfamily ssize\+\_\+t ks\+Search (\begin{DoxyParamCaption}\item[{const Key\+Set $\ast$}]{ks,  }\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Search in a key set, either yielding the actual index of the key, if the ley has been found within the key set, or a negative value indicating the insertion index of the key, if the key would be inserted. 


\begin{DoxyCode}{0}
\DoxyCodeLine{ssize\_t result = \mbox{\hyperlink{group__keyset_gac59817ac58072708092fbeb87600beb1}{ksSearch}}(ks, key);}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordflow}{if} (result >= 0)}
\DoxyCodeLine{\{}
\DoxyCodeLine{        ssize\_t position = result;}
\DoxyCodeLine{        \textcolor{comment}{// The key already exist in key set.}}
\DoxyCodeLine{\} \textcolor{keywordflow}{else} \{}
\DoxyCodeLine{        ssize\_t insertpos = -\/result-\/1;}
\DoxyCodeLine{        \textcolor{comment}{// The key was not found in key set.}}
\DoxyCodeLine{\}}

\end{DoxyCode}



\begin{DoxyParams}{Parameters}
{\em ks} & the keyset to work with \\
\hline
{\em key} & the key to check \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
position where the key is ($>$=0) if the key was found 

-\/insertpos -\/1 ($<$ 0) if the key was not found so to get the insertpos simple do\+: -\/insertpos -\/1 
\end{DoxyReturn}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} for retrieving the found \mbox{\hyperlink{group__key}{Key}} 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga28b2a7d13c620b3c9d4815a0608c738f}\label{group__keyset_ga28b2a7d13c620b3c9d4815a0608c738f}} 
\index{KeySet@{KeySet}!ksSetCursor@{ksSetCursor}}
\index{ksSetCursor@{ksSetCursor}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksSetCursor()}{ksSetCursor()}}
{\footnotesize\ttfamily int ks\+Set\+Cursor (\begin{DoxyParamCaption}\item[{Key\+Set $\ast$}]{ks,  }\item[{elektra\+Cursor}]{cursor }\end{DoxyParamCaption})}



Set the Key\+Set internal cursor to {\ttfamily cursor}. 

Use it to set the cursor to a stored position. \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} will then return the Key at the position of the supplied cursor.

\begin{DoxyWarning}{Warning}
Cursors may get invalid when the Key was \mbox{\hyperlink{group__keyset_gae42530b04defb772059de0600159cf69}{ks\+Pop()}}ed or \mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} was used together with KDB\+\_\+\+O\+\_\+\+POP.
\end{DoxyWarning}

\begin{DoxyCode}{0}
\DoxyCodeLine{elektraCursor cursor;}
\DoxyCodeLine{..}
\DoxyCodeLine{\textcolor{comment}{// key now in any position here}}
\DoxyCodeLine{cursor = \mbox{\hyperlink{group__keyset_gace0444eb8ec958a429794f8586fc72e7}{ksGetCursor}} (ks);}
\DoxyCodeLine{\textcolor{keywordflow}{while} ((key = \mbox{\hyperlink{group__keymeta_ga4c88342f580a4291455a801af71ce048}{keyNextMeta}} (ks))!=0) \{\}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga28b2a7d13c620b3c9d4815a0608c738f}{ksSetCursor}} (ks, cursor); \textcolor{comment}{// reset state}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ksCurrent}}(ks); \textcolor{comment}{// in same position as before}}

\end{DoxyCode}


An invalid cursor will set the Key\+Set to its beginning like \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}}. When you set an invalid cursor \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} is 0 and \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} == \mbox{\hyperlink{group__keyset_gae7dbf3aef70e67b5328475eb3d1f92f5}{ks\+Head()}}.


\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set object where the cursor should be set \\
\hline
{\em cursor} & the cursor to set for {\ttfamily ks} \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 0} & when the Key\+Set has been \mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}}ed \\
\hline
{\em 1} & otherwise \\
\hline
{\em -\/1} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gace0444eb8ec958a429794f8586fc72e7}{ks\+Get\+Cursor()}} for getting the cursor at the current position 

\mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} for moving the internal cursor forward 

\mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} for getting the Key at the current position 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_gadca442c4ab43cf532b15091d7711559e}\label{group__keyset_gadca442c4ab43cf532b15091d7711559e}} 
\index{KeySet@{KeySet}!ksTail@{ksTail}}
\index{ksTail@{ksTail}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksTail()}{ksTail()}}
{\footnotesize\ttfamily Key$\ast$ ks\+Tail (\begin{DoxyParamCaption}\item[{const Key\+Set $\ast$}]{ks }\end{DoxyParamCaption})}



Return the last Key in the Key\+Set. 

The Key\+Set\textquotesingle{}s cursor will not be affected.

If \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}}==\mbox{\hyperlink{group__keyset_gadca442c4ab43cf532b15091d7711559e}{ks\+Tail()}} you know you are on the last key. \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} will return a NULL pointer afterwards.


\begin{DoxyParams}{Parameters}
{\em ks} & the Key\+Set object to get the last Key from\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
the last Key of a Key\+Set 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & on NULL pointer or empty Key\+Set\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gae7dbf3aef70e67b5328475eb3d1f92f5}{ks\+Head()}} for getting the first Key of a Key\+Set 

\mbox{\hyperlink{group__keyset_gabe793ff51f1728e3429c84a8a9086b70}{ks\+Rewind()}}, \mbox{\hyperlink{group__keyset_ga4287b9416912c5f2ab9c195cb74fb094}{ks\+Current()}} and \mbox{\hyperlink{group__keyset_ga317321c9065b5a4b3e33fe1c399bcec9}{ks\+Next()}} for iterating over the Key\+Set 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keyset_ga4ff760f56693b51ab785ed7ce628e649}\label{group__keyset_ga4ff760f56693b51ab785ed7ce628e649}} 
\index{KeySet@{KeySet}!ksVNew@{ksVNew}}
\index{ksVNew@{ksVNew}!KeySet@{KeySet}}
\doxysubsubsection{\texorpdfstring{ksVNew()}{ksVNew()}}
{\footnotesize\ttfamily Key\+Set$\ast$ ks\+VNew (\begin{DoxyParamCaption}\item[{size\+\_\+t}]{alloc,  }\item[{va\+\_\+list}]{va }\end{DoxyParamCaption})}



Allocate, initialize and return a new Key\+Set object. 

Objects created with \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ks\+New()}} must be destroyed with \mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}}.

You can use an arbitrary long list of parameters to preload the Key\+Set with a list of Keys. Either your first and only parameter is 0 or your last parameter must be KS\+\_\+\+END.

So, terminate with ks\+New(0, KS\+\_\+\+END) or ks\+New(20, ..., KS\+\_\+\+END)

\begin{DoxyWarning}{Warning}
Never use ks\+New(0, key\+New(...), KS\+\_\+\+END). If the first parameter is 0, other arguments are ignored.
\end{DoxyWarning}
The first parameter {\ttfamily alloc} defines how many Keys can be added without reallocation. If you pass any alloc size greater than 0, but less than 16, it will default to 16.

For most uses


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{KeySet * keys = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (1, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{\textcolor{comment}{// enough memory for up to 16 keys, without needing reallocation}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (keys);}

\end{DoxyCodeInclude}
 will be fine. The alloc size will be 16 and will double whenever size reaches alloc size, so it also performs well with large Key\+Sets.

You can defer the allocation of the internal array that holds the Keys, by passing 0 as the alloc size. This is useful if it is unclear whether your Key\+Set will actually hold any Keys and you want to avoid a malloc call.


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{comment}{// Create KeySet without allocating memory for keys}}
\DoxyCodeLine{KeySet * keys = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (0, \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{\textcolor{comment}{// The first allocation will happen in ksAppendKey}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ksAppendKey}}(keys, \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key02"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value02"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}));}
\DoxyCodeLine{\textcolor{comment}{// work with the KeySet}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (keys);}

\end{DoxyCodeInclude}
 If the size of the Key\+Set is known in advance, use the {\ttfamily alloc} parameter to hint the size of the Key\+Set.

If your application only needs up to 15 Keys you can request a Key\+Set of size 15\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{KeySet * keys = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (15, \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key01"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value01"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                       \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key02"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value02"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                       \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key03"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value03"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                       \textcolor{comment}{// ...}}
\DoxyCodeLine{                       \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key15"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value15"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}), \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}});}
\DoxyCodeLine{\textcolor{comment}{// work with it}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (keys);}

\end{DoxyCodeInclude}
 If you start having 3 Keys, and your application needs approximately 200 up to 500 Keys, you can use\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{KeySet * config = \mbox{\hyperlink{group__keyset_ga671e1aaee3ae9dc13b4834a4ddbd2c3c}{ksNew}} (500, \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key1"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value1"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                         \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key2"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value2"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                         \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}user:/sw/org/app/\#0/current/fixedConfiguration/key3"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}value3"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{                         \mbox{\hyperlink{group__keyset_ga7a28fce3773b2c873c94ac80b8b4cd54}{KS\_END}}); \textcolor{comment}{// don't forget the KS\_END at the end!}}
\DoxyCodeLine{\textcolor{comment}{// work with it}}
\DoxyCodeLine{\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ksDel}} (config);}

\end{DoxyCodeInclude}
 Alloc size is 500, the size of the Key\+Set will be 3 after ks\+New. This means the Key\+Set will reallocate when appending more than 497 keys.

The main benefit of taking a list of variant length parameters is to be able to have one C-\/\+Statement for any possible Key\+Set. If you prefer, you can always create an empty Key\+Set and use \mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()}}.

\begin{DoxyPostcond}{Postcondition}
the Key\+Set is rewinded properly
\end{DoxyPostcond}

\begin{DoxyParams}{Parameters}
{\em alloc} & gives a hint for how many Keys may be stored initially\\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
a ready to use Key\+Set object 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
{\em 0} & on memory error\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0 
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_ga27e5c16473b02a422238c8d970db7ac8}{ks\+Del()}} to free the Key\+Set afterwards 

\mbox{\hyperlink{group__keyset_gac59e4b328245463f1451f68d5106151c}{ks\+Dup()}} to duplicate an existing Key\+Set 

\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()}} to append individual Keys to a Key\+Set
\end{DoxySeeAlso}
\begin{DoxyPrecond}{Precondition}
caller must call va\+\_\+start and va\+\_\+end 
\end{DoxyPrecond}
\begin{DoxyParagraph}{va the list of arguments}

\end{DoxyParagraph}

\begin{DoxyParams}{Parameters}
{\em alloc} & the allocation size \\
\hline
{\em va} & the list of variable arguments \\
\hline
\end{DoxyParams}
