Elektra: kdb::Key Class Reference

Elektra 0.8.14

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files

- Data Structures
- Class Hierarchy
- Data Fields

Public Member Functions
kdb::Key Class Reference

More...

`#include <key.hpp>`

## Public Member Functions
| Key ()
| Constructs an empty, invalid key. More...
| Key (ckdb::Key *k)
| Constructs a key out of a C key. More...
| Key (Key &k)
| Takes a reference of another key. More...
| Key (Key const &k)
| Takes a reference of another key. More...
| Key (const char *keyName,...)
| Key (const std::string keyName,...)
| Key (const char *keyName, va_list ap)
void | operator++ (int) const
void | operator++ () const
void | operator-- (int) const
void | operator-- () const
ssize_t | getReferenceCounter () const
Key & | operator= (ckdb::Key *k)
| Assign a C key. More...
Key & | operator= (const Key &k)
| Assign a key. More...
void | copy (const Key &other)
void | clear ()
| Clears/Invalidates a key. More...
Key * | operator-> ()
ckdb::Key * | getKey () const
| Passes out the raw key pointer. More...
ckdb::Key * | operator* () const
| Is a abbreviation for getKey. More...
ckdb::Key * | release ()
| Passes out the raw key pointer and resets internal key handle. More...
ckdb::Key * | dup () const
| ~Key ()
| Destructs the key. More...
std::string | getName () const
ssize_t | getNameSize () const
std::string | getBaseName () const
ssize_t | getBaseNameSize () const
void | setName (const std::string &newName)
void | setBaseName (const std::string &baseName)
| Sets a base name for a key. More...
void | addBaseName (const std::string &baseName)
| Adds a base name for a key. More...
ssize_t | getFullNameSize () const
std::string | getFullName () const
bool | operator== (const Key &k) const
bool | operator!= (const Key &k) const
bool | operator< (const Key &other) const
bool | operator<= (const Key &other) const
bool | operator> (const Key &other) const
bool | operator>= (const Key &other) const
bool | isNull () const
| Checks if C++ wrapper has an underlying key. More...
| operator bool () const
| This is for loops and lookups only. More...
bool | needSync () const
template<class T >
T | get () const
| Get a key value. More...
template<class T >
void | set (T x)
| Set a key value. More...
std::string | getString () const
void | setString (std::string newString)
ssize_t | getStringSize () const
func_t | getFunc () const
| Elektra can store function pointers as binary. More...
const void * | getValue () const
std::string | getBinary () const
ssize_t | getBinarySize () const
ssize_t | setBinary (const void *newBinary, size_t dataSize)
bool | hasMeta (const std::string &metaName) const
template<class T >
T | getMeta (const std::string &metaName) const
template<class T >
void | setMeta (const std::string &metaName, T x)
| Set metadata for key. More...
void | delMeta (const std::string &metaName)
| Delete metadata for key. More...
void | copyMeta (const Key &other, const std::string &metaName)
void | copyAllMeta (const Key &other)
void | rewindMeta () const
const Key | nextMeta ()
const Key | currentMeta () const
bool | isValid () const
std::string | getNamespace () const
bool | isSystem () const
| Name starts with "system". More...
bool | isUser () const
| Name starts with "user". More...
bool | isString () const
bool | isBinary () const
bool | isInactive () const
bool | isBelow (const Key &k) const
bool | isBelowOrSame (const Key &k) const
bool | isDirectBelow (const Key &k) const

## Detailed Description

This class is an wrapper for an optional, refcounted ckdb::Key. It is like an shared_ptr<ckdb::Key>, but the shared_ptr functionality is already within the Key and exposed with this wrapper.

optional
  A key can be constructed with an null pointer, by using Key (static_cast<ckdb::Key*>(0)); or made empty afterwards by using release() or assign a null key. To check if there is an associated managed object the user can use isNull().

references
  Copies of keys are cheap because they are only flat. If you really need a deep copy, you can use copy() or dup(). If you release() an object, the reference counter will stay All other operations operate on references.

documentation
  Note that the documentation is typically copied from the underlying function which is wrapped and sometimes extended with C++ specific details. So you might find C examples within the C++ documentation.

Invariant
  Key either has a working underlying Elektra Key object or a null pointer. The Key, however, might be invalid (see isValid()) or null (see isNull()).

