RunMat
GitHub

View all functions

CategoryIo: Repl Fs

What does the ls function do in MATLAB / RunMat?

ls lists the contents of a directory. Without inputs, it shows the files and folders in the current working directory. With an argument, it lists the items that match a path or wildcard pattern. The return value is a character array whose rows contain the matching names padded with spaces, mirroring MATLAB behaviour.

How does the ls function behave in MATLAB / RunMat?

  • ls without outputs displays the directory listing in the REPL. When you assign the result to a variable, you receive a character array with one row per item, padded with spaces to a fixed width.
  • ls(name) accepts character vectors or string scalars. The argument may be an absolute path, a relative path, or a wildcard such as *.m or build/*.
  • Paths beginning with ~ or ~/ expand to the current user's home directory, matching MATLAB desktop behaviour on every supported platform.
  • Wildcards follow MATLAB rules: * matches any sequence of characters and ? matches exactly one character. The pattern is evaluated relative to the current folder unless it contains a leading path.
  • Directory results include the platform-specific file separator (/ on Unix, \ on Windows) so you can quickly distinguish folders from files, and duplicate matches are removed automatically.
  • Empty matches return a 0×0 character array rather than raising an error, enabling idioms such as isempty(ls("*.tmp")).
  • Only scalar inputs are supported. Multi-row character arrays, multi-element string arrays, numeric values, or logical arguments raise ls: name must be a character vector or string scalar, mirroring MATLAB's diagnostics.

ls Function GPU Execution Behaviour

ls is an I/O-centric builtin with no GPU execution path. When the argument is a GPU-resident scalar (for example, the output of gather that remained on the device), RunMat gathers it to the host before expanding wildcards. No device kernels run, and acceleration providers do not need to implement hooks for this builtin.

GPU residency in RunMat (Do I need gpuArray?)

No. Directory listings are always computed on the CPU. Passing gpuArray("*.m") offers no benefit: RunMat will gather the value automatically before enumerating files, and results are materialised as host-resident character arrays.

Examples of using the ls function in MATLAB / RunMat

List Files In The Current Folder

ls

Expected output (example):

README.md
src/
tests/

List Only MATLAB Files Using Wildcards

ls("*.m")

Expected output:

script.m
solver.m
test_helper.m

Capture A Directory Listing In A Variable

listing = ls;
disp(listing(1, :));  % Display the first entry

Expected output:

README.md

List The Contents Of A Specific Folder

tempDir = fullfile(pwd, "tmp");
ls(tempDir);

Expected output:

tmpfile.txt
subdir/

Use Wildcards With Nested Paths

ls("src/**/*.rs")

Expected output:

src/main.rs
src/utils/helpers.rs

Handle Missing Matches Gracefully

if isempty(ls("*.tmp"))
    disp("No temporary files found.");
end

Expected output:

No temporary files found.

Combine ls With cd For Temporary Directory Changes

start = cd("examples");
cleanup = onCleanup(@() cd(start));
files = ls("*.m");

Expected output:

animation.m
plot_surface.m

FAQ

  • What types can I pass to ls? Use character vectors or string scalars. Other types – including numeric values, logical arrays, or string arrays with multiple elements – produce an error.
  • Does ls support wildcard patterns? Yes. Use * to match any sequence and ? for a single character. Patterns are resolved relative to the current folder unless you provide an absolute path.
  • How are directories indicated in the output? Directory entries end with the platform-specific file separator (/ or \) so you can distinguish them from files.
  • What happens if there are no matches? The function returns a 0×0 character array. You can test for this with isempty or by checking size.
  • Can I list the contents of another drive or mounted volume? Yes. Provide the absolute path, e.g., ls("D:\Projects") on Windows or ls("/Volumes/Data") on macOS.
  • Does ls follow symbolic links? The function reports the link itself; if the link points to a directory, it receives the directory suffix but the listing does not recursively expand the target.
  • Will ls respect the current working directory set by cd? Absolutely. ls always evaluates relative paths against whatever pwd reports.
  • Is the output sorted? Yes. RunMat sorts case-insensitively on Windows and case-sensitively on Unix-like systems to match MATLAB conventions.
  • How do I list hidden files? Hidden files are included when they match the pattern you specify. On Unix-like systems, prepend a dot: ls(".*").
  • Can I send the output directly to another builtin? Yes. Because the result is a character array, you can convert it to a string array with string(ls) or operate on individual rows using indexing.

See Also

pwd, cd, fopen, fclose

Source & Feedback