Struct autosar_data::Element

source · [−]
pub struct Element(_);
Expand description

An arxml element

This is actually a wrapper type which provides all the necessary manipulation functions. The actual element data is held behind Arc<Mutex<>>.

Implementations

Get the parent element of the current element

Returns None if the current element is the root, or if it has been deleted from the element hierarchy

Example
if let Some(parent) = element.parent()? {
    // ...
}
Possible Errors

Get the ElementName of the element

Example
let element = file.root_element();
let element_name = element.element_name();
assert_eq!(element_name, ElementName::Autosar);

Get the ElementType of the element

The ElementType is needed in order to call methods from the autosar-data-specification crate

Example
let element_type = element.element_type();

Get the name of an identifiable element

An identifiable element has a <SHORT-NAME> sub element and can be referenced using an autosar path.

If the element is not identifiable, this function returns None

Example
if let Some(item_name) = element.item_name() {
    // ...
}

Set the item name of this element

This operation will update all references pointing to the element or its sub-elements so that they remain valid.

Example
element.set_item_name("NewName");
Note

In order to rename an element without updating any references, do this instead:

if let Some(short_name) = element.get_sub_element(ElementName::ShortName) {
    short_name.set_character_data(CharacterData::String("the_new_name".to_string()));
}
Possible Errors

Returns true if the element is identifiable

In order to be identifiable, the specification must require a SHORT-NAME sub-element and the SHORT-NAME must actually be present.

Example
if element.is_identifiable() {
    // ...
}

Returns true if the element should contain a referenct to another element

The function does not check if the reference is valid

Example
if element.is_reference() {
    // ex: element.set_reference_target(...)
}

Get the Autosar path of an identifiable element

Example
let path = element.path()?;
Possible Errors

Get a reference to the ArxmlFile containing the current element

Example
let file = element.file()?;
Possible Errors

Get the ContentType of the current element

Example
if element.content_type() == ContentType::CharacterData {
    // ...
}

Create a sub element at a suitable insertion position

The given ElementName must be allowed on a sub element in this element, taking into account any sub elements that may already exist. It is not possible to create named sub elements with this function; use create_named_sub_element() for that instead.

Example
let element = file.root_element().create_sub_element(ElementName::ArPackages)?;
Possible Errors

Create a sub element at the specified insertion position

The given ElementName must be allowed on a sub element in this element, taking into account any sub elements that may already exist. It is not possible to create named sub elements with this function; use create_named_sub_element_at() for that instead.

The specified insertion position will be compared to the range of valid insertion positions; if it falls outside that range then the function fails.

Example
let element = file.root_element().create_sub_element_at(ElementName::ArPackages, 0)?;
Possible Errors

Create a named/identifiable sub element at a suitable insertion position

The given ElementName must be allowed on a sub element in this element, taking into account any sub elements that may already exist.

This method can only be used to create identifiable sub elements.

Example
let pkgs_element = file.root_element().create_sub_element(ElementName::ArPackages)?;
let element = pkgs_element.create_named_sub_element(ElementName::ArPackage, "Package")?;
Possible Errors

Create a named/identifiable sub element at the specified insertion position

The given ElementName must be allowed on a sub element in this element, taking into account any sub elements that may already exist. The specified insertion position will be compared to the range of valid insertion positions; if it falls outside that range then the function fails.

This method can only be used to create identifiable sub elements.

Example
let pkgs_element = file.root_element().create_sub_element(ElementName::ArPackages)?;
let element = pkgs_element.create_named_sub_element_at(ElementName::ArPackage, "Package", 0)?;
Possible Errors

Create a deep copy of the given element and insert it as a sub-element

The other element must be a permissible sub-element in this element and not conflict with any existing sub element. The other element can originate from any loaded AutosarProject, it does not have to originate from the same project or file as the current element.

The AutosarVersion of the other element might differ from the version of the current file; in this case a partial copy will be performed that omits all incompatible elements.

