findNodesByExample method

Iterator<Node> findNodesByExample([ Iterable? examples ])

Search for Nodes or Groups by matching the Node data with example data holding values, RegExps, or predicates.

For example, calling this method with an argument object: { sex: "M", name: /^Alex/i, age: n => n >= 18 } will return an iterator of Nodes whose Node.data is a JavaScript object whose:

• sex is "M" (a case-sensitive string comparison), and
• name starts with the string "Alex" (using a case-insensitive match), and
• age is greater than or equal to 18

Here is how an example value can match the corresponding data value:

• A string, number, or boolean is compared with the === operator.

• A function is treated as a predicate and applied to the data value.

• A regular expression (RexExp) is matched against the toString() of the data value. Common expressions include:

  • /abc/ matches any string that includes exactly the substring "abc"
  • /abc/i matches any string that includes the substring "abc", but uses a case-insensitive comparison
  • /^no/i matches any string that starts with "no", ignoring case
  • /ism$ matches any string that ends with "ism" exactly
  • /(green|red) apple/ matches any string that includes either "green apple" or "red apple"

  For more details read Regular Expressions (mozilla.org).

• An Array requires the data value to also be an Array of equal or greater length. Each example array item that is not undefined is matched with the corresponding data array item.

• An Object is recursively matched with the data value, which must also be an Object.

All properties given by the argument example data must be present on the node data, unless the example property value is undefined. All other data properties are ignored when matching.

When multiple argument objects are given, if any of the objects match the node's data, the node is included in the results. @param {...Object} examples one or more JavaScript Objects whose properties are either predicates to be applied or RegExps to be tested or values to be compared to the corresponding data property value @return {Iterator.

Implementation

_i3.Iterator<_i3.Node> findNodesByExample(
        [_i2.Iterable<_i2.dynamic>? examples]) =>
    _i4.callMethod(
      this,
      'findNodesByExample',
      [...?examples],
    );