A keyset holds together a set of keys.
Methods to manipulate KeySets. A KeySet is a sorted set of keys. So the correct name actually would be KeyMap.With ksNew() you can create a new KeySet.You can add keys with ksAppendKey() in the keyset. Using ksAppend() you can append a whole keyset.
- Note
- Because the key is not copied, also the pointer to the current metadata keyNextMeta() will be shared.
ksGetSize() tells you the current size of the keyset.With
ksRewind() and
ksNext() you can navigate through the keyset. Don't expect any particular order, but it is assured that you will get every key of the set.KeySets have an
internal cursor . This is used for
ksLookup() and
kdbSet().KeySet has a fundamental meaning inside elektra. It makes it possible to get and store many keys at once inside the database. In addition to that the class can be used as high level datastructure in applications. With
ksLookupByName() it is possible to fetch easily specific keys out of the list of keys.You can easily create and iterate keys:
#include <kdb.h>
KeySet *myConfig =
ksNew(20,
KS_END);
Key *current;
while ((current=
ksNext(myConfig))!=0)
{
printf(
"Key name is %s.\n",
keyName (current));
}
- Invariant
- always holds an underlying elektra keyset.
- Note
- that the cursor is mutable, so it might be changed even in const functions as described.
Creates a new empty keyset with no keys
Allocate, initialize and return a new KeySet object.Objects created with ksNew() must be destroyed with ksDel().You can use a various long list of parameters to preload the keyset with a list of keys. Either your first and only parameter is 0 or your last parameter must be KEY_END.So, terminate with ksNew(0, KS_END) or ksNew(20, ..., KS_END)For most uses
goes ok, the alloc size will be 16, defined in kdbprivate.h. The alloc size will be doubled whenever size reaches alloc size, so it also performs out large keysets.But if you have any clue how large your keyset may be you should read the next statements.If you want a keyset with length 15 (because you know of your application that you normally need about 12 up to 15 keys), use:
keyNew (
"user/sw/app/fixedConfiguration/key01", KEY_SWITCH_VALUE,
"value01", 0),
keyNew (
"user/sw/app/fixedConfiguration/key02", KEY_SWITCH_VALUE,
"value02", 0),
keyNew (
"user/sw/app/fixedConfiguration/key03", KEY_SWITCH_VALUE,
"value03", 0),
keyNew (
"user/sw/app/fixedConfiguration/key15", KEY_SWITCH_VALUE,
"value15", 0),
KS_END);
If you start having 3 keys, and your application needs approximately 200-500 keys, you can use:
keyNew (
"user/sw/app/fixedConfiguration/key1", KEY_SWITCH_VALUE,
"value1", 0),
keyNew (
"user/sw/app/fixedConfiguration/key2", KEY_SWITCH_VALUE,
"value2", 0),
keyNew (
"user/sw/app/fixedConfiguration/key3", KEY_SWITCH_VALUE,
"value3", 0),
KS_END);
Alloc size is 500, the size of the keyset will be 3 after ksNew. This means the keyset will reallocate when appending more than 497 keys.The main benefit of taking a list of variant length parameters is to be able to have one C-Statement for any possible KeySet.
- Postcondition
- the keyset is rewinded properly
- See Also
- ksDel() to free the KeySet afterwards
-
ksDup() to duplicate an existing KeySet
- Parameters
-
alloc | gives a hint for the size how many Keys may be stored initially |
- Returns
- a ready to use KeySet object
-
0 on memory error
kdb::KeySet::KeySet |
( |
size_t |
alloc, |
|
|
va_list |
ap |
|
) |
| |
|
inlineexplicit |
Create a new keyset.
- Parameters
-
alloc | minimum number of keys to allocate |
ap | variable arguments list |
Allocate, initialize and return a new KeySet object.Objects created with ksNew() must be destroyed with ksDel().You can use a various long list of parameters to preload the keyset with a list of keys. Either your first and only parameter is 0 or your last parameter must be KEY_END.So, terminate with ksNew(0, KS_END) or ksNew(20, ..., KS_END)For most uses
goes ok, the alloc size will be 16, defined in kdbprivate.h. The alloc size will be doubled whenever size reaches alloc size, so it also performs out large keysets.But if you have any clue how large your keyset may be you should read the next statements.If you want a keyset with length 15 (because you know of your application that you normally need about 12 up to 15 keys), use:
keyNew (
"user/sw/app/fixedConfiguration/key01", KEY_SWITCH_VALUE,
"value01", 0),
keyNew (
"user/sw/app/fixedConfiguration/key02", KEY_SWITCH_VALUE,
"value02", 0),
keyNew (
"user/sw/app/fixedConfiguration/key03", KEY_SWITCH_VALUE,
"value03", 0),
keyNew (
"user/sw/app/fixedConfiguration/key15", KEY_SWITCH_VALUE,
"value15", 0),
KS_END);
If you start having 3 keys, and your application needs approximately 200-500 keys, you can use:
keyNew (
"user/sw/app/fixedConfiguration/key1", KEY_SWITCH_VALUE,
"value1", 0),
keyNew (
"user/sw/app/fixedConfiguration/key2", KEY_SWITCH_VALUE,
"value2", 0),
keyNew (
"user/sw/app/fixedConfiguration/key3", KEY_SWITCH_VALUE,
"value3", 0),
KS_END);
Alloc size is 500, the size of the keyset will be 3 after ksNew. This means the keyset will reallocate when appending more than 497 keys.The main benefit of taking a list of variant length parameters is to be able to have one C-Statement for any possible KeySet.
- Postcondition
- the keyset is rewinded properly
- See Also
- ksDel() to free the KeySet afterwards
-
ksDup() to duplicate an existing KeySet
- Parameters
-
alloc | gives a hint for the size how many Keys may be stored initially |
- Returns
- a ready to use KeySet object
-
0 on memory error
- Precondition
- caller must call va_start and va_end
- va the list of arguments
- Parameters
-
alloc | the allocation size |
va | the list of variable arguments |
kdb::KeySet::KeySet |
( |
size_t |
alloc, |
|
|
|
... |
|
) |
| |
|
inlineexplicit |
Create a new keyset.
- Parameters
-
alloc | minimum number of keys to allocate |
... | variable argument list |
Allocate, initialize and return a new KeySet object.Objects created with ksNew() must be destroyed with ksDel().You can use a various long list of parameters to preload the keyset with a list of keys. Either your first and only parameter is 0 or your last parameter must be KEY_END.So, terminate with ksNew(0, KS_END) or ksNew(20, ..., KS_END)For most uses
goes ok, the alloc size will be 16, defined in kdbprivate.h. The alloc size will be doubled whenever size reaches alloc size, so it also performs out large keysets.But if you have any clue how large your keyset may be you should read the next statements.If you want a keyset with length 15 (because you know of your application that you normally need about 12 up to 15 keys), use:
keyNew (
"user/sw/app/fixedConfiguration/key01", KEY_SWITCH_VALUE,
"value01", 0),
keyNew (
"user/sw/app/fixedConfiguration/key02", KEY_SWITCH_VALUE,
"value02", 0),
keyNew (
"user/sw/app/fixedConfiguration/key03", KEY_SWITCH_VALUE,
"value03", 0),
keyNew (
"user/sw/app/fixedConfiguration/key15", KEY_SWITCH_VALUE,
"value15", 0),
KS_END);
If you start having 3 keys, and your application needs approximately 200-500 keys, you can use:
keyNew (
"user/sw/app/fixedConfiguration/key1", KEY_SWITCH_VALUE,
"value1", 0),
keyNew (
"user/sw/app/fixedConfiguration/key2", KEY_SWITCH_VALUE,
"value2", 0),
keyNew (
"user/sw/app/fixedConfiguration/key3", KEY_SWITCH_VALUE,
"value3", 0),
KS_END);
Alloc size is 500, the size of the keyset will be 3 after ksNew. This means the keyset will reallocate when appending more than 497 keys.The main benefit of taking a list of variant length parameters is to be able to have one C-Statement for any possible KeySet.
- Postcondition
- the keyset is rewinded properly
- See Also
- ksDel() to free the KeySet afterwards
-
ksDup() to duplicate an existing KeySet
- Parameters
-
alloc | gives a hint for the size how many Keys may be stored initially |
- Returns
- a ready to use KeySet object
-
0 on memory error
- Precondition
- caller must call va_start and va_end
- va the list of arguments
- Parameters
-
alloc | the allocation size |
va | the list of variable arguments |
ssize_t kdb::KeySet::append |
( |
const Key & |
toAppend | ) |
|
|
inline |
append a key
- Parameters
-
- Returns
- number of keys in the keyset
Appends a Key to the end of ks
.A pointer to the key will be stored, and not a private copy. So a future ksDel() on ks
may keyDel() the toAppend
object, see keyGetRef().The reference counter of the key will be incremented, and thus toAppend is not const.
- Note
- Because the key is not copied, also the pointer to the current metadata keyNextMeta() will be shared.
If the keyname already existed, it will be replaced with the new key.The
KeySet internal cursor will be set to the new key.It is save to use ksAppendKey(ks, keyNew(..)).
- Returns
- the size of the KeySet after insertion
-
-1 on NULL pointers
-
-1 if insertion failed, the key will be deleted then.
- Parameters
-
ks | KeySet that will receive the key |
toAppend | Key that will be appended to ks or deleted |
- See Also
- ksAppend(), keyNew(), ksDel()
-
keyIncRef()