| Elektra 0.11.0

Functions
Methods for Making Tests
Key

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

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

## 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");
keyCmp
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
keyNew
Key * keyNew(const char *name,...)
A practical way to fully create a Key object in one step.
Definition key.c:144

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