Trait elektra::writable::WriteableKey

pub trait WriteableKey: ReadableKey {
    type SetValue;
    fn as_ptr(&mut self) -> *mut Key;
    fn set_value(&mut self, value: Self::SetValue)
    where
        Self: Sized;

    fn new(name: &str) -> Result<Self, KeyNameInvalidError>
    where
        Self: Sized,
    { ... }
    fn new_empty() -> Self
    where
        Self: Sized,
    { ... }
    unsafe fn inc_ref(&mut self) -> isize { ... }
    unsafe fn dec_ref(&mut self) -> isize { ... }
    fn clear(&mut self) { ... }
    fn set_name(&mut self, name: &str) -> Result<u32, KeyNameInvalidError> { ... }
    fn set_basename(
        &mut self, 
        basename: &str
    ) -> Result<(), KeyNameReadOnlyError> { ... }
    fn add_basename(
        &mut self, 
        basename: &str
    ) -> Result<(), KeyNameReadOnlyError> { ... }
    fn add_name(&mut self, name: &str) -> Result<(), KeyNameInvalidError> { ... }
    fn copy_all_meta(&mut self, source: &Self)
    where
        Self: Sized,
    { ... }
    fn copy_meta(&mut self, source: &Self, metaname: &str) -> i32
    where
        Self: Sized,
    { ... }
    fn set_meta(
        &mut self, 
        metaname: &str, 
        metavalue: &str
    ) -> Result<usize, KeyNameInvalidError> { ... }
    fn delete_meta(
        &mut self, 
        metaname: &str
    ) -> Result<usize, KeyNameInvalidError> { ... }
    fn rewind_meta(&mut self) { ... }
}

Associated Types

type SetValue

The value that is passed to set_value.

Loading content...

Required methods

fn as_ptr(&mut self) -> *mut Key

Returns the raw pointer of the key. Should be used with caution. In particular, the pointer should only be modified with elektra_sys::key* functions, but keyDel should not be called.

You can use it to call functions in the raw bindings that modify the key, if the safe API doesn't fulfill your usecase.

Examples

let mut key = StringKey::new("user/test/key")?;
let cstr = CString::new("newbasename").unwrap();
let ret_val = unsafe { elektra_sys::keySetBaseName(key.as_ptr(), cstr.as_ptr()) };
assert_eq!(key.name(), "user/test/newbasename");

fn set_value(&mut self, value: Self::SetValue) where
    Self: Sized, 

Set the value of the key.

Examples

let mut key = StringKey::new_empty();
key.set_value("rust");
assert_eq!(key.value(), "rust");

Loading content...

Provided methods

fn new(name: &str) -> Result<Self, KeyNameInvalidError> where
    Self: Sized, 

Construct a new key with a name.

Panics

Panics if an allocation error (out of memory) occurs in the C-constructor.

fn new_empty() -> Self where
    Self: Sized, 

Construct a new nameless key.

Panics

Panics if an allocation error (out of memory) occurs in the C-constructor.

unsafe fn inc_ref(&mut self) -> isize

Increment the viability of a key object. Returns the value of the new reference counter.

Notes

This function is unsafe, since forgetting to call dec_ref after a call to inc_ref results in a memory leak. It is preferable to use duplicate instead.

Examples

let mut key2;
{
    let mut key = StringKey::new("user/test/language")?;
    unsafe { key.inc_ref(); }
    key2 = unsafe { StringKey::from_ptr(key.as_ptr()) };
} // <- key is dropped here, but key2 can still be used
assert_eq!(key2.name(), "user/test/language");
// Forgetting to call this method would leak memory.
unsafe { key2.dec_ref(); }

unsafe fn dec_ref(&mut self) -> isize

Decrement the viability of a key object. Returns the value of the new reference counter.

fn clear(&mut self)

Clears the key. After this call you will receive a fresh key.

fn set_name(&mut self, name: &str) -> Result<u32, KeyNameInvalidError>

Set the name of a key. Must adhere to the rules for keynames otherwise a KeyNameInvalidError is returned. Note that the error could also represent a KeyNameReadOnlyError, but the C-API doesn't allow for the distinction, so only one error can be returned. Returns the size in bytes of this new key name including the ending NUL.

Examples

let mut key = StringKey::new_empty();
key.set_name("user/test/rust")?;
assert_eq!(key.name(), "user/test/rust");

Panics

Panics if the provided string contains interior nul bytes.

fn set_basename(&mut self, basename: &str) -> Result<(), KeyNameReadOnlyError>

Set the basename of the key Returns a KeyNameReadOnlyError if the key is part of a keyset.

Examples

let mut key = StringKey::new("user/test/key")?;
key.set_basename("rust")?;
assert_eq!(key.name(), "user/test/rust");

Panics

Panics if the provided string contains interior nul bytes.

fn add_basename(&mut self, basename: &str) -> Result<(), KeyNameReadOnlyError>

Add a basename to the key Returns a KeyNameReadOnlyError if the key is part of a keyset.

Examples

let mut key = StringKey::new("user/test/key")?;
key.add_basename("rust")?;
assert_eq!(key.name(), "user/test/key/rust");

Panics

Panics if the provided string contains interior nul bytes.

fn add_name(&mut self, name: &str) -> Result<(), KeyNameInvalidError>

Add an already escaped name to the keyname. Returns an KeyNameInvalidError if the name is not a valid escaped name.

Examples

let mut key = StringKey::new("user/x/r").unwrap();
key.add_name("../y/a//././z").unwrap();
assert_eq!(key.name(), "user/x/y/a/z");

Panics

Panics if the provided string contains interior nul bytes.

fn copy_all_meta(&mut self, source: &Self) where
    Self: Sized, 

Copies all metadata from source to the self.

Examples

let mut key = StringKey::new("user/test/mykey")?;
let mut key2 = StringKey::new("user/test/mykey")?;
key.set_meta("rusty", "metal");
key2.copy_all_meta(&key);
assert_eq!(key.meta("rusty")?.value(), "metal");

fn copy_meta(&mut self, source: &Self, metaname: &str) -> i32 where
    Self: Sized, 

Copy metakey with name metaname from source to self.

Examples

use elektra::{StringKey,WriteableKey,ReadableKey};
let mut key = StringKey::new_empty();
key.set_meta("meta", "value");
let mut key2 = StringKey::new_empty();
key2.copy_meta(&key, "meta");
assert_eq!(key2.meta("meta").unwrap().value(), "value");

Panics

Panics if the provided string contains interior nul bytes.

fn set_meta(
    &mut self,
    metaname: &str,
    metavalue: &str
) -> Result<usize, KeyNameInvalidError>

Set a new meta-information. Returns the size of the new meta information on success, or a KeyNameInvalidError if the name is invalid.

Panics

Panics if any of the provided strings contains interior nul bytes.

fn delete_meta(&mut self, metaname: &str) -> Result<usize, KeyNameInvalidError>

Delete the metadata at metaname Returns the size of the new meta information on success, or a KeyNameInvalidError if the name is invalid or out of memory.

Panics

Panics if the provided string contains interior nul bytes.

fn rewind_meta(&mut self)

Rewind the internal iterator to first metadata. Note that iterators already call this method when they're created.

Loading content...

Implementors

impl<'a> WriteableKey for BinaryKey<'a>

type SetValue = &'a [u8]

fn as_ptr(&mut self) -> *mut Key

fn set_value(&mut self, value: Self::SetValue)

impl<'a> WriteableKey for StringKey<'a>

type SetValue = &'a str

fn as_ptr(&mut self) -> *mut Key

fn set_value(&mut self, value: Self::SetValue)

Loading content...