Note
  that the reference counting in the keys is mutable, so that const keys can be passed around by value.

## Constructor & Destructor Documentation

kdb::Key::Key | ( |  | ) |
| inline

Constructs an empty, invalid key.

Note
  That this is not a null key, so the key will evaluate to true.

See also
  isValid(), isNull()

kdb::Key::Key | ( | ckdb::Key * | k | ) |
| inline

Constructs a key out of a C key.

Note
  If you pass a null pointer here, the key will evaluate to false.

Parameters

  k | the key to work with

See also
  isValid(), isNull()

kdb::Key::Key | ( | Key & | k | ) |
| inline

Takes a reference of another key.

The key will not be copied, but the reference counter will be increased.

Parameters

  k | the key to work with

kdb::Key::Key | ( | Key const & | k | ) |
| inline

Takes a reference of another key.

The key will not be copied, but the reference counter will be increased.

Parameters

  k | the key to work with

kdb::Key::Key | ( | const char * | keyName,
|  |  | ...
| ) |  |
| inlineexplicit

Exceptions

  bad_alloc | if key could not be constructed (allocation problems)

Parameters

  keyName | the name of the new key

kdb::Key::Key | ( | const std::string | keyName,
|  |  | ...
| ) |  |
| inlineexplicit

Exceptions

  bad_alloc | if key could not be constructed (allocation problems)

Warning
  Not supported on some compilers, e.g. clang which require you to only pass non-POD in varg lists.

Parameters

  keyName | the name of the new key

kdb::Key::Key | ( | const char * | keyName,
|  | va_list | ap
| ) |  |
| inlineexplicit

Exceptions

  bad_alloc | if key could not be constructed (allocation problems)

Parameters

  keyName | the name of the new key
  ap | the variable argument list pointer

kdb::Key::~Key | ( |  | ) |
| inline

Destructs the key.

See also
  del()

## Member Function Documentation

void kdb::Key::addBaseName | ( | const std::string & | baseName | ) |
| inline

Adds a base name for a key.

Exceptions

  KeyInvalidName | if the name is not valid

void kdb::Key::clear | ( |  | ) |
| inline

Clears/Invalidates a key.

Afterwards the object is empty again.

Note
  This is not a null key, so it will evaluate to true. isValid() will, however, be false.

See also
  release()
  isValid(), isNull()

void kdb::Key::copy | ( | const Key & | other | ) |
| inline

void kdb::Key::copyAllMeta | ( | const Key & | other | ) |
| inline

See also
  getMeta(), setMeta(), copyMeta()

void kdb::Key::copyMeta | ( | const Key & | other,
|  | const std::string & | metaName
| ) |  |
| inline

See also
  getMeta(), setMeta(), copyAllMeta()

const Key kdb::Key::currentMeta | ( |  | ) | const
| inline

Note
  that the key will be null if last meta data is found.

k.rewindMeta();
while (meta = k.nextMeta())
{
cout << meta.getName() << " " << meta.getString() << endl;
}

See also
  rewindMeta(), nextMeta()

void kdb::Key::delMeta | ( | const std::string & | metaName | ) |
| inline

Delete metadata for key.

See also
  setMeta(), getMeta(), copyMeta(), copyAllMeta()

ckdb::Key * kdb::Key::dup | ( |  | ) | const
| inline

template<class T >

T kdb::Key::get | ( |  | ) | const
| inline

Get a key value.

You can write your own template specialication, e.g.:

template <>
inline QColor Key::get() const
{
if (getStringSize() < 1)
{
throw KeyTypeConversion();
}
std::string str = getString();
QColor c(str.c_str());
return c;
}

Returns
  the string directly from the key.

It should be the same as get().

Returns
  empty string on null pointers

Exceptions

  KeyException | on null key or not a valid size
  KeyTypeMismatch | if key holds binary data and not a string

Note
  unlike in the C version, it is safe to change the returned string.

See also
  isString(), getBinary()

This method tries to serialise the string to the given type.

std::string kdb::Key::getBaseName | ( |  | ) | const
| inline

ssize_t kdb::Key::getBaseNameSize | ( |  | ) | const
| inline

std::string kdb::Key::getBinary | ( |  | ) | const
| inline

