\hypertarget{group__keytest}{}\doxysection{Methods for Making Tests}
\label{group__keytest}\index{Methods for Making Tests@{Methods for Making Tests}}


Methods to do various tests on Keys.  


Collaboration diagram for Methods for Making Tests\+:
\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=265pt]{group__keytest}
\end{center}
\end{figure}
\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
int \mbox{\hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{key\+Cmp}} (const Key $\ast$k1, const Key $\ast$k2)
\begin{DoxyCompactList}\small\item\em Compare the name of two Keys. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}{key\+Need\+Sync}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Test if a key needs to be synced to backend storage. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}{key\+Is\+Below}} (const Key $\ast$key, const Key $\ast$check)
\begin{DoxyCompactList}\small\item\em Check if the Key {\ttfamily check} is below the Key {\ttfamily key} or not. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keytest_ga0150fb549225d8789e7297b919965e72}{key\+Is\+Directly\+Below}} (const Key $\ast$key, const Key $\ast$check)
\begin{DoxyCompactList}\small\item\em Check whether the Key {\ttfamily check} is directly below the Key {\ttfamily key}. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keytest_ga9526b371087564e43e3dff8ad0dac949}{key\+Is\+Binary}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Check if the value of a {\ttfamily key} is of binary type. \end{DoxyCompactList}\item 
int \mbox{\hyperlink{group__keytest_gaea7670778abd07fee0fe8ac12a149190}{key\+Is\+String}} (const Key $\ast$key)
\begin{DoxyCompactList}\small\item\em Check if the value of {\ttfamily key} is of string type. \end{DoxyCompactList}\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Methods to do various tests on Keys. 

With exception of the parameters of \mbox{\hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{key\+Cmp()}}, the following contract holds for all parameters of type Key\+: \begin{DoxyPrecond}{Precondition}
The Key has been properly initialized via \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}} 
\end{DoxyPrecond}
\begin{DoxyInvariant}{Invariant}
All parts of the Key remain unchanged 
\end{DoxyInvariant}
\begin{DoxyPostcond}{Postcondition}
All parts of the Key are unchanged
\end{DoxyPostcond}
To use them\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <kdb.h>}}

\end{DoxyCode}
 

\doxysubsection{Function Documentation}
\mbox{\Hypertarget{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}\label{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}} 
\index{Methods for Making Tests@{Methods for Making Tests}!keyCmp@{keyCmp}}
\index{keyCmp@{keyCmp}!Methods for Making Tests@{Methods for Making Tests}}
\doxysubsubsection{\texorpdfstring{keyCmp()}{keyCmp()}}
{\footnotesize\ttfamily int key\+Cmp (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{k1,  }\item[{const Key $\ast$}]{k2 }\end{DoxyParamCaption})}



Compare the name of two Keys. 

The comparison is based on a memcmp of the Key\textquotesingle{}s names. If the names match, the Keys are found to be exactly the same and 0 is returned. These two keys can\textquotesingle{}t be used in the same Key\+Set.

\mbox{\hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{key\+Cmp()}} defines the sorting order for a Key\+Set.

The following 3 points are the rules for NULL values\+:


\begin{DoxyItemize}
\item A NULL pointer will be found to be smaller than every other Key. If both are NULL pointers, 0 is returned.
\item A NULL name will be found to be smaller than every other name. If both are NULL names, 0 is returned.
\end{DoxyItemize}

If the name is equal then\+:


\begin{DoxyItemize}
\item No owner will be found to be smaller than every other owner. If both don\textquotesingle{}t have an owner, 0 is returned.
\end{DoxyItemize}

\begin{DoxyNote}{Note}
the owner will only be used if the names are equal.
\end{DoxyNote}
Given any Keys k1 and k2 constructed with \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}, following equation hold true\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{        succeed\_if (\mbox{\hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{keyCmp}} (0, 0) == 0, \textcolor{stringliteral}{"{}all null pointers same"{}});}
\DoxyCodeLine{        succeed\_if (\mbox{\hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{keyCmp}} (k1, 0) == 1, \textcolor{stringliteral}{"{}null pointer is smaller"{}});}
\DoxyCodeLine{        succeed\_if (\mbox{\hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{keyCmp}} (0, k2) == -\/1, \textcolor{stringliteral}{"{}null pointer is smaller"{}});}

\end{DoxyCodeInclude}
 Here are some more examples\+: 
\begin{DoxyCode}{0}
\DoxyCodeLine{Key *k1 = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}user:/a"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{Key *k2 = \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}}(\textcolor{stringliteral}{"{}user:/b"{}}, \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}});}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{// keyCmp(k1,k2) < 0}}
\DoxyCodeLine{\textcolor{comment}{// keyCmp(k2,k1) > 0}}

\end{DoxyCode}


Do not strcmp the \mbox{\hyperlink{group__keyname_ga8e805c726a60da921d3736cda7813513}{key\+Name()}} yourself, because the result differs from simple ascii comparison.

\begin{DoxyPrecond}{Precondition}
The Keys {\ttfamily k1} and {\ttfamily k2} have been properly initialized via \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}} or are NULL 
\end{DoxyPrecond}
\begin{DoxyInvariant}{Invariant}
All parts of the Keys remain unchanged 
\end{DoxyInvariant}
\begin{DoxyPostcond}{Postcondition}
If the result is 0, {\ttfamily k1} and {\ttfamily k2} cannot be used in the same Key\+Set
\end{DoxyPostcond}

