Trait GroupIDChanger

Source

pub trait GroupIDChanger {
    // Required methods
    unsafe fn change_group_id_unchecked(&mut self, new_group_id: &str);
    fn apply_group_id(&mut self);

    // Provided method
    fn change_group_id(
        &mut self,
        new_group_id: impl GroupID,
    ) -> Result<(), GroupIDError> { ... }
}

Expand description

Used for GroupID modifications on buildertrees.

Implementing this trait allows for the modification of identification string (often name field) of its implementor and his children.

The following operations can be done:

Replacing the GroupID section of the identification string.
Appling the GroupID delimiter transformations

This should be achieved by recursively calling the desired method on the children of the implementor.

§Examples

Impemtation of GroupIDChanger for on an example struct tree:

use robot_description_builder::identifiers::{GroupIDChanger,GroupIDErrorKind};

#[derive(Debug, PartialEq, Eq, Clone)]
struct ChildStruct {
    name: String
}

impl GroupIDChanger for ChildStruct {
    unsafe fn change_group_id_unchecked(&mut self, new_group_id: &str) {
        self.name.change_group_id_unchecked(new_group_id);
    }

    fn apply_group_id(&mut self) {
        self.name.apply_group_id();
    }
}

#[derive(Debug, PartialEq, Eq, Clone)]
struct ParentStruct {
    name: String,
    child: Option<ChildStruct>
}

impl GroupIDChanger for ParentStruct {
    unsafe fn change_group_id_unchecked(&mut self, new_group_id: &str) {
        self.name.change_group_id_unchecked(new_group_id);
        if let Some(child) = self.child.as_mut() {
            child.change_group_id_unchecked(new_group_id);
        }
    }

    fn apply_group_id(&mut self) {
        self.name.apply_group_id();
        if let Some(child) = self.child.as_mut() {
            child.apply_group_id();
        }
    }
}

let example_tree = ParentStruct{
        name: "tree_[[0]]".into(),
        child: Some(ChildStruct{name:"tree_child_[[0]][\\[".into()})
    };

// Appling a GroupID
let mut applied_tree = example_tree.clone();
applied_tree.apply_group_id();
assert_eq!(
    applied_tree,
    ParentStruct{
        name: "tree_0".into(),
        child: Some(ChildStruct{name:"tree_child_0[[".into()})
    }
);

// Changing the GroupID
let mut changed_tree = example_tree.clone();
assert!(changed_tree.change_group_id("1").is_ok());
assert_eq!(
    changed_tree,
    ParentStruct{
        name: "tree_[[1]]".into(),
        child: Some(ChildStruct{name:"tree_child_[[1]][\\[".into()})
    }
);

// Invalid GroupID
let mut failed_tree = example_tree.clone();
assert_eq!(changed_tree.change_group_id("").unwrap_err().kind(), &GroupIDErrorKind::Empty);
// The tree remains unchanged
assert_eq!(failed_tree, example_tree);

Required Methods§

Source

unsafe fn change_group_id_unchecked(&mut self, new_group_id: &str)

Unchecked replacement of the GroupID of the builder tree with new_group_id.

Changes the GroupID of the identification string of the current builder tree without checking if the new_group_id is valid. This should be achieved by calling this method on all its implementors childeren and its identification string often called name.

§Safety

This function should be called with a valid GroupID. It is recommended to use change_group_id instead.

Source

fn apply_group_id(&mut self)

Applies GroupID delimiter replacements.

Replaces the GroupID delimiters in the current builder tree.

TODO: REFERENCE MODULE DOC ABOUT GroupID Delimiters and replacements

TODO: UPGRADE

Replaces:

DELIMITER_OPEN_GROUPID with ""
DELIMITER_CLOSE_GROUPID with ""
DELIMITER_ESCAPED_OPEN_GROUPID with DELIMITER_OPEN_GROUPID
DELIMITER_ESCAPED_CLOSE_GROUPID with DELIMITER_CLOSE_GROUPID

Provided Methods§

Source

fn change_group_id( &mut self, new_group_id: impl GroupID, ) -> Result<(), GroupIDError>

Replaces the GroupID of the builder tree with new_group_id.

If new_group_id is a valid GroupID then the GroupID of the whole buildertree is replaced. Otherwise, this method fails returning an error explaing the invalidation.

For performance reasons the check only get’s performed here, when this succeeds change_group_id_unchecked is used to perform the actual updating.