Returns
  the binary Value of the key.

Return values

  "" | on null pointers (size == 0) and on data only containing \0

Note
  if you need to distinguish between null pointers and data containing \0 you can use getValue().

Exceptions

  KeyException | on invalid binary size
  KeyTypeMismatch | if key is string and not a binary

See also
  isBinary(), getString(), getValue()

ssize_t kdb::Key::getBinarySize | ( |  | ) | const
| inline

std::string kdb::Key::getFullName | ( |  | ) | const
| inline

Exceptions

  KeyException | if key is null

ssize_t kdb::Key::getFullNameSize | ( |  | ) | const
| inline

Key::func_t kdb::Key::getFunc | ( |  | ) | const
| inline

Elektra can store function pointers as binary.

This function returns such a function pointer.

Exceptions

  KeyTypeMismatch | if no binary data found, or binary data has not correct length

Returns
  a function pointer stored with setBinary()

ckdb::Key * kdb::Key::getKey | ( |  | ) | const
| inline

Passes out the raw key pointer.

This pointer can be used to directly change the underlying key object.

Note
  that the ownership remains in the object

template<class T >

T kdb::Key::getMeta | ( | const std::string & | metaName | ) | const
| inline

You can specify your own template specialisation:

template<>
inline yourtype Key::getMeta(const std::string &name) const
{
yourtype x;
std::string str;
str = std::string(
static_cast<const char*>(
ckdb::keyValue(
ckdb::keyGetMeta(key, name.c_str())
)
)
);
return yourconversion(str);
}

Exceptions

  KeyTypeConversion | if meta data could not be parsed

Note
  No exception will be thrown if a const Key or char* is requested, but don't forget the const: getMeta<const Key>, otherwise you will get an compiler error.

If no meta is available:

- char* is null (evaluates to 0)
- const Key is null (evaluate to false)
- otherwise the default constructed type will be returned
  See also
    hasMeta
    delMeta(), setMeta(), copyMeta(), copyAllMeta()

std::string kdb::Key::getName | ( |  | ) | const
| inline

Exceptions

  KeyException | if key is null

Note
  unlike in the C version, it is safe to change the returned string.

ssize_t kdb::Key::getNameSize | ( |  | ) | const
| inline

std::string kdb::Key::getNamespace | ( |  | ) | const
| inline

Returns
  namespace as string

Will return slash for cascading names.

See also
  getName(), isUser(), isSystem()

ssize_t kdb::Key::getReferenceCounter | ( |  | ) | const
| inline

std::string kdb::Key::getString | ( |  | ) | const
| inline

Returns
  the string directly from the key.

It should be the same as get().

Returns
  empty string on null pointers

Exceptions

  KeyException | on null key or not a valid size
  KeyTypeMismatch | if key holds binary data and not a string

Note
  unlike in the C version, it is safe to change the returned string.

See also
  isString(), getBinary()

ssize_t kdb::Key::getStringSize | ( |  | ) | const
| inline

const void * kdb::Key::getValue | ( |  | ) | const
| inline

Returns
  the value of the key

See also
  getBinary()

bool kdb::Key::hasMeta | ( | const std::string & | metaName | ) | const
| inline

Return values

  true | if there is a metadata with given name
  false | if no such metadata exists

See also
  getMeta()

bool kdb::Key::isBelow | ( | const Key & | k | ) | const
| inline

Parameters

  k | the other key

Returns
  true if our key is below k

bool kdb::Key::isBelowOrSame | ( | const Key & | k | ) | const
| inline

Parameters

  k | the other key

Returns
  true if our key is below k or the same as k

bool kdb::Key::isBinary | ( |  | ) | const
| inline

bool kdb::Key::isDirectBelow | ( | const Key & | k | ) | const
| inline

Parameters

  k | the other key

Returns
  true if our key is direct below k

bool kdb::Key::isInactive | ( |  | ) | const
| inline

bool kdb::Key::isNull | ( |  | ) | const
| inline

Checks if C++ wrapper has an underlying key.

See also
  operator bool(), isValid()

Returns
  true if no underlying key exists

bool kdb::Key::isString | ( |  | ) | const
| inline

bool kdb::Key::isSystem | ( |  | ) | const
| inline

Name starts with "system".

