Imported from geospace-code/matlab-stdlib (AGENTS.md). Install upstream with npx skills add geospace-code/matlab-stdlib. Copyright stays with the author.

Matlab standard library project

Project Overview

This is a standard library project for Matlab, designed to provide a collection of commonly used functions and utilities. The minimum Matlab release is R2020b. The project has a strong emphasis on cross-platform compatibility, performance, and ease of use. The namespace of the project is "stdlib" as indicated by all the project functions being under directory "+stdlib/"

This project is free to use the external language interfaces provided by Matlab to call functions written in other scripting languages IF the language interface is enabled on the specific computer where Matlab is running. We do not use user-compiled MEX files or require any Matlab toolboxes, only base Matlab functionality. The specific external languages supported (if available on the user system) are

• Python: namespace stdlib.python under +stdlib/+python/, availability check stdlib.has_python()
• Java: namespace stdlib.java under +stdlib/+java/, availability check stdlib.has_java()
• .NET: namespace stdlib.dotnet under +stdlib/+dotnet/, availability check stdlib.has_dotnet()

There are a few other namespaces that are not external language interfaces:

• stdlib.shell under +stdlib/+shell/ uses system() calls to the system shell as a last-resort fallback. The speed of these calls is generally much slower than the other language interfaces.
• stdlib.native under +stdlib/+native/ uses plain Matlab code to implement functions.
• stdlib.legacy under +stdlib/+legacy/ uses plain Matlab code to implement functions for older Matlab versions that don't have the specific stdlib.native implementation for that function.

Not every language interface may be available on every system, and the availability of specific language interfaces may depend on the installation and configuration of the Matlab environment. These stdlib.has_*() functions are intended to run very quickly, caching the result using Matlab "persistent" variables as needed to make them efficient to call multiple times.

The self-test functions under "test/" directory can be used by Matlab >= R2020b as invoked by "test_main.m" at the top level of the project directory. Matlab >= R2022b should use "buildtool test" to run the self-tests.

Key limitations driving minimum Matlab version include:

• R2017b: builtin isfolder(), isfile() available
• R2017b: fileparts() supports string type. fileparts() is used in many places in the code as it's 5-10x faster than regexp() for filename parsing.
• R2018a: fileattrib(), fullfile() supports string type
• R2018a: mfilename('fullpath') tells the full path to the matlab .m file currently running (empty for older Matlab)
• R2019b: function argument validation block "arguments"
• R2020b: mustBeTextScalar(), mustBeText() functions for function argument validation, used in many places in the code.

Dev Rules

These rules apply under the namespace "stdlib" (directory +stdlib/) and all its sub-namespaces (subdirectories +stdlib/+*).

• The code syntax must work for Matlab >= R2020b
• The code must not require any Matlab toolboxes, only base Matlab functionality
• When an exception is encountered, we generally desire that the code return "missing". In certain cases we may throw or rethrow an error.
• When a backend is not available, we require that the code return "missing". The previous behavior of returning empty array or empty char or empty string is deprecated and being transitioned.
• where the output represents a filesystem path, the output should be a string type if any input is string type, otherwise char type.

Dev notes

• the backends for each function are stored in +stdlib/private/functionBackends.m, and the function +stdlib/private/filterBackend() is used to filter the backends based on availability.
• The code in stdlib.python.version, stdlib.has_python has distinct use of persistent variables, we have carefully reviewed it and are satified with its performance and correctness regarding persistent variables.
• I do not wish to implement cache reset in stdlib.python.version().

The code in the following list of stdlib.* functions is of the highest priority to be correct and efficient, as it's fundamental to correct filesystem operations. These functions are used by many other functions in this and other projects.

absolute(), canonical(), cpu_count(), exists(), expanduser(), file_checksum(), file_size(), filename(), h5save(), h5exists(), h5size(), is_absolute(), is_exe, join(), makedir(), parent(), posix(), resolve(), root(), samepath(), stem(), suffix(), with_suffix()