getNthElementWhere method

XmlElement? getNthElementWhere(int index, {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})

Recursively checks all elements within the node tree and returns the nth element found with properties matching those specified.

index must not be null and must be >= 0.

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? getNthElementWhere(
  int index, {
  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,
    attributes: attributes,
    matchAllAttributes: matchAllAttributes,
    attributesMustBeIdentical: attributesMustBeIdentical,
    children: children,
    matchAllChildren: matchAllChildren,
    childrenMustBeIdentical: childrenMustBeIdentical,
    start: index,
    stop: index,
  )?.first;
}