$darkmode
Elektra 0.11.0
|
Methods to do various operations on Key values. More...
Functions | |
const void * | keyValue (const Key *key) |
Return a pointer to the real internal key value. More... | |
const char * | keyString (const Key *key) |
Get a pointer to the c-string representing the value. More... | |
ssize_t | keyGetValueSize (const Key *key) |
Returns the number of bytes needed to store the key value, including the NULL terminator. More... | |
ssize_t | keyGetString (const Key *key, char *returnedString, size_t maxSize) |
Copy the string value of a Key into returnedString . More... | |
ssize_t | keySetString (Key *key, const char *newStringValue) |
Set the value for key as newStringValue . More... | |
ssize_t | keyGetBinary (const Key *key, void *returnedBinary, size_t maxSize) |
Copy the binary value of a Key into returnedBinary . More... | |
ssize_t | keySetBinary (Key *key, const void *newBinary, size_t dataSize) |
Set the value of a Key to the binary value newBinary . More... | |
Methods to do various operations on Key values.
A key can contain a value in different format. The most likely situation is, that the value is interpreted as text. Use keyGetString() for that. You can save any Unicode Symbols and Elektra will take care that you get the same back, independent of your current environment.
In some situations this idea fails. When you need exactly the same value back without any interpretation of the characters, there is keySetBinary(). If you use that, its very likely that your Configuration is not according to the standard. Also for Numbers, Booleans and Date you should use keyGetString(). To do so, you might use strtod() strtol() and then atol() or atof() to convert back.
To use them:
ssize_t keyGetBinary | ( | const Key * | key, |
void * | returnedBinary, | ||
size_t | maxSize | ||
) |
Copy the binary value of a Key into returnedBinary
.
If the type is not binary -1 will be returned.
When the binary data is empty (this is not the same as ""!) 0 will be returned and returnedBinary
will not be changed.
For string values see keyGetString() and keyIsString().
When returnedBinary
is too small to hold the data (maximum size is given by maxSize), the returnedBinary will not be changed and -1 is returned.
key | the Key object to get the binary value from |
returnedBinary | pre-allocated memory to store a copy of the Key's value |
maxSize | number of bytes of pre-allocated memory in returnedBinary |
returnedBinary
0 | if the binary is empty |
-1 | on NULL pointers |
-1 | if maxSize is 0, too small for the value or larger than SSIZE_MAX |
-1 | if the Key's value is a string |
ssize_t keyGetString | ( | const Key * | key, |
char * | returnedString, | ||
size_t | maxSize | ||
) |
Copy the string value of a Key into returnedString
.
When there is no value inside the string, 1 will be returned and the returnedString will be empty ("") to avoid programming errors where old strings are shown to the user.
key | the Key object to get the string from |
returnedString | pre-allocated memory to store a copy of the Key's value |
maxSize | number of bytes of allocated memory in returnedString |
returnedString
, including final NULL 1 | if the string is empty |
-1 | on any NULL pointers |
-1 | if the Key's value is binary |
-1 | maxSize is 0, too small for the string or larger than SSIZE_MAX |
ssize_t keyGetValueSize | ( | const Key * | key | ) |
Returns the number of bytes needed to store the key value, including the NULL terminator.
It returns the correct size, independent of the Key Type. If the value is binary there might be '\0' values in it.
For an empty string you need one byte to store the ending NULL. For that reason 1 is returned. This is not true for binary data, so 0 will be returned.
A binary key has no '\0' termination. String types are null-terminated, and the terminator will be considered for the length.
This method can be used with elektraMalloc() before keyGetString() or keyGetBinary() is called.
key's
value (including NULL terminators)key | the Key object to get the size of the value from |
1 | when there is no data and type is a string |
0 | when there is no data and type is binary |
-1 | on null pointer |
ssize_t keySetBinary | ( | Key * | key, |
const void * | newBinary, | ||
size_t | dataSize | ||
) |
Set the value of a Key to the binary value newBinary
.
A private copy of newBinary
will be allocated and saved inside key
, so the parameter can be deallocated after the call.
Binary values might be encoded in another way than string values depending on the plugin. Typically character encodings should not take place on binary data. Consider using a string Key instead, if encoding should occur.
When newBinary
is a NULL pointer the value will be freed and 0 will be returned.
Read-only keys will stay unchanged after calling this function.
dataSize
matches the length of newBinary
newBinary
is not NULL and dataSize
> 0 key
is not read-only key's
value set exactly to the data in newBinary
key's
metadatakey | the Key object where the value should be set |
newBinary | a pointer to any binary data or NULL (to clear the stored value) |
dataSize | number of bytes to copy from newBinary |
0 | when the internal binary was freed and is now a null pointer |
-1 | if key is NULL |
-1 | when dataSize is 0 (and newBinary not NULL) or larger than SSIZE_MAX |
-1 | if key is read-only |
ssize_t keySetString | ( | Key * | key, |
const char * | newStringValue | ||
) |
Set the value for key
as newStringValue
.
The function will allocate and save a private copy of newStringValue
, so the parameter can be freed after the call.
String values will be saved in backend storage in UTF-8 universal encoding, regardless of the program's current encoding (if the iconv plugin is available).
newStringValue
is a NULL terminated string newStringValue
meta:/binary
is clearedkey | the Key for which to set the string value |
newStringValue | NULL-terminated string to be set as key's value |
1 | if newStringValue is a NULL pointer, this will make the string empty (string only containing null termination) |
-1 | if key is a NULL pointer |
const char* keyString | ( | const Key * | key | ) |
Get a pointer to the c-string representing the value.
Will return "(null)" on null pointers. Will return "(binary)" on binary data not ended with a null byte.
It is not checked if it is actually a string, only if it terminates for security reasons.
key | the Key object to get the string value from |
"" | if no data found |
(null) | on null Key |
(binary) | on binary Key |
const void* keyValue | ( | const Key * | key | ) |
Return a pointer to the real internal key
value.
This is a much more efficient version of keyGetString() keyGetBinary(). You should use it if you are responsible enough to not mess up things. You are not allowed to modify anything in the returned string. If you need a copy of the Value, consider to use keyGetString() or keyGetBinary() instead.
If key
is string (keyIsString()), you may cast the returned as a "char *"
because you'll get a NULL terminated regular string.
keyValue() returns "" in string mode when there is no value. The reason is
If the data is binary, the size of the value must be determined by keyGetValueSize(), any strlen() operations are not suitable to determine the size.
keyValue() returns 0 in binary mode when there is no value. The reason is
key
is not NULL and has stored data key | the Key from which to get the value |
"" | when there is no value and Key is not binary |
0 | where there is no value and Key is binary |
0 | on NULL pointer |