Return values

  true | if it is a system key
  false | otherwise

bool kdb::Key::isUser | ( |  | ) | const
| inline

Name starts with "user".

Return values

  true | if it is a user key
  false | otherwise

bool kdb::Key::isValid | ( |  | ) | const
| inline

Returns
  if the key is valid

An invalid key has no name. The name of valid keys either start with user or system.

Return values

  true | if the key has a valid name
  false | if the key has an invalid name

See also
  getName(), isUser(), isSystem(), getNamespace()

bool kdb::Key::needSync | ( |  | ) | const
| inline

const Key kdb::Key::nextMeta | ( |  | ) |
| inline

See also
  rewindMeta(), currentMeta()

kdb::Key::operator bool | ( |  | ) | const
| inline

This is for loops and lookups only.

Opposite of isNull()

For loops it checks if there are still more keys. For lookups it checks if a key could be found.

Warning
  you should not construct or use null keys

See also
  isNull(), isValid()

Returns
  false on null keys
  true otherwise

bool kdb::Key::operator!= | ( | const Key & | k | ) | const
| inline

Return values

  true | != 0

ckdb::Key * kdb::Key::operator* | ( |  | ) | const
| inline

Is a abbreviation for getKey.

Passes out the raw key pointer. This pointer can be used to directly change the underlying key object.

Note
  that the ownership remains in the object

See also
  getKey()

void kdb::Key::operator++ | ( | int |  | ) | const
| inline

void kdb::Key::operator++ | ( |  | ) | const
| inline

void kdb::Key::operator-- | ( | int |  | ) | const
| inline

void kdb::Key::operator-- | ( |  | ) | const
| inline

Key * kdb::Key::operator-> | ( |  | ) |
| inline

Returns
  a pointer to this object

Needed for KeySet iterators.

See also
  KeySetIterator

bool kdb::Key::operator< | ( | const Key & | other | ) | const
| inline

Return values

  true | < 0

bool kdb::Key::operator<= | ( | const Key & | other | ) | const
| inline

Return values

  true | <= 0

Key & kdb::Key::operator= | ( | ckdb::Key * | k | ) |
| inline

Assign a C key.

Will call del() on the old key.

Key & kdb::Key::operator= | ( | const Key & | k | ) |
| inline

Assign a key.

Will call del() on the old key.

bool kdb::Key::operator== | ( | const Key & | k | ) | const
| inline

Return values

  true | == 0

bool kdb::Key::operator> | ( | const Key & | other | ) | const
| inline

Return values

  true | > 0

bool kdb::Key::operator>= | ( | const Key & | other | ) | const
| inline

Return values

  true | >= 0

ckdb::Key * kdb::Key::release | ( |  | ) |
| inline

Passes out the raw key pointer and resets internal key handle.

Note
  that the ownership is moved outside.

Return values

  0 | if no key is held (null pointer), no action is done then.

void kdb::Key::rewindMeta | ( |  | ) | const
| inline

See also
  nextMeta(), currentMeta()

template<class T >

void kdb::Key::set | ( | T | x | ) |
| inline

Set a key value.

This method tries to deserialise the string to the given type.

void kdb::Key::setBaseName | ( | const std::string & | baseName | ) |
| inline

Sets a base name for a key.

Exceptions

  KeyInvalidName | if the name is not valid

ssize_t kdb::Key::setBinary | ( | const void * | newBinary,
|  | size_t | dataSize
| ) |  |
| inline

template<class T >

void kdb::Key::setMeta | ( | const std::string & | metaName,
|  | T | x
| ) |  |
| inline

Set metadata for key.

Warning
  unlike the C Interface, it is not possible to remove metadata with this method. k.setMeta("something", NULL) will lead to set the number 0 or to something different (may depend on compiler definition of NULL). See discussion in Issue https://github.com/ElektraInitiative/libelektra/issues/8

Use delMeta() to avoid these issues.

See also
  delMeta(), getMeta(), copyMeta(), copyAllMeta()

void kdb::Key::setName | ( | const std::string & | newName | ) |
| inline

Exceptions

  KeyInvalidName | if the name is not valid

void kdb::Key::setString | ( | std::string | newString | ) |
| inline

The documentation for this class was generated from the following files:

- key.hpp
- kdbvalue.hpp