NAME

       api - API Proposals for Elektra

       for kdb.h.

   Functions
       ssize_t keySetStringF (Key *key, const char *format,...)
           Set a formatted string.
       int elektraArrayIncName (Key *key)
           Increment the name of the key by one.
       int elektraKsToMemArray (KeySet *ks, Key **buffer)
           Builds an array of pointers to the keys in the supplied keyset.
       int elektraKsFilter (KeySet *result, KeySet *input, int(*filter)(const Key *k, void
           *argument), void *argument)
           return only those keys from the given keyset that pass the supplied filter function
           with the supplied argument
       KeySet * elektraRenameKeys (KeySet *config, const char *name)
           Takes the first key and cuts off this common part for all other keys, instead name
           will be prepended.
       elektraNamespace keyGetNamespace (const Key *key)
           For currently valid namespaces see elektraNamespace.
       int keyLock (Key *key, enum elektraLockOptions what)
           Permanently locks a part of the key.
       KeySet * elektraArrayGet (const Key *arrayParent, KeySet *keys)
           Return all the array keys below the given arrayparent The arrayparent itself is not
           returned.
       Key * elektraArrayGetNextKey (KeySet *arrayKeys)
           Return the next key in the given array.
       KeySet * elektraKeyGetMetaKeySet (const Key *key)
           Return meta data as keyset.
       Key * ksPrev (KeySet *ks)
           Returns the previous Key in a KeySet.
       Key * ksPopAtCursor (KeySet *ks, cursor_t pos)
           Pop key at given cursor position.

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

   KeySet* elektraArrayGet (const Key * arrayParent, KeySet * keys)
       Return all the array keys below the given arrayparent The arrayparent itself is not
       returned. For example, if user/config/# is an array, user/config is the array parent. Only
       the direct array keys will be returned. This means that for example user/config/#1/key
       will not be included, but only user/config/#1.

       A new keyset will be allocated for the resulting keys. This means that the caller must
       ksDel the resulting keyset.

       Parameters:
           arrayParent the parent of the array to be returned
           keys the keyset containing the array keys.

       Returns:
           a keyset containing the arraykeys (if any)

       Return values:
           NULL on NULL pointers

   Key* elektraArrayGetNextKey (KeySet * arrayKeys)
       Return the next key in the given array. The function will automatically allocate memory
       for a new key and name it accordingly.

       Precondition:
           The supplied keyset must contain only valid array keys.

       The caller has to keyDel the resulting key.

       Parameters:
           arraykeys the array where the new key will belong to

       Returns:
           the new array key on success

       Return values:
           NULL if the passed array is empty
           NULL on NULL pointers or if an error occurs

   int elektraArrayIncName (Key * key)
       Increment the name of the key by one. Alphabetical order will remain

       e.g. user/abc/#9 will be changed to user/abc/#_10

       For the start: user/abc/# will be changed to user/abc/#0

       Parameters:
           key which base name will be incremented

       Return values:
           -1 on error (e.g. too large array, not validated array)
           0 on success

   KeySet* elektraKeyGetMetaKeySet (const Key * key)
       Return meta data as keyset.

       Parameters:
           key the key object to work with

       Returns:
           a duplication of the keyset representing the meta data

   int elektraKsFilter (KeySet * result, KeySet * input, int(*)(const Key *k, void *argument)
       filter, void * argument)
       return only those keys from the given keyset that pass the supplied filter function with
       the supplied argument

       Parameters:
           result the keyset that should contain the filtered keys
           input the keyset whose keys should be filtered
           filter a function pointer to a function that will be used to filter the keyset. A key
           will be taken if the function returns a value greater than 0.
           argument an argument that will be passed to the filter function each time it is called

       Returns:
           the number of filtered keys if the filter function always returned a positive value,
           -1 otherwise

       Return values:
           NULL on NULL pointer

   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:

       1 KeySet *ks = somekeyset;
       2 Key **keyArray = calloc (ksGetSize(ks), sizeof (Key *));
       3 elektraKsToMemArray (ks, keyArray);
       4 ... work with the array ...
       5 free (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

   KeySet* elektraRenameKeys (KeySet * config, const char * 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.

   elektraNamespace keyGetNamespace (const Key * key)
       For currently valid namespaces see elektraNamespace.

       Since:
           0.8.10 Added method to kdbproposal.h

       To handle every possible cases (including namespaces) a key can have:

       switch (keyGetNamespace(k))
       {
       case KEY_NS_SPEC:
               printf ("spec namespace0);
               break;
       case KEY_NS_PROC:
               printf ("proc namespace0);
               break;
       case KEY_NS_DIR:
               printf ("dir namespace0);
               break;
       case KEY_NS_USER:
               printf ("user namespace0);
               break;
       case KEY_NS_SYSTEM:
               printf ("system namespace0);
               break;
       case KEY_NS_EMPTY:
               printf ("empty name0);
               break;
       case KEY_NS_NONE:
               printf ("no key0);
               break;
       case KEY_NS_META:
               printf ("meta key0);
               break;
       case KEY_NS_CASCADING:
               printf ("cascading key0);
               break;
       }

        To loop over all valid namespaces use:

       for (elektraNamespace ns=KEY_NS_FIRST; ns<=KEY_NS_LAST; ++ns)
       {
               // work with namespace
               printf ("%d0, ns);
       }

       Note:
           This method might be enhanced. You do not have any guarantee that, when for a specific
           name KEY_NS_META is returned today, that it still will be returned after the next
           recompilation. So make sure that your compiler gives you a warning for unhandled
           switches (gcc: -Wswitch or -Wswitch-enum if you want to handle default) and look out
           for those warnings.

       Parameters:
           key the key object to work with

       Returns:
           the namespace of a key.

   int keyLock (Key * key, enum elektraLockOptions 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 meta data

       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)

   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)

   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:

       1 cursor_t c = ksGetCursor(ks);
       2 keyDel (ksPopAtCursor(ks, c));
       3 ksSetCursor(ks, c);
       4 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

   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()

Author

       Generated automatically by Doxygen for Elektra from the source code.