find

Return specified objects

Syntax

objArray = thisObject.find(Specifier,Value, ...)

Description

Using combinations of specifier-value argument pairs, the find method returns objects in this object that match the specified criteria. The specifier-value pairs can be property based or based on other attributes of the object such as its depth of containment. Specifiers can also be logical operators (-and, -or, and so on) that combine other specifier-value pairs.

By default, the find command finds objects at all depths of containment within an object. You can specify the maximum depth of search by using the -depth specifier. However, the zeroth level of containment, that is, the searched object itself, is always included if it satisfies the search criteria.

If no arguments are specified, the find command returns all objects of this object at all levels of containment.

Arguments

thisObject

The object for which to find contained objects. Can be an object of type Root, Machine, State, Box, Function, or Truth Table.

'-and'

No value is paired to this specifier. Instead, this specifier relates a previous specifier-value pair to a following specifier-value pair in an AND relation.

Note

If no logical operator is specified, -and is assumed.

'-class'

Name of the class to search for. Use this option to find all objects whose class exactly matches a given class. To allow matches for subclasses of a given class, use the -isa specifier. Classes are specified as the name (e.g., 'Stateflow.State', 'Stateflow.Transition', etc.) or as a handle to the class. For more information, see classhandle.

'-depth'

Integer depth to search, which can be 0, 1, 2,..., infinite. The default search depth is infinite.

'-function'

Handle to a function that evaluates each object visited in the search. The function must always return a logical scalar value that indicates whether or not the value is a match. If no property is specified, the function is passed the handle of the current object in the search. If a property is specified, the function is passed the value of that property.

In the following example, a function with handle f (defined in first line) is used to return only those objects of type 'andState':

f = @(h) (strcmp(get(h,'type'), 'andState'));
objArray = thisObject.find('-function', f);

'-isa'

Name of the type of objects to search for. Object types are specified as a name (e.g., 'Stateflow.State', 'Stateflow.Transition', etc.) or as a handle to the object type. For more information, see classhandle.

'-method'

Name of a method belonging to the objects to search for.

'-not'

No value is paired to this specifier. Instead, this specifier searches for the negative of the following specifier-value pair.

'-or'

No value is paired to this specifier. Instead, this specifier relates the previous specifier-value pair to the following specifier-value pair in an OR relation.

'property'

The specifier takes on the name of the property. Value of the specified property for the objects you want to find.

'-property'

Name of the property that belongs to the objects you want to find.

'-xor'

No value is paired to this specifier. Instead, this specifier relates the previous specifier-value pair to the following specifier-value pair in an XOR relation.

'-regexp'

No value follows this specifier. Instead, this specifier indicates that the value of the following specifier-value pair contains a regular expression. For more information, see regexp.

Returns

objArray

Array of objects found matching the criteria specified.

Examples

If a Chart object c represents a Stateflow® chart, to produce an array of all the states in the chart, use this command :

states = c.find('-isa','Stateflow.State')
To produce an array of all objects whose Name property is 'A', use this command:
objects = c.find('Name','A')
To produce an array of all states whose Name property starts with the letter A, use this command:
states = c.find('-isa','Stateflow.State','-and','-regexp','Name','^A')

Introduced before R2006a