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");

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

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

k1	the first Key to be compared
k2	the second Key to be compared

Return values

<0	if k1 < k2
0	if k1 == k2
>0	if 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

key	the Key object to check against
check	the Key object for which it should be checked whether it is below key

Return values

1	if check is below key
0	if it is not below or if it is the same key
-1	if 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

key	the Key to check

Return values

1	if the value of key is binary
0	if the value of key is not binary
-1	on 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

key	the Key object to check against
check	the Key object for which it should be checked whether it is directly below key

Return values

1	if check is directly below key
0	if check is not directly below key or if it is the same
-1	on 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

key	the Key to check

Return values

1	if the value of key is string
0	if the value of key is not string
-1	on NULL pointer

See also

keyGetString(), keySetString() for getting / setting a Key's value as string