If the copied element is identifiable, then the item name might be extended with a numerical suffix, if one is required in order to make the name unique. For example: An identifiable element “Foo” already exists at the same path; the copied identifiable element will be renamed to “Foo_1”.

If the copied element or the hierarchy of elements under it contain any references, then these will need to be adjusted manually after copying.

Example
let other_element = project.get_element_by_path("/Package/Path").unwrap();
let element = base.create_copied_sub_element(&other_element)?;
Possible Errors

Create a deep copy of the given element and insert it as a sub-element at the given position

The other element must be a permissible sub-element in this element and not conflict with any existing sub element. The other element can originate from any loaded AutosarProject, it does not have to originate from the same project or file as the current element.

The AutosarVersion of the other element might differ from the version of the current file; in this case a partial copy will be performed that omits all incompatible elements.

If the copied element is identifiable, then the item name might be extended with a numerical suffix, if one is required in order to make the name unique. For example: An identifiable element “Foo” already exists at the same path; the copied identifiable element will be renamed to “Foo_1”.

If the copied element or the hierarchy of elements under it contain any references, then these will need to be adjusted manually after copying.

Example
let other_element = project.get_element_by_path("/Package/Path").unwrap();
let element = base.create_copied_sub_element_at(&other_element, 0)?;
Possible Errors

Take an element from it’s current location and place it in this element as a sub element

The moved element can be taken from anywhere - even from a different arxml document that is not part of the same AutosarProject

Restrictions:

  1. The element must have a compatible element type. If it could not have been created here, then it can’t be moved either.
  2. The origin document of the element must have exactly the same AutosarVersion as the destination.
Example
let other_element = project.get_element_by_path("/Package/Path").unwrap();
let element = base.move_element_here(&other_element)?;
Possible Errors

Take an element from it’s current location and place it at the given position in this element as a sub element

The moved element can be taken from anywhere - even from a different arxml document that is not part of the same AutosarProject

Restrictions:

  1. The element must have a compatible element type. If it could not have been created here, then it can’t be moved either.
  2. The origin document of the element must have exactly the same AutosarVersion as the destination.
Example
let other_element = project.get_element_by_path("/Package/Path").unwrap();
let element = base.move_element_here_at(&other_element, 0)?;
Possible Errors

Remove the sub element sub_element

The sub_element will be unlinked from the hierarchy of elements. All of the sub-sub-elements nested under the removed element will also be recusively removed.

Since all elements are reference counted, they might not be deallocated immediately, however they do become invalid and unusable immediately.

Example
let packages = file.root_element().create_sub_element(ElementName::ArPackages)?;
file.root_element().remove_sub_element(packages)?;
Possible Errors

Set the reference target for the element to target

When the reference is updated, the DEST attribute is also updated to match the referenced element. The current element must be a reference element, otherwise the function fails.

Example
let cluster_element = elements.create_named_sub_element(ElementName::CanCluster, "Cluster")?;
ref_element.set_reference_target(&cluster_element)?;
Possible Errors

Get the referenced element

This function will get the reference string from the character data of the element as well as the destination type from the DEST attribute. Then a lookup of the Autosar path is performed, and if an element is found at that path, then the type of the element is compared to the expected type.

The element is returned if it exists and its type is correct.

Example
let cluster_element = elements.create_named_sub_element(ElementName::CanCluster, "Cluster")?;
ref_element.set_reference_target(&cluster_element)?;
let ref_target = ref_element.get_reference_target()?;
assert_eq!(cluster_element, ref_target);
Possible Errors

set the character data of this element

This method only applies to elements which contain character data, i.e. element.content_type == CharacterData

Example
element.set_character_data(CharacterData::String("value".to_string()))?;
Possible Errors
source

pub fn insert_character_content_item(
    &self,
    chardata: &str,
    position: usize
) -> Result<(), AutosarDataError>

Insert a character data item into the content of this element

This method only applies to elements which contain mixed data, i.e. element.content_type() == Mixed. Use create_sub_element_at to add an element instead of a character data item

