transform

Class: matlab.buildtool.io.FileCollection
Namespace: matlab.buildtool.io

Transform paths of file collection

Since R2023b

Syntax

newfc = transform(fc,fcn)

newfc = transform(fc,fcn,AllowResizing=tf)

Description

newfc = transform(fc,fcn) transforms the paths of the file collection fc with the function handle fcn. The method returns the transformed file collection as a matlab.buildtool.io.FileCollection array the same size as fc. The paths of the original and transformed file collections have a one-to-one correspondence.

You can use newfc to specify task inputs and outputs. For more information about task inputs and outputs, see Improve Performance with Incremental Builds.

newfc = transform(fc,fcn,AllowResizing=tf) also specifies whether the number of paths of fc and newfc can differ. If tf is true, a one-to-one correspondence between the paths of the original and transformed file collections is not required. For example, if fc is a file collection of .m files, newfc = transform(fc,@(paths) [paths replace(paths,".m",".p")],AllowResizing=true) creates a file collection with twice the number of paths in fc, including the original .m files as well as their corresponding P-code files.

Input Arguments

fc — File collection

matlab.buildtool.io.FileCollection array

File collection, specified as a matlab.buildtool.io.FileCollection array.

fcn — Path transformation function

function handle

Path transformation function, specified as a function handle. The function must accept the paths of fc as an input and return the transformed paths as a string vector, character vector, or cell vector of character vectors. If tf is false, then the output of the function must be the same size as the paths of fc.

Example: @(paths) replace(paths,".m",".p")

tf — Option to allow resizing

false or 0 (default) | true or 1

Option to allow resizing, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, the number of paths of fc and newfc can differ. By default, the method enforces a one-to-one correspondence between the paths of the original and transformed file collections.

Attributes

Sealed

true

To learn about attributes of methods, see Method Attributes.

Examples

Transform File Collection Paths

Transform the paths of a file collection by using the transform method.

Import the FileCollection class.

import matlab.buildtool.io.FileCollection

Create the folder structure used in this example. See the code of the local function createFile, which is used to create the files, at the end of this example.

mkdir source
createFile(fullfile("source","file1.m"))
createFile(fullfile("source","file2.m"))
mkdir source private
createFile(fullfile("source","private","file3.m"))
createFile(fullfile("source","private","file4.m"))

Create a file collection from all the .m files in the source folder and any of its subfolders. In this example, fc is a matlab.buildtool.io.Glob object because it is defined by a pattern that includes the * and ** wildcards.

fc = FileCollection.fromPaths("source/**/*.m")

fc = Glob
     source/**/*.m 

Return the paths of the file collection. When you call paths on a Glob object, the method returns the paths to the files and folders on disk that match the Glob pattern.

fc.paths'

ans = 4×1 string
    "source\file1.m"
    "source\file2.m"
    "source\private\file3.m"
    "source\private\file4.m"

Transform the paths of fc by replacing each .m extension with .p. Then, return the paths of the transformed file collection. The paths of newfc1 are the paths of fc transformed by the specified function handle.

newfc1 = fc.transform(@(p) replace(p,".m",".p"));
newfc1.paths'

ans = 4×1 string
    "source\file1.p"
    "source\file2.p"
    "source\private\file3.p"
    "source\private\file4.p"

Add a file to the source folder, and return the paths of newfc1 again. Because the Glob pattern matches the newly created file as well, newfc1 has a path to the P-code file corresponding to newFile.m.

createFile(fullfile("source","newFile.m"))
newfc1.paths'

ans = 5×1 string
    "source\file1.p"
    "source\file2.p"
    "source\newFile.p"
    "source\private\file3.p"
    "source\private\file4.p"

By default, the paths of the original and transformed file collections have a one-to-one correspondence. However, the number of paths of the original and transformed file collections can differ if you allow resizing. For example, transform the paths of fc so that the new file collection includes each .m file as well as its corresponding P-code file. In this example, newfc2 has twice as many paths as fc.

newfc2 = fc.transform(@(p) [p replace(p,".m",".p")],AllowResizing=true);
newfc2.paths'

ans = 10×1 string
    "source\file1.m"
    "source\file2.m"
    "source\newFile.m"
    "source\private\file3.m"
    "source\private\file4.m"
    "source\file1.p"
    "source\file2.p"
    "source\newFile.p"
    "source\private\file3.p"
    "source\private\file4.p"

Local Function

This code shows the local function used in this example.

function createFile(filename)
fclose(fopen(filename,"w"));
end

Tips

• If fc is a matlab.buildtool.io.File array, then the transform method does not return a File array if you allow resizing. If you want the transformed file collection to be a File array, do not specify tf as true.

Version History

Introduced in R2023b