Trait toml_query::insert::TomlValueInsertExt

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

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

Required Methods

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

Provided Methods

Extension function for inserting a value from the current toml::Value document

See documentation of TomlValueinsertExt::insert_with_seperator

Implementations on Foreign Types

Implementors