Trait TomlValueInsertExt

Help

pub trait TomlValueInsertExt {
    // Required method
    fn insert_with_seperator(
        &mut self,
        query: &str,
        sep: char,
        value: Value,
    ) -> Result<Option<Value>>;

    // Provided method
    fn insert(&mut self, query: &str, value: Value) -> Result<Option<Value>> { ... }
}

Required Methods§

Source

fn insert_with_seperator( &mut self, query: &str, sep: char, value: Value, ) -> Result<Option<Value>>

Extension function for inserting a value in the current toml::Value document using a custom seperator.

For difference to TomlSetExt::set() and friends, read [#semantics].

§Semantics

The function automatically creates intermediate data structures based on the query string. That means, if the query string is "a.b.c.[0]", but only a table "a" exists in the document, the function automatically creates a table "b" inside "a" and "c" inside "b", and an array in "c". The array index is ignored if the array is created.

If an Array exists, but the specified index is larger than the last index, the array will be expanded by one element: If the array has a length of 3, but the query string specifies that the element should be put at 1000, the function ignores the large index and simply appends the value to the index.

If a Value is inserted into an Array, the array indexes are shifted. Semantically this is the same as doing a array.insert(4, _) (see the standard library).

§Known Bugs

The current implementation does not create intermediate Arrays as described above. This is a known bug. So queries like “foo.bar.[0].baz” (or any query which has an array element) will fail with an error rather than work.

§Return value

If the insert operation worked correctly, Ok(None) is returned. If the insert operation replaced an existing value Ok(Some(old_value)) is returned On failure, Err(e) is returned

§Examples

The following example shows a working insert_with_seperator() call on an empty toml document. The Value is inserted as "foo.bar = 1" in the document.

extern crate toml;
extern crate toml_query;

let mut toml : toml::Value = toml::from_str("").unwrap();
let query = "foo.bar";
let sep = '.';
let val = toml::Value::Integer(1);

let res = toml_query::insert::TomlValueInsertExt::insert_with_seperator(&mut toml, query, sep, val);
assert!(res.is_ok());
let res = res.unwrap();
assert!(res.is_none());

The following example shows a failing insert_with_seperator() call on an empty toml document. The Query does contain an array token, which does not yet work.

extern crate toml;
extern crate toml_query;

let mut toml : toml::Value = toml::from_str("").unwrap();
let query = "foo.[0]";
let sep = '.';
let val = toml::Value::Integer(1);

let res = toml_query::insert::TomlValueInsertExt::insert_with_seperator(&mut toml, query, sep, val);
assert!(res.is_ok()); // panics