Function renvy::merge

source · [−]

pub fn merge(
    settings: Settings, 
    defaults: Settings, 
    clean: Option<bool>
) -> Settings

Expand description

Merges two instances of Settings together so that the following rules are satisfied:

all key-value pairs on defaults that are missing on settings will be added
existing key-value pairs of settings retain their value
if the parameter clean receives Some(true), then any key-value pair on settings which is missing from defaults will be removed

Examples

Default behaviour when clean is None. This is the same behaviour like passing Some(false) explicitly.

// "ssl" exists in both objects, it's "true" here
let settings = renvy::Settings::from([
    ("url".into(), Some(String::from("https://example.com"))),
    ("ssl".into(), Some(String::from("true")))
]);

// "ssl" is "false" here
let defaults = renvy::Settings::from([
    ("port".into(), None),
    ("ssl".into(), Some(String::from("false")))
]);

let merged = renvy::merge(settings, defaults, None);

// "ssl" remains "true", "port" is added, and "url" is left intact
assert_eq!(merged.get("url".into()).unwrap(), &Some(String::from("https://example.com")));
assert_eq!(merged.get("ssl".into()).unwrap(), &Some(String::from("true")));
assert_eq!(merged.get("port".into()).unwrap(), &None);

Behaviour when clean is disabled with Some(false): Extra keys in settings remain untouched. This is the default behaviour that is also applied when clean is empty (None).

// "ssl" exists in both objects, it's "true" here
let settings = renvy::Settings::from([
    ("url".into(), Some(String::from("https://example.com"))),
    ("ssl".into(), Some(String::from("true")))
]);

// "ssl" is "false" here
let defaults = renvy::Settings::from([
    ("port".into(), None),
    ("ssl".into(), Some(String::from("false")))
]);

let merged = renvy::merge(settings, defaults, Some(false));

// "ssl" remains "true", "port" is added, and "url" is left intact
assert_eq!(merged.get("url".into()).unwrap(), &Some(String::from("https://example.com")));
assert_eq!(merged.get("ssl".into()).unwrap(), &Some(String::from("true")));
assert_eq!(merged.get("port".into()).unwrap(), &None);

Behaviour when clean is enabled with Some(true): Extra keys in settings are being removed so that only keys that exist in defaults remain in settings.

// "ssl" exists in both objects, it's "true" here
// "url" exists only in "settings".
let settings = renvy::Settings::from([
    ("url".into(), Some(String::from("https://example.com"))),
    ("ssl".into(), Some(String::from("true")))
]);

// "ssl" is "false" here
let defaults = renvy::Settings::from([
    ("port".into(), None),
    ("ssl".into(), Some(String::from("false")))
]);

let merged = renvy::merge(settings, defaults, Some(true));

// "ssl" remains "true", "port" is added, and "url" is removed
assert_eq!(merged.get("url".into()), None);
assert_eq!(merged.get("ssl".into()).unwrap(), &Some(String::from("true")));
assert_eq!(merged.get("port".into()).unwrap(), &None);