new to Analytica 4.7

= FindObjects( regExp, attribute, excludeAttribute, class, excludeClass, value, influences, influencedBy, inclusive, within, withinAny, contains, containsAny, hasInput, hasOutput, hasParent, hasKid, isLiteral, uses, usedBy, caseSensitive )

Finds Analytica objects matching the criteria specified and returns a set of handles to these objects. The result is a set (a reference to a list), which can be used directly in functions like SetUnion, SetDifference and SetIntersection to combine search criteria in arbitrary ways. To get the result as a list, preface with a de-reference operator (#), i.e.,

#FindObjects( "Cost" )

Because it returns a reference to the list of matching objects, the function is fully array-abstractable, and will return an array of matching sets when an array is passed as a parameter. In this case, it returns the results for an array of distinct searches. You cannot de-reference the result when the result might be an array of searches, so you would not preface with the # operator, unless you know that only a single search has been requested.

A rich set of parameters, all optional, allow many types of criteria to be specified. You can combine criteria by specifying multiple attributes. When multiple types of criteria are present, they are combined conjunctively (i.e., they must all be true).

Parameters

All parameters, with the possible exception of «regExp» and «attribute», must be specified using a named calling convention. All parameters are optional, but at least one parameter should be specified.

regExp

A regular expression (text) to search for. Objects having this pattern in any textual attribute, or in any of the attributes listed in «attribute» are returned.

attribute

One or more attributes to be matched against «regExp» and «value». When omitted, all applicable attributes are searched. No information about which attribute matched is included in the result.

excludeAttribute

One or more attributes to be excluded from the match.

class

One or more object classes. Only objects having one of the specified classes are returned. When not specified, only user objects are returned (not built-in objects like SysFunction or SysVar). If you specify Any, then all object classes, user and built-in, are included.

excludeClass

One of more object classes to exclude.

value

An atomic value to find. Previously computed values are search, or the attributes listed in «attribute». Searches within the individual cells of tables and arrays. You can search for NaN or Null.

influences

A list of handles to, or names of variables. Finds all objects that influence all of the listed variables, i.e., all objects upstream from all the listed variables.

influencedBy

A list of handles to, or names of variables. Finds all objects downstream from all variables listed.

inclusive

Boolean. By default FindObjects(influences:x) does not include x itself. When «inclusive» is true, then x is included. The same goes for «influencedBy», «within», «withinAny», «contains» and «containsAny».

within

When one or more modules is specified, only objects within the indicated modules are searched.

withinAny

Same as «within», except that it also includes objects that are inside the specified module(s) only as a result of a module alias being inside the module.

contains

Searches among modules that contain all of the objects specified in «contains».

containsAny

Same as «contains», except that it also includes modules that contain an alias that contains the indicates object(s).

hasInput

When true, returns objects that have an input node. When false, objects that have no input node.

hasOutput

When true, returns objects that have an output node. When false, objects that have no output node.

hasParent

When true, returns objects that depend on at least one other variable. When false, returns objects that have no dependency parents.

hasKid

When true, returns objects influence at least one other variable. When false, returns objects with no dependents.

isLiteral

When true, returns objects that contain only literals (explicit numbers, text, etc.) or are defined as a table with only literals in the cells.

uses

Find objects that use the items listed in «uses». Specify handles to, or textual names of variables, functions or attributes to «uses».

usedBy

Finds objects that are used by the items listed in «usedBy». You should specify handles to, or textual names of variables, functions or attributes to «uses».

caseSensitive

Controls whether «regExp» is case-sensitive. By default, it is case-insensitive.

Examples

Objects matching specific text

Find all objects having the text "Bacteria" anywhere within any textual attribute (such as Identifier, Units, Title, Description, Definition, User-defined attributes, etc.). The match is case insensitive.

#FindObjects("Bacteria")

Find all objects with an identifier that starts with the prefix "Hydro_". The ^ character is the regular expression code for beginning-of-text, which prevents a match to "Cost_of_hydro_power".

#FindObjects( "^Hydro_",Identifier)

You can equivalently quote the attribute name, or compute it:

Var att := "Identifier" Do #FindObjects("^Hydro_", att )

Find objects that have both the words "plant" and "animal" within its textual attributes. An object matches if each word appears in a different attribute, for example, "plant" in the Title, and "animal" in the Description. Notice that when using a Set Functions to combine criteria, you don't de-reference the result of FindObjects before passing it to the set function.

#SetUnion( [ FindObjects("plant"), FindObjects("animal") ] )

Find objects that have Units of "mph" or "miles per hour", which do not have a divide operator (/) in the Definition.

#SetDifference( FindObjects("(mph)|(miles per hour)", Units), FindObjects("/", Definition) )

Find objects in which "lumina" appears in a textual attribute without being capitalized (it is a proper noun, so should be capitalized). It uses the regular expression control '\b to match word-boundaries, so that words like "illumination" that contain the character sequence inside the word is not matched. The search is case-sensitive so that properly capitalized instances of "Lumina" are not included.

#FindObjects( "\blumina\b", caseSensitive:True )

Find objects having the text "Power" in either the Identifier on Title. This uses named-calling syntax, but the positional syntax (with three parameters) would also work.

#FindObjects( regExp:"Power", attribute:Identifier, Title )

Find objects having the text "Dynamic" in any textual attribute other than the Definition.

#FindObjects( "Dynamic", excludeAttribute:Definition )

The variable Words contains a vector of words, indexed by the index Word_idx. The variable Attr_to_search contains a list of attribute names, computed using Subset. Find objects having any of the indicated words in any of the indicated attributes. Only full words are matched (by use of the regular expression '\b'), but the match is case insensitive. The full list of attributes from Attr_to_search is passed to the «attribute» parameter by using Repeated parameter forwarding (the ...).

#SetUnion( FindObjects( '\b' & Words & '\b', attribute: ...Attr_to_search ), Word_idx )

Building on the previous example, but passing Attr_to_search without Repeated parameter forwarding, we end up with a list of results, one for each attribute, since array-abstraction kicks in on the list of attributes. So for example, if Attr_to_search has the value ["Title", "Description", "Help"], the result is an array of three elements, the first having objects in whose Title attribute contains one of the words, the second cell has objects whose Description contains one of the words, etc. An important point here is that we cannot de-reference the result, because the result is collection of sets. Dereferencing would attempt to combine

SetUnion( FindObjects( Words, attribute: Attr_to_search ), Word_idx )

Objects of a certain type

Any of these three variations can be used to find all User-defined functions.

#FindObjects( class:Function )
#FindObjects( class:"Function" )
#FindObjects( class: Handle(Function) )

Find all non-linked libraries.

#FindObjects( class: "Library" )

Find all libraries, whether linked or non-linked.

#FindObjects( class: Library, LinkLibrary )

Find all modules or libraries. In this example, ModuleTypes is a separate constant node in your model. Notice that Repeated-parameter forwarding is used here to pass the full list of modules as a single call, without array-iterating over them.

Constant ModuleTypes := [ "Module", "LinkModule", "Model", "Library", "LinkLibrary", "Form" ] 
#FindObjects( class: ...ModuleTypes )

You could also allow array-abstraction to iterate, returning the matches to each module type, and then combine the results using SetUnion.

#SetUnion( [[FindObjects(class:ModuleTypes), ModuleTypes )Using with FoundSetSee Also