\begin{DoxyParams}{Parameters}
{\em k1} & the first Key to be compared \\
\hline
{\em k2} & the second Key to be compared\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em $<$0} & if k1 $<$ k2 \\
\hline
{\em 0} & if k1 == k2 \\
\hline
{\em $>$0} & if k1 $>$ k2\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyset_gaa5a1d467a4d71041edce68ea7748ce45}{ks\+Append\+Key()}}, \mbox{\hyperlink{group__keyset_ga21eb9c3a14a604ee3a8bdc779232e7b7}{ks\+Append()}} will compare Keys via \mbox{\hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{key\+Cmp()}} when appending 

\mbox{\hyperlink{group__keyset_ga60f1ddcf23272f2b29b90e92ebe9b56f}{ks\+Lookup()}} will compare Keys via \mbox{\hyperlink{group__keytest_gaf6e66e12fe04d535a5d1c8218ced803e}{key\+Cmp()}} during searching 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}\label{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}} 
\index{Methods for Making Tests@{Methods for Making Tests}!keyIsBelow@{keyIsBelow}}
\index{keyIsBelow@{keyIsBelow}!Methods for Making Tests@{Methods for Making Tests}}
\doxysubsubsection{\texorpdfstring{keyIsBelow()}{keyIsBelow()}}
{\footnotesize\ttfamily int key\+Is\+Below (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key,  }\item[{const Key $\ast$}]{check }\end{DoxyParamCaption})}



Check if the Key {\ttfamily check} is below the Key {\ttfamily key} or not. 

Example\+: \begin{DoxyVerb}key user:/sw/app
check user:/sw/app/key
\end{DoxyVerb}


returns true because {\ttfamily check} is below {\ttfamily key} 

Example\+: \begin{DoxyVerb}key user:/sw/app
check user:/sw/app/folder/key
\end{DoxyVerb}


returns also true because {\ttfamily check} is indirectly below {\ttfamily key} 

Obviously, there is no Key above a namespace (e.\+g. user, system, /)\+:

\begin{DoxyVerb}key *
check user
\end{DoxyVerb}



\begin{DoxyParams}{Parameters}
{\em key} & the Key object to check against \\
\hline
{\em check} & the Key object for which it should be checked whether it is below {\ttfamily key} \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & if {\ttfamily check} is below {\ttfamily key} \\
\hline
{\em 0} & if it is not below or if it is the same key \\
\hline
{\em -\/1} & if key or check is null\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keytest_ga0150fb549225d8789e7297b919965e72}{key\+Is\+Directly\+Below()}} for checking whether a Key is directly below another 

\mbox{\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\+Get\+Name()}}, \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} for getting / setting the Key\textquotesingle{}s name 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keytest_ga9526b371087564e43e3dff8ad0dac949}\label{group__keytest_ga9526b371087564e43e3dff8ad0dac949}} 
\index{Methods for Making Tests@{Methods for Making Tests}!keyIsBinary@{keyIsBinary}}
\index{keyIsBinary@{keyIsBinary}!Methods for Making Tests@{Methods for Making Tests}}
\doxysubsubsection{\texorpdfstring{keyIsBinary()}{keyIsBinary()}}
{\footnotesize\ttfamily int key\+Is\+Binary (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Check if the value of a {\ttfamily key} is of binary type. 

The function checks if the value of {\ttfamily key} is binary. Contrary to string values binary values can have \textquotesingle{}\textbackslash{}0\textquotesingle{} inside the value and may not be terminated by a null character. Their disadvantage is that you need to pass their size.

Make sure to use this function and don\textquotesingle{}t test the binary type another way to ensure compatibility and to write less error prone programs.


\begin{DoxyParams}{Parameters}
{\em key} & the Key to check\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & if the value of {\ttfamily key} is binary \\
\hline
{\em 0} & if the value of {\ttfamily key} is not binary \\
\hline
{\em -\/1} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyvalue_ga4c0d8a4a11174197699c231e0b5c3c84}{key\+Get\+Binary()}}, \mbox{\hyperlink{group__keyvalue_gaa50a5358fd328d373a45f395fa1b99e7}{key\+Set\+Binary()}} for getting / setting a Key\textquotesingle{}s value as binary 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keytest_ga0150fb549225d8789e7297b919965e72}\label{group__keytest_ga0150fb549225d8789e7297b919965e72}} 
\index{Methods for Making Tests@{Methods for Making Tests}!keyIsDirectlyBelow@{keyIsDirectlyBelow}}
\index{keyIsDirectlyBelow@{keyIsDirectlyBelow}!Methods for Making Tests@{Methods for Making Tests}}
\doxysubsubsection{\texorpdfstring{keyIsDirectlyBelow()}{keyIsDirectlyBelow()}}
{\footnotesize\ttfamily int key\+Is\+Directly\+Below (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key,  }\item[{const Key $\ast$}]{check }\end{DoxyParamCaption})}



