findLabel

Get project file label

Syntax

label = findLabel(files,categoryName,labelName)

label = findLabel(files,labelDefinition)

labelDefintion = findLabel(category,labels)

Description

label = findLabel(files,categoryName,labelName) gets the specified label, in the specified category, from the specified files. The function returns the label object and the attached data. Use this syntax when you know the label name and category. If the label is not found, findLabel returns an empty array.

label = findLabel(files,labelDefinition) gets the label defined by the specified label definition object. Use this syntax if you previously created a labelDefinition using a Labels property, for instance by using an expression like category.LabelDefintions(1).

labelDefintion = findLabel(category,labels) gets the label definition that you can use to find files with the label. Use this syntax if you created a category object using the createCategory or the findCategory functions.

Examples

Find Files with Label

Find all project files with the label "Design".

Tip

Starting in R2024a, to find all project files with a specific label, use findFiles instead of findLabel for more direct solutions. For an example, see Create Test Suite Using Project Labels.

Open the Times Table App project. Use currentProject to create a project object from the currently loaded project.

openExample("matlab/TimesTableProjectExample")
proj = currentProject;

Get the list of project files.

files = proj.Files;

Use the findLabel function to find all the files with the label "Design".

designFilesToReview = [findLabel(files,"Classification","Design").File]'

designFilesToReview = 

  5×1 string array

    "C:\Workspace\TimesTableApp\source\timesTableGame.m"
    "C:\Workspace\TimesTableApp\source\timestable.mlapp"
    "C:\Workspace\TimesTableApp\utilities\editTimesTable.m"
    "C:\Workspace\TimesTableApp\utilities\openRequirementsDocument.m"
    "C:\Workspace\TimesTableApp\utilities\runTheseTests.m"

Find Label by Category

Open the Times Table App project. Use currentProject to create a project object from the currently loaded project.

openExample("matlab/TimesTableProjectExample")
proj = currentProject;

Get a category.

category = proj.Categories(1)

category = 

  Category with properties:

        SingleValued: 1
            DataType: "none"
                Name: "Classification"
    LabelDefinitions: [1×7 matlab.project.LabelDefinition]

Get a label definition from that category.

ld = findLabel(category,"Design")

ld = 

  LabelDefinition with properties:

            Name: "Design"
    CategoryName: "Classification"

Input Arguments

files — Files to search in

array of ProjectFile objects

Files to search in, specified as an array of ProjectFile objects. You can create a project file object by examining the project files property using the syntax proj.Files, or by using findFiles.

categoryName — Name of category

string scalar | character vector

Name of category for the label, specified as a string scalar or a character vector.

labelName — Label name

string scalar | character vector

Label name, specified as a string scalar or a character vector.

labels — Label names

string array | cell array of character vectors

Label names, specified as a string array or a cell array of character vectors.

labelDefinition — Label definition

LabelDefinition object

Label definition, specified as a LabelDefinition object gotten from category.LabelDefintions(1).

category — Category object

Category object

Category object. Create a category object from the proj.Categories property or by using the findCategory function.

Output Arguments

label — Labels

array of Label objects

Label, returned as an array of Label objects.

labelDefintion — Label definitions

array of LabelDefinition objects

Label definition, returned as an array of LabelDefinition objects.

Version History

Introduced in R2019a

R2025a: Get label from a file set

Starting in R2025a, you can get labels from multiple files at the same time. See Find Files with Label.

R2025a: Get label definition for a label set

Starting in R2025a, you can get label definitions for multiple labels in a category simultaneously.

proj = currentProject;
category = proj.Categories(1);
findLabel(category,["Design","utilities"])