#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:

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation