Elektra  0.8.14
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
 
Keyoperator= (ckdb::Key *k)
 Assign a C key. More...
 
Keyoperator= (const Key &k)
 Assign a key. More...
 
void copy (const Key &other)
 
void clear ()
 Clears/Invalidates a key. More...
 
Keyoperator-> ()
 
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 >
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 >
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
kthe 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
kthe 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
kthe key to work with
kdb::Key::Key ( const char *  keyName,
  ... 
)
inlineexplicit

Exceptions
bad_allocif key could not be constructed (allocation problems)
Parameters
keyNamethe name of the new key
kdb::Key::Key ( const std::string  keyName,
  ... 
)
inlineexplicit

Exceptions
bad_allocif 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
keyNamethe name of the new key
kdb::Key::Key ( const char *  keyName,
va_list  ap 
)
inlineexplicit

Exceptions
bad_allocif key could not be constructed (allocation problems)
Parameters
keyNamethe name of the new key
apthe 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
KeyInvalidNameif 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
void kdb::Key::copyMeta ( const Key other,
const std::string &  metaName 
)
inline
const Key kdb::Key::currentMeta ( ) const
inline

Note
that the key will be null if last meta data is found.
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
KeyExceptionon null key or not a valid size
KeyTypeMismatchif 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
KeyExceptionon invalid binary size
KeyTypeMismatchif 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
KeyExceptionif 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
KeyTypeMismatchif 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
KeyTypeConversionif 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:

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

Exceptions
KeyExceptionif 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
KeyExceptionon null key or not a valid size
KeyTypeMismatchif 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
trueif there is a metadata with given name
falseif no such metadata exists
See also
getMeta()
bool kdb::Key::isBelow ( const Key k) const
inline

Parameters
kthe other key
Returns
true if our key is below k
bool kdb::Key::isBelowOrSame ( const Key k) const
inline

Parameters
kthe 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
kthe 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
trueif it is a system key
falseotherwise
bool kdb::Key::isUser ( ) const
inline

Name starts with "user".

Return values
trueif it is a user key
falseotherwise
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
trueif the key has a valid name
falseif the key has an invalid name
See also
getName(), isUser(), isSystem(), getNamespace()
bool kdb::Key::needSync ( ) const
inline

const Key kdb::Key::nextMeta ( )
inline
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
0if no key is held (null pointer), no action is done then.
void kdb::Key::rewindMeta ( ) const
inline
template<class T >
void kdb::Key::set ( 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
KeyInvalidNameif 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,
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
KeyInvalidNameif the name is not valid
void kdb::Key::setString ( std::string  newString)
inline


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