Example
// mixed content elements are primarily used for documentation and description
let desc = element.create_sub_element(ElementName::Desc)?;
let l2 = desc.create_sub_element(ElementName::L2)?;
l2.insert_character_content_item("descriptive text", 0)?;
Possible Errors
source

pub fn remove_character_content_item(
    &self,
    position: usize
) -> Result<(), AutosarDataError>

Remove a character data item from the content of this element

This method only applies to elements which contain mixed data, i.e. element.content_type == Mixed

Example
element.insert_character_content_item("descriptive text", 0)?;
element.remove_character_content_item(0)?;
Possible Errors

Get the character content of the element

This method only applies to elements which contain character data, i.e. element.content_type() == CharacterData

Example
match element.character_data() {
    Some(CharacterData::String(stringval)) => {},
    Some(CharacterData::Enum(enumval)) => {},
    Some(CharacterData::UnsignedInteger(intval)) => {},
    Some(CharacterData::Double(dblval)) => {},
    None => {},
}

Create an iterator over all of the content of this element

The iterator can return both sub elements and character data, wrapped as ElementContent::Element and ElementContent::CharacterData

This method is intended to be used with elements that contain mixed content.

Example
for content_item in element.content() {
    match content_item {
        ElementContent::CharacterData(data) => {},
        ElementContent::Element(element) => {},
    }
}

Create a weak reference to this element

A weak reference can be stored without preventing the element from being deallocated. The weak reference has to be upgraded in order to be used, which can fail if the element no longer exists.

See the documentation for Arc

Example
let weak_element = element.downgrade();

Create an iterator over all sub elements of this element

Example
for sub_element in element.sub_elements() {
    // ...
}

Get the sub element with the given element name

Returns None if no such element exists. if there are multiple sub elements with the requested name, then only the first is returned

Example
let element = pkg.get_sub_element(ElementName::ShortName).unwrap();
assert_eq!(element.element_name(), ElementName::ShortName);

Create a depth first iterator over this element and all of its sub elements

Each step in the iteration returns the depth and an element. Due to the nature of a depth first search, the returned depth can remain the same, increase by one, or decrease by an arbitrary number in each step.

The dfs iterator will always return this element as the first item.

Example
for (depth, elem) in element.elements_dfs() {
    // ...
}

Create an iterator over all the attributes in this element

Example
for attribute in element.attributes() {
    println!("{} = {}", attribute.attrname, attribute.content);
}

Get the value of an attribute by name

Example
let value = file.root_element().attribute_value(AttributeName::xsiSchemalocation);

Get the content of an attribute as a string

Example
let value = element.attribute_string(AttributeName::Dest);

Set the value of a named attribute

If no attribute by that name exists, and the attribute is a valid attribute of the element, then the attribute will be created.

Returns true if the attribute was set.

let result = element.set_attribute(AttributeName::Dest, CharacterData::UnsignedInteger(42));
assert_eq!(result, false);

Set the value of a named attribute from a string

The function tries to convert the string to the correct data type for the attribute

Returns true if the attribute was set.

let result = element.set_attribute_string(AttributeName::T, "2022-01-31T13:59:59Z");
assert_eq!(result, true);

Remove an attribute from the element

Returns true if the attribute existed and could be removed.

Example
let result = file.root_element().remove_attribute(AttributeName::xsiSchemalocation);
// xsiSchemalocation exists in the AUTOSAR element, but it is mandatory and cannot be removed
assert_eq!(result, false);

Serialize the element and all of its content to a string

The serialized text generated for elements below the root element cannot be loaded, but it may be useful for display.

Example
let text = element.serialize();

List all sub_elements that are valid in the current element

The target use case is direct interaction with a user, e.g. through a selection dialog

Return Value

A list of tuples consisting of ElementName of the potential sub element bool: is the sub element named bool: can this sub element be inserted considering the current content of the element

Example
for (element_name, is_named, is_allowed) in element.list_valid_sub_elements() {
    // ...
}

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.