Elektra: API Proposals for Elektra

Elektra 0.8.24

Functions
API Proposals for Elektra
Proposals for Elektra

for kdb.h. More...

## Functions
ssize_t | keySetStringF (Key *key, const char *format,...)
| Set a formatted string. More...
int | elektraKsToMemArray (KeySet *ks, Key **buffer)
| Builds an array of pointers to the keys in the supplied keyset. More...
KeySet * | ksRenameKeys (KeySet *config, const Key *name)
| Takes the first key and cuts off this common part for all other keys, instead name will be prepended. More...
int | keyLock (Key *key, option_t what)
| Permanently locks a part of the key. More...
KeySet * | elektraKeyGetMetaKeySet (const Key *key)
| Return metadata as keyset. More...
Key * | ksPrev (KeySet *ks)
| Returns the previous Key in a KeySet. More...
Key * | ksPopAtCursor (KeySet *ks, cursor_t pos)
| Pop key at given cursor position. More...
Key * | keyAsCascading (const Key *key)
| keyRel replacement
int | keyRel2 (const Key *key, const Key *check, KeyRelType which)
| Replacement proposal for keyRel. More...

## Detailed Description

for kdb.h.

Warning
  Do not use these methods if you do not want to depend on exactly the Elektra version your binary was built for.

These methods are a technical preview of what might be added in future Elektra releases. It is a requirement that methods are first added here, before they are added to the public API.

Usually, names in proposal stage should be prefixed with elektra to clearly mark that the signature is likely to be changed and not yet ABI compatible.

## Function Documentation

## ◆ elektraKeyGetMetaKeySet()

KeySet* elektraKeyGetMetaKeySet | ( | const Key * | key | ) |

Return metadata as keyset.

Parameters

  key | the key object to work with

Returns
  a duplication of the keyset representing the metadata

## ◆ elektraKsToMemArray()

int elektraKsToMemArray | ( | KeySet * | ks,
|  | Key ** | buffer
| ) |  |

Builds an array of pointers to the keys in the supplied keyset.

The keys are not copied, calling keyDel may remove them from the keyset.

The size of the buffer can be easily allocated via ksGetSize. Example:

KeySet *ks = somekeyset;
Key **keyArray = calloc (ksGetSize(ks), sizeof (Key *));
elektraKsToMemArray (ks, keyArray);
... work with the array ...
elektraFree (keyArray);

Parameters

  ks | the keyset object to work with
  buffer | the buffer to put the result into

Returns
  the number of elements in the array if successful
  a negative number on null pointers or if an error occurred

## ◆ keyLock()

int keyLock | ( | Key * | key,
|  | option_t | what
| ) |  |

Permanently locks a part of the key.

This can be:

- KEY_FLAG_LOCK_NAME to lock the name
- KEY_FLAG_LOCK_VALUE to lock the value
- KEY_FLAG_LOCK_META to lock the metadata

To unlock the key, duplicate it.

It is also possible to lock when the key is created with keyNew().

Some data structures need to lock the key (most likely its name), so that the ordering does not get confused.

Parameters

  key | which name should be locked

See also
  keyNew(), keyDup(), ksAppendKey()

Return values

  >0 | the bits that were successfully locked
  0 | if everything was locked before
  -1 | if it could not be locked (nullpointer)

## ◆ keyRel2()

int keyRel2 | ( | const Key * | key,
|  | const Key * | check,
|  | KeyRelType | which
| ) |  |

Replacement proposal for keyRel.

Returns
  depending on relation type

Return values

  -1 | usage error
  0 | test failed
  >1 | true for binary tests, number of levels below for other relation tests

Parameters

  key | the key object to work with
  check | the second key object to check the relation with
  which | what kind of relationship test should be done

## ◆ keySetStringF()

ssize_t keySetStringF | ( | Key * | key,
|  | const char * | format,
|  |  | ...
| ) |  |

Set a formatted string.

Parameters

  key | the key to set the string value
  format | NULL-terminated text format string
  ... | more arguments

Returns
  the size of the string as set (with including 0)

## ◆ ksPopAtCursor()

Key* ksPopAtCursor | ( | KeySet * | ks,
|  | cursor_t | pos
| ) |  |

Pop key at given cursor position.

Parameters

  ks | the keyset to pop key from
  c | where to pop

The internal cursor will be rewinded using ksRewind(). You can use ksGetCursor() and ksSetCursor() jump back to the previous position. e.g. to pop at current position within ksNext() loop:

cursor_t c = ksGetCursor(ks);
keyDel (ksPopAtCursor(ks, c));
ksSetCursor(ks, c);
ksPrev(ks); // to have correct key after next ksNext()

Warning
  do not use, will be superseded by external iterator API

Returns
  the popped key

Return values

  0 | if ks is 0

## ◆ ksPrev()

Key* ksPrev | ( | KeySet * | ks | ) |

Returns the previous Key in a KeySet.

KeySets have an internal cursor that can be reset with ksRewind(). Every time ksPrev() is called the cursor is decremented and the new current Key is returned.

You'll get a NULL pointer if the key before begin of the KeySet was reached.

Don't delete the key, use ksPop() if you want to delete it.

Returns
  the new current Key

See also
  ksRewind(), ksCurrent()

## ◆ ksRenameKeys()

KeySet* ksRenameKeys | ( | KeySet * | config,
|  | const Key * | name
| ) |  |

Takes the first key and cuts off this common part for all other keys, instead name will be prepended.

Returns
  a new allocated keyset with keys in user namespace.

The first key is removed in the resulting keyset.