Check whether the Key {\ttfamily check} is directly below the Key {\ttfamily key}. 

\begin{DoxyVerb}Example:
key user:/sw/app
check user:/sw/app/key\end{DoxyVerb}


returns true because check is directly below key

\begin{DoxyVerb}Example:
key user:/sw/app
check user:/sw/app/folder/key\end{DoxyVerb}


does not return true, because it is only indirectly below


\begin{DoxyParams}{Parameters}
{\em key} & the Key object to check against \\
\hline
{\em check} & the Key object for which it should be checked whether it is directly below {\ttfamily key} \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & if {\ttfamily check} is directly below {\ttfamily key} \\
\hline
{\em 0} & if {\ttfamily check} is not directly below {\ttfamily key} or if it is the same \\
\hline
{\em -\/1} & on null pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keytest_ga03332b5d97c76a4fd2640aca4762b8df}{key\+Is\+Below()}} for checking whether a Key is below another 

\mbox{\hyperlink{group__keyname_gab29a850168d9b31c9529e90cf9ab68be}{key\+Get\+Name()}}, \mbox{\hyperlink{group__keyname_ga7699091610e7f3f43d2949514a4b35d9}{key\+Set\+Name()}} for getting / setting the Key\textquotesingle{}s name 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keytest_gaea7670778abd07fee0fe8ac12a149190}\label{group__keytest_gaea7670778abd07fee0fe8ac12a149190}} 
\index{Methods for Making Tests@{Methods for Making Tests}!keyIsString@{keyIsString}}
\index{keyIsString@{keyIsString}!Methods for Making Tests@{Methods for Making Tests}}
\doxysubsubsection{\texorpdfstring{keyIsString()}{keyIsString()}}
{\footnotesize\ttfamily int key\+Is\+String (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Check if the value of {\ttfamily key} is of string type. 

String values are null terminated and are not allowed to have any \textquotesingle{}\textbackslash{}0\textquotesingle{} characters inside the string.

Make sure to use this function and don\textquotesingle{}t test the string type another way to ensure compatibility and to write less error prone programs.


\begin{DoxyParams}{Parameters}
{\em key} & the Key to check\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & if the value of {\ttfamily key} is string \\
\hline
{\em 0} & if the value of {\ttfamily key} is not string \\
\hline
{\em -\/1} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__keyvalue_ga41b9fac5ccddafe407fc0ae1e2eb8778}{key\+Get\+String()}}, \mbox{\hyperlink{group__keyvalue_ga622bde1eb0e0c4994728331326340ef2}{key\+Set\+String()}} for getting / setting a Key\textquotesingle{}s value as string 
\end{DoxySeeAlso}
\mbox{\Hypertarget{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}\label{group__keytest_gaf247df0de7aca04b32ef80e39ef12950}} 
\index{Methods for Making Tests@{Methods for Making Tests}!keyNeedSync@{keyNeedSync}}
\index{keyNeedSync@{keyNeedSync}!Methods for Making Tests@{Methods for Making Tests}}
\doxysubsubsection{\texorpdfstring{keyNeedSync()}{keyNeedSync()}}
{\footnotesize\ttfamily int key\+Need\+Sync (\begin{DoxyParamCaption}\item[{const Key $\ast$}]{key }\end{DoxyParamCaption})}



Test if a key needs to be synced to backend storage. 

If any Key modification took place the Key will be flagged so that \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} knows which keys were modified and which not.

After \mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}} the flag will normally be set, but after \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} and \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}} the flag will be removed. When you modify the key the flag will be set again.

In your application you can make use of that flag to know if you changed something in a key after a \mbox{\hyperlink{group__kdb_ga28e385fd9cb7ccfe0b2f1ed2f62453a1}{kdb\+Get()}} or \mbox{\hyperlink{group__kdb_ga11436b058408f83d303ca5e996832bcf}{kdb\+Set()}}.

\begin{DoxyNote}{Note}
Note that the sync status will be updated on any change, including metadata.
\end{DoxyNote}
\begin{DoxyRefDesc}{Deprecated}
\item[\mbox{\hyperlink{deprecated__deprecated000003}{Deprecated}}]The handling of synchronization is done internally and does not need to be checked by neither application nor plugins.\end{DoxyRefDesc}



\begin{DoxyParams}{Parameters}
{\em key} & the Key which should be checked\\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{Return values}
{\em 1} & if {\ttfamily key} was changed in memory \\
\hline
{\em 0} & if {\ttfamily key} wasn\textquotesingle{}t changed \\
\hline
{\em -\/1} & on NULL pointer\\
\hline
\end{DoxyRetVals}
\begin{DoxySince}{Since}
1.\+0.\+0
\end{DoxySince}
\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{key\+New()}}, key\+Dup() Keys need to be synced after calling those functions 
\end{DoxySeeAlso}
