\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_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}
