{Function} - A query is started searching within the scope of the finder and all of its children. Returns a FindResult that contains only elements that match the given criteria, i.e. that 1) have the given attribute and 2) the attribute value matches the given value. While find can be executed on a Finder to start a query, the and function can be executed on a FindResult to further reduce the number of elements.

Value can be any object and has to match the attribute type, i.e. passing a Number as value together with a String attribute, will never match any element.

// find all element without name and description, if they have one
var needWork = finder.find("name", null).and("description", null);

// may match
var test = finder.find("name", "24");

// correct, but will never match
var test = finder.find("name", 24);

Stability 2 - Unstable

{Function} - Same as find() or and() but retuns all elements that do NOT match the criteria.

// find elements that have no name but at least a description
var okay = finder.find("name", null).butNot("description", null);

Stability 2 - Unstable

{Function} - Similar as find() but accepts a type (here: Metaclass) as the first argument. The second argument is optional and expressed whether the search should be "strict", i.e. whether only direct instances of the given type shall be found or whether sub-classes are allowed too. The default is false.

// find elements of type SysMLElement and sub-classes
var all = finder.findByType(Metamodel.sysml.SysMLElement);

Stability 2 - Unstable

{Function} - Similar as findByType() but accepts a single tag string as the first and only argument. Accepts only elements that actually are tagged with or without the given tag.

// find elements tagged as "Hardware"
var hardware = finder.findByTag("Hardware");

// now filter further with tags
var gen4 = hardware.withTag("Gen4").withoutTag("Deprecated");

Stability 2 - Unstable

{Function} - Filter elements that match a certain criteria. Accepts a predicate (boolean-valued function with a single argument) as first and only argument. That predicate function is called for each element in the current finder result. The element is kept if the function returns true, otherwise it is dropped.

// find elements tagged as "Hardware"
var hardware = finder.findByTag("Hardware");

// now filter further using filter()
var gen4 = hardware.filter(function (e) {
	return e.mediniTags.contains("Gen4") 
		&& !e.mediniTags.contains("Deprecated");
});

Stability 2 - Unstable

{Function} - Similar to find() but has no arguments and simply accepts all elements. This is a convenience function only to bypass any initial filtering.

// find elements by filter only
var all = finder.all();
console.log("This project contains {0} elements overall", all.size());

Stability 2 - Unstable

{Function} - Can be called on any FindResult to either return number of found elements or to check whether anything or nothing was found.

// search all parts ...
var all = finder.findByType(Metamodel.sysml.SySMLPart, true);
console.log("Found {0} parts", all.size());
if (all.notEmpty()) {
  console.log("Found something!");
}

Stability 2 - Unstable

{Function} - Can be called on any FindResult to return the first found element. If there was not anything found, undefined is returned.

// find first element
var first = finder.all().first();
console.log("The first element in this project is {0}", first);

Stability 2 - Unstable

{Attribute} - The scope attribute is a read-only attribute. It holds the object or objects, a finder is searching on, so either a root object or an array of objects, depending on how the finder was created. The default finder has the project root node as its scope. To create a finder on another scope use the Global object.

// search on temporary scope
var beforeScope = finder.scope;
finder = Global.getFinder(...);
...
finder = Global.getFinder(beforeScope);

Stability 2 - Unstable

{Function} - Can be called on any FindResult to return the list of found elements either as an array or as a list (of type java.util.List). The returned result is never undefined but might be empty. Note that toList() and toArray() have the same functionality as asList() resp. asArray(). Both were introduced in 2022 R2 as replacement for the other functions which are deprecated.

// find elements
var first = finder.all().toArray();
console.log("There are {0} elements in this project", first.length);

Stability 2 - Unstable

{Function} - Can be called on any FindResult to return the time that was used to finish the last query or filter execution. The time is given in milliseconds.

// search all parts ...
var all = finder.findByType(Metamodel.sysml.SySMLPart, true);
console.log("Found all parts in {0}ms", all.elapsedTime());

Stability 2 - Unstable