getElementWhere method
Recursively checks all elements within the node tree and returns the first element found with properties matching those specified.
name
and id
must not be empty if they are provided.
If attributeNames
is not null
, only elements posessing an attribute
with a name contained in attributeNames
will be returned. If
matchAllAttributes
is true
, an element must possess every attribute
contained in attributeNames
to be returned, if false
, the element
only needs to posess a single attribute contained in attributeNames
.
If attributes
isn't null
, only elements possessing attributes
with an identical name and value as those contained in attributes
will be returned. If matchAllAttributes
is true
, an element must
possess every attribute contained in attributes
, if false
,
the element only needs to possess a single attribute contained in
attributes
.
If children
isn't null
, only elements possessing children matching
those in children
will be returned. If matchAllChildren
is true
,
an element must posess every child
found in children
, if false
,
the element only needs to posess a single child found in children
.
If childrenMustBeIdentical
is true
, the element's children must be
in the same order and possess the same number of children as those in
children
, children will also be compared with the ==
operator,
rather than the compareValues method.
start
and stop
refer to the indexes of the identified elements.
Only matches found between start
and stop
will be returned.
start
must not be null
and must be >= 0
. stop
may be null
,
but must be >= start
if provided.
Returns null
if no element can be found.
Implementation
XmlElement? getElementWhere({
String? name,
String? id,
List<String>? attributeNames,
List<XmlAttribute>? attributes,
bool matchAllAttributes = false,
bool attributesMustBeIdentical = false,
List<XmlNode>? children,
bool matchAllChildren = false,
bool childrenMustBeIdentical = false,
}) {
assert(name == null || name.isNotEmpty);
assert(id == null || id.isNotEmpty);
return getElementsWhere(
name: name,
id: id,
attributeNames: attributeNames,
matchAllAttributes: matchAllAttributes,
attributesMustBeIdentical: attributesMustBeIdentical,
children: children,
matchAllChildren: matchAllChildren,
childrenMustBeIdentical: childrenMustBeIdentical,
start: 0,
stop: 0,
)?.first;
}