$darkmode
Elektra 0.11.0
Functions
Methods for Making Tests

Methods to do various tests on Keys. More...

Collaboration diagram for Methods for Making Tests:

Functions

int keyCmp (const Key *k1, const Key *k2)
 Compare the name of two Keys. More...
 
int keyIsBelow (const Key *key, const Key *check)
 Check if the Key check is below the Key key or not. More...
 
int keyIsDirectlyBelow (const Key *key, const Key *check)
 Check whether the Key check is directly below the Key key. More...
 
int keyIsBinary (const Key *key)
 Check if the value of a key is of binary type. More...
 
int keyIsString (const Key *key)
 Check if the value of key is of string type. More...
 

Detailed Description

Methods to do various tests on Keys.

With exception of the parameters of keyCmp(), the following contract holds for all parameters of type Key:

Precondition
The Key has been properly initialized via keyNew()
Invariant
All parts of the Key remain unchanged
Postcondition
All parts of the Key are unchanged

To use them:

#include <kdb.h>

Function Documentation

◆ keyCmp()

int keyCmp ( const Key *  k1,
const Key *  k2 
)

Compare the name of two Keys.

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

keyCmp() defines the sorting order for a KeySet.

The following 3 points are the rules for NULL values:

  • A NULL pointer will be found to be smaller than every other Key. If both are NULL pointers, 0 is returned.
  • A NULL name will be found to be smaller than every other name. If both are NULL names, 0 is returned.

If the name is equal then:

  • No owner will be found to be smaller than every other owner. If both don't have an owner, 0 is returned.
Note
the owner will only be used if the names are equal.

Given any Keys k1 and k2 constructed with keyNew(), following equation hold true:

succeed_if (keyCmp (0, 0) == 0, "all null pointers same");
succeed_if (keyCmp (k1, 0) == 1, "null pointer is smaller");
succeed_if (keyCmp (0, k2) == -1, "null pointer is smaller");
int keyCmp(const Key *k1, const Key *k2)
Compare the name of two Keys.
Definition: keyset.c:768

Here are some more examples:

Key *k1 = keyNew("user:/a", KEY_END);
Key *k2 = keyNew("user:/b", KEY_END);
// keyCmp(k1,k2) < 0
// keyCmp(k2,k1) > 0
Key * keyNew(const char *name,...)
A practical way to fully create a Key object in one step.
Definition: key.c:144
@ KEY_END
Definition: kdbenum.c:95

Do not strcmp the keyName() yourself, because the result differs from simple ascii comparison.

Precondition
The Keys k1 and k2 have been properly initialized via keyNew() or are NULL
Invariant
All parts of the Keys remain unchanged
Postcondition
If the result is 0, k1 and k2 cannot be used in the same KeySet
Parameters
k1the first Key to be compared
k2the second Key to be compared
Return values
<0if k1 < k2
0if k1 == k2
>0if k1 > k2
Since
1.0.0
See also
ksAppendKey(), ksAppend() will compare Keys via keyCmp() when appending
ksLookup() will compare Keys via keyCmp() during searching

◆ keyIsBelow()

int keyIsBelow ( const Key *  key,
const Key *  check 
)

Check if the Key check is below the Key key or not.

Example:

key user:/sw/app
check user:/sw/app/key

returns true because check is below key

Example:

key user:/sw/app
check user:/sw/app/folder/key

returns also true because check is indirectly below key

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

key *
check user
Parameters
keythe Key object to check against
checkthe Key object for which it should be checked whether it is below key
Return values
1if check is below key
0if it is not below or if it is the same key
-1if key or check is null
Since
1.0.0
See also
keyIsDirectlyBelow() for checking whether a Key is directly below another
keyGetName(), keySetName() for getting / setting the Key's name

◆ keyIsBinary()

int keyIsBinary ( const Key *  key)

Check if the value of a key is of binary type.

The function checks if the value of key is binary. Contrary to string values binary values can have '\0' 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't test the binary type another way to ensure compatibility and to write less error prone programs.

Parameters
keythe Key to check
Return values
1if the value of key is binary
0if the value of key is not binary
-1on NULL pointer
See also
keyGetBinary(), keySetBinary() for getting / setting a Key's value as binary

◆ keyIsDirectlyBelow()

int keyIsDirectlyBelow ( const Key *  key,
const Key *  check 
)

Check whether the Key check is directly below the Key key.

Example:
key user:/sw/app
check user:/sw/app/key

returns true because check is directly below key

Example:
key user:/sw/app
check user:/sw/app/folder/key

does not return true, because it is only indirectly below

Parameters
keythe Key object to check against
checkthe Key object for which it should be checked whether it is directly below key
Return values
1if check is directly below key
0if check is not directly below key or if it is the same
-1on null pointer
Since
1.0.0
See also
keyIsBelow() for checking whether a Key is below another
keyGetName(), keySetName() for getting / setting the Key's name

◆ keyIsString()

int keyIsString ( const Key *  key)

Check if the value of key is of string type.

String values are null terminated and are not allowed to have any '\0' characters inside the string.

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

Parameters
keythe Key to check
Return values
1if the value of key is string
0if the value of key is not string
-1on NULL pointer
See also
keyGetString(), keySetString() for getting / setting a Key's value as string