What does the exist function do in MATLAB / RunMat?

exist(name) returns an integer code that identifies which kind of item named name is currently available. The codes match MATLAB:

Pass a second argument to restrict the lookup (for example, 'file', 'dir', 'builtin', 'class', 'mex', 'pcode', 'method', or 'handle'). The builtin mirrors MATLAB semantics for string handling, search order, and numeric return values.

How does the exist function behave in MATLAB / RunMat?

• Searches follow MATLAB's precedence: variables first, then built-ins, classes, compiled code (MEX/P-code), standard files, and finally folders.
• When you omit the type, exist returns the first match respecting this precedence.
• String handling matches MATLAB: name and the optional type must be character vectors or string scalars. String arrays must contain exactly one element.
• Paths expand ~ to the user's home folder. Relative paths resolve against the current working directory, and RunMat honours RUNMAT_PATH / MATLABPATH entries when searching for scripts and classes.
• Package-qualified names such as pkg.func and pkg.Class map to +pkg folders automatically. Class queries also recognise @ClassName folders and .m files that contain classdef.
• GPU-resident arguments (for example, gpuArray("script")) are gathered automatically, so callers never need to move text back to the CPU manually.
• Unsupported second-argument types surface a MATLAB-compatible error listing the accepted keywords.

exist Function GPU Execution Behaviour

The builtin runs entirely on the host CPU. If any argument lives on the GPU, RunMat gathers it to host memory before performing the lookup. Providers do not implement dedicated hooks for exist, and the result is always returned as a host-resident double scalar. Documented behaviour is identical regardless of whether acceleration is enabled.

Examples of using the exist function in MATLAB / RunMat

How to check if a workspace variable exists

alpha = 3.14;
status = exist("alpha", "var");

Expected output:

status =
     1

How to determine if a built-in function is available

code = exist("sin");

Expected output:

code =
     5

How to test whether an M-file is on the MATLAB path

status = exist("utilities/process_data", "file");

Expected output (assuming the file exists):

status =
     2

How to verify a folder exists before creating logs

mkdir("logs");
status = exist("logs", "dir");

Expected output:

status =
     7

How to detect class definitions in packages

status = exist("pkg.Widget", "class");

Expected output:

status =
     8

How to inspect compiled MEX fallbacks

if exist("fastfft", "mex")
    disp("Using compiled fastfft.");
else
    disp("Falling back to MATLAB implementation.");
end

Expected output:

% Prints which implementation will be executed based on the presence of fastfft.mex*.

GPU residency in RunMat (Do I need gpuArray?)

No. exist gathers any GPU-resident string inputs transparently. The lookup, file system checks, and return value are always host-side operations. Keeping text on the GPU offers no performance benefits, so you can pass regular character vectors or string scalars.

FAQ

• Does exist support wildcards? No. Strings containing * or ? return 0, matching MATLAB behaviour.
• What about Simulink models or Java classes? RunMat reports 4 for .slx / .mdl files. Java class detection is not implemented yet and currently returns 0, mirroring MATLAB when Java support is unavailable.
• How are packages handled? Names like pkg.func translate to +pkg/func.m. Class queries additionally search +pkg/@Class folders.
• Is the search path configurable? Yes. RunMat honours the current working directory plus any folders listed in RUNMAT_PATH or MATLABPATH (path separator aware).
• What's the search precedence when multiple items share a name? Variables have highest priority, followed by built-ins, classes, compiled code (MEX/P-code), standard files, and folders last—exactly like MATLAB.
• What happens with unsupported type keywords? The builtin raises exist: invalid type... describing the accepted tokens, matching MATLAB's diagnostic.
• Do handle queries work? When the first argument is a RunMat handle object, exist(handle, "handle") returns 1. Numeric graphics handles are not yet supported and return 0.

See Also

dir, ls, copyfile, pwd

Source & Feedback

• Source: crates/runmat-runtime/src/builtins/io/repl_fs/exist.rs
• Found an issue? Open a GitHub ticket with steps to reproduce.