find

Identify specified objects in hierarchy

Syntax

objArray = find(location,propertyName,propertyValue)

objArray = find(location,"-regexp",propertyName,propertyValue)

objArray = find(location,"-isa",objectType)

objArray = find(location,"-depth",depth)

objArray = find(location,"-property",propertyName)

objArray = find(location,"-method",functionName)

objArray = find(location,"-function",function)

objArray = find(location,"-not",___)

objArray = find(location,___,logicalOp,___)

Description

objArray = find(location,propertyName,propertyValue) returns an array of Stateflow^® API objects in the hierarchy of location that have a property called propertyName with a value of propertyValue.

objArray = find(location,"-regexp",propertyName,propertyValue) returns the objects that have a property called propertyName with a value that matches the regular expression specified by propertyValue. For more information, see Regular Expressions.

objArray = find(location,"-isa",objectType) returns the objects in the hierarchy of location that have the type specified by objectType.

objArray = find(location,"-depth",depth) returns the objects at or above the specified depth in the hierarchy of location.

objArray = find(location,"-property",propertyName) returns the objects that have a property with the specified name.

objArray = find(location,"-method",functionName) returns the objects that have an object function with the specified name.

objArray = find(location,"-function",function) returns the objects for which the specified function returns true.

objArray = find(location,"-not",___) returns the objects that do not match the specified search criterion. You can specify search criteria by using one of the previous syntaxes except "-depth" and "-regexp".

objArray = find(location,___,logicalOp,___) combines search criteria specified by using the previous syntaxes. Use one of these logical operations:

• "-and" — Results must match both search criteria.

• "-or" — Results must match at least one of the criteria.

• "-xor" — Results must match exactly one of the criteria.

When using multiple logical operations, -and has the highest precedence, while -or and -xor are right-associative. If no logical operation is specified, -and is assumed.

Examples

Find Objects Named A

Find the objects in the chart ch whose Name property is A.

namedIsA = find(ch,"Name","A")

You can specify property names and values as PropertyName=PropertyValue, where PropertyName is not enclosed in quotes (since R2021a). This syntax must appear after other arguments that use quotes.

namedIsA = find(ch,Name="A")

Find Objects with Names That Start with Letter A

Find the objects in the chart ch whose Name property starts with the letter A.

nameStartsWithA = find(ch,"-regexp","Name,","^A")

You can specify property names and values as PropertyName=PropertyValue, where PropertyName is not enclosed in quotes (since R2021a). This syntax must appear after other arguments that use quotes.

nameStartsWithA = find(ch,"-regexp",Name="^A")

Find States in Chart

Find the states in the chart ch.

states = find(ch,"-isa","Stateflow.State")

Find States with Names That Start with Letter A

Find the states in the chart ch whose Name property starts with the letter A.

stateNameStartsWithA = find(ch,"-isa","Stateflow.State", ...
    "-and","-regexp","Name","^A")

You can specify property names and values as PropertyName=PropertyValue, where PropertyName is not enclosed in quotes (since R2021a). This syntax must appear after other arguments that use quotes.

stateNameStartsWithA = find(ch,"-isa","Stateflow.State", ...
    "-and","-regexp",Name="^A")

Find Objects in Top Two Levels of Chart

Find the objects in the top two levels of the hierarchy of the chart ch.

depthTwoObjects = find(ch,"-depth",2)

Find Symbols in Chart

Find the symbols in the chart ch. Symbols include Stateflow.Data, Stateflow.Event, Stateflow.Message, and other non-chart objects that have a Name property.

symbols = find(ch,"-property","Name", ...
    "-not","-isa","Stateflow.Chart")

Find Graphical Objects in Chart

Find the graphical objects in the chart ch. Graphical objects are non-chart objects that have an object function called fitToView.

graphicalObjects = find(ch,"-method","fitToView", ...
    "-not","-isa","Stateflow.Chart")

Find Objects for Which Signal Logging Is Enabled

Find the objects in the chart ch for which signal logging is enabled. Signal logging is enabled when the subproperty LoggingInfo.DataLogging is true.

f = @(h) h.LoggingInfo.DataLogging;
signalLoggingOn = find(ch,"-function",f);

Input Arguments

location — Location to search

Simulink.Root object | Stateflow.Chart object | Stateflow.State object | ...

Location to search, specified as a Simulink.Root object, a Simulink.BlockDiagram object, or a Stateflow API object of one of these types:

• Stateflow.Box

• Stateflow.Chart

• Stateflow.EMChart

• Stateflow.EMFunction

• Stateflow.Function

• Stateflow.Machine

• Stateflow.State

• Stateflow.SLFunction

• Stateflow.StateTransitionTableChart

• Stateflow.TruthTable

• Stateflow.TruthTableChart

propertyName — Name of property

string scalar | character vector

Name of property, specified as a string scalar or character vector.

propertyValue — Value of property

any data type, depending on the property

Value of property, specified in the format determined by the property.

objectType — Type of object

string scalar | character vector | class handle

Type of object for which to search, specified as a string scalar, character vector, or a class handle for an object.

Example: find(ch,"-isa","Stateflow.State") finds the states in the chart ch.

Example: find(ch,"-isa",class(object)) finds the objects of the same type as object.

depth — Depth of search

inf (default) | nonnegative integer scalar

Depth of search in the object hierarchy, specified as a nonnegative integer scalar or inf. Use inf to search all levels of the hierarchy.

functionName — Name of object function

string scalar | character vector

Name of object function, specified as a string scalar or character vector.

function — Filtering function

function handle

Filtering function, specified as a function handle. The function must return a logical scalar value that indicates whether an object is a match.

Output Arguments

objArray — Search results

array

Search results, returned as an array of Stateflow API objects.

Tips

• To limit search results based on the value of a subproperty, call find using "-function" and a function handle. For an example, see Find Objects for Which Signal Logging Is Enabled.

• Using the find function on Simulink.Root, Simulink.BlockDiagram, or Stateflow.Machine objects can return Simulink^® objects that match the search criteria you specify. For example, this command can return a Simulink subsystem or block named ABC:

  find(sfroot,"Name","ABC")

• Opening a main model that refers to a linked Stateflow chart does not guarantee that the Stateflow API can find the linked chart. To access the objects in a linked library chart, first load the library model into the Simulink workspace by performing one of these tasks:

  • Load the library model by calling the function load_system (Simulink).

  • Call the function find_system (Simulink) with the FollowLinks argument set to on:

    find_system(FollowLinks="on");

  • View a linked subsystem or block in the main model.

  • Compile or simulate the model.

Version History

Introduced before R2006a