---

name: matlab-validate-function-arguments description: > Use when writing MATLAB functions with arguments blocks — repeating arguments (arguments (Repeating)), .?ClassName property import in constructors, name-value forwarding with namedargs2cell, or migrating from inputParser or validateattributes. Also when reviewing signatures for implicit-conversion pitfalls (size reshaping, class coercion, computed defaults), or when restricting, constraining, or validating function inputs — scalar vs vector enforcement, type rejection, size checking. Also when asked to harden inputs, make a function more robust, tighten input checking, or rewrite for safer input acceptance — even without "validation" or "arguments block" wording. Triggers on: arguments block, mustBe validators, name-value arguments, varargin, inputParser, nargin/narginchk, restrict input, type checking, scalar constraint, harden inputs, defensive programming. Not for: App Designer callbacks, Simulink mask parameters, class inheritance, or runtime validation outside function or property declarations. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.2"

MATLAB Function Argument Validation

Write robust MATLAB functions using arguments blocks with correct semantics for size, class, repeating arguments, and property import.

When to Use

• Writing a function with an arguments block
• Using repeating arguments (arguments (Repeating))
• Writing a class constructor that accepts name-value arguments
• Migrating from inputParser or validateattributes
• Reviewing a function signature for implicit conversion pitfalls
• Choosing between class specs, mustBeA, and validators

When NOT to Use

• Basic MATLAB programming without argument validation
• App building or UI components (use matlab-building-apps)
• Unit testing (use matlab-write-tests)
• General OOP class design unrelated to argument validation
• Simple if/error guard clauses for runtime invariants inside a function body (those aren't input validation — leave them as-is unless the user asks for an arguments block specifically)
• .mlx (Live Script) or .mlapp (App Designer) files — these are binary ZIP containers. Don't unzip them or attempt structural edits. If the user asks to add an arguments block to a function inside one, ask them to export to plain .m first, or open the file in MATLAB and edit it there.

Critical Misconceptions

These are things the agent commonly gets wrong. Read these FIRST.

Size specs RESHAPE, not reject

WRONG belief: (1,:) rejects column vectors with an error.

ACTUAL behavior: MATLAB silently reshapes the input to fit the declared size.

function out = myFunc(x)
    arguments
        x (1,:) double
    end
    out = x;
end

myFunc([1; 2; 3])  % Does NOT error! Returns [1 2 3] (reshaped to row)

A column vector [1;2;3] passed to (1,:) becomes a row vector [1 2 3]. To actually reject column vectors, use a validator:

function out = myFunc(x)
    arguments
        x {mustBeNumeric, mustBeRow}
    end
    out = x;
end

Class specs CONVERT, not reject

WRONG belief: double in the arguments block rejects non-double inputs.

ACTUAL behavior: MATLAB attempts implicit conversion to the declared class.

function out = myFunc(x)
    arguments
        x double
    end
    out = x;
end

myFunc('hello')  % Does NOT error! Returns [104 101 108 108 111] (ASCII codes)
myFunc(single(3.14))  % Does NOT error! Returns double(3.14)

To reject without converting, use mustBeA or mustBeFloat:

x {mustBeA(x, "double")}           % Rejects single, char, int32, etc.
x {mustBeFloat}                     % Accepts single OR double, rejects char/int
x {mustBeNumeric}                   % Accepts any numeric, rejects char/string

Numeric validators don't reject complex values

WRONG belief: mustBeNumeric, mustBeFinite, and mustBeInteger reject complex inputs like 1+2i.

ACTUAL behavior: Complex values are numeric, finite, and (when their real and imaginary parts are integer-valued) integer — so 1+2i passes all three silently. Sizes, indices, counts, and most physical scalars should reject complex values explicitly:

function H = hilb2(n)
    arguments
        n (1,1) {mustBeInteger, mustBePositive, mustBeReal}
    end
    H = 1./((1:n)' + (0:n-1));
end

Add mustBeReal whenever a complex input would be nonsensical for the function's contract.

Computed defaults see PASSED values, not declared defaults

WRONG belief: Default expressions use the declared default values of earlier arguments.

ACTUAL behavior: Default expressions evaluate using the actual passed values.

function out = myFunc(fs, windowSize)
    arguments
        fs (1,1) double {mustBePositive}
        windowSize (1,1) double {mustBePositive} = round(fs / 10)
    end
    out = windowSize;
end

myFunc(8000)      % windowSize = round(8000/10) = 800 (uses passed fs)
myFunc(8000, 256) % windowSize = 256 (explicitly passed)

This eliminates the need for sentinel values ([]) and post-validation fixup.

~ is a valid placeholder — don't rename it

WRONG belief: A name in the arguments block is mandatory, so a ~ placeholder in the function signature must be renamed to obj/this/etc.

ACTUAL behavior: ~ is valid as an argument-block name (R2019b+). Keep it.

function normalize(~, results)
    arguments
        ~
        results (1,:) struct
    end
    ...
end

When a method signature uses ~ to mark an unused input (e.g. an unused class instance), preserve the ~ in the arguments block:

• No class or size spec on ~ — type specs like (1,1) MetricCalculator require a name, so adding one forces a rename. Skip the spec entirely.
• No %#ok<INUSL> / %#ok<INUSA> / %#ok<MANU> pragma — ~ already tells the lint pass the input is intentionally unused.
• Don't rename ~ to obj to "tighten validation." Renaming reintroduces the lint warning the original ~ was suppressing, with no contract benefit.

Patterns

Repeating Arguments

Use arguments (Repeating) for functions accepting variable groups of arguments (like plot(x1,y1,x2,y2,...)). Each declared variable becomes a cell array in the function body.

function plotMultiSeries(x, y)
    arguments (Repeating)
        x (1,:) double {mustBeFinite}
        y (1,:) double {mustBeFinite}
    end

    figure;
    hold on;
    for i = 1:numel(x)
        plot(x{i}, y{i});
    end
    hold off;
end

Key rules:

• Variables become cell arrays — access with x{i}, not x(i)
• All variables in the group repeat together (complete sets)
• Repeating arguments cannot have default values
• Zero repetitions is valid (produces empty cell arrays)

Output Argument Validation — arguments (Output) and (Output, Repeating)

R2022b+. Output argument validation is unavailable in earlier releases — input validation (the bulk of this skill) works from R2019b onward.

Use arguments (Output, Repeating) to declare a function whose output count scales with nargout. The block must declare exactly one name — MATLAB rejects multi-name repeating output blocks with MATLAB:functionValidation:MultipleRepeatingOutputs. To return groups of related values (e.g. triples), pack them into the single output and have the caller request N * groupSize outputs.

function out = productTriples()
    arguments (Output, Repeating)
        out (1,1) double
    end
    out = cell(1, nargout);
    for k = 1:3:nargout
        b = rand;
        c = rand;
        out{k}   = b * c;
        out{k+1} = b;
        out{k+2} = c;
    end
end

Caller: [p1, a1, b1, p2, a2, b2] = productTriples();

Key rules:

• One name only — arguments (Output, Repeating) a; b; c; end errors at parse
• The output is assigned a 1×nargout cell array; comma-list expansion at the call site distributes its contents across the requested LHS variables
• Validators on the single declared name apply to each cell element
• nargout tells the body how many outputs were requested; zero is valid

Composition Rules — What Can Coexist

A function may have multiple arguments blocks. The rules below apply to the function as a whole — argument categories must appear in this order across all blocks combined:

required → optional (with defaults) → repeating → name-value

Violating the order at any point — even across separate blocks — fails to parse. Don't trust intuition: all of these compose legally in one function:

• required + optional + repeating + name-value (.?ClassName allowed too)
• required + repeating + name-value
• repeating + name-value
• (Output, Repeating) plus any combination of input blocks
• ~ placeholders inside a (Repeating) block

Multiplicity:

| Block kind | How many allowed | |------------|------------------| | Plain arguments (positional and/or name-value) | Multiple, in order | | arguments (Repeating) (input) | Exactly one per function | | arguments (Output, Repeating) | Exactly one per function | | Name-value structs across plain blocks | Multiple — different struct names |

Parse-time error identifiers — when in doubt, write the function and let MATLAB tell you. These are the only errors composition can produce; the names spell out the rule:

| Identifier | Means | |------------|-------| | MATLAB:functionValidation:RequiredAfterOptional | A required arg appears after one with a default | | MATLAB:functionValidation:OptionalAfterRepeating | An optional/positional arg appears after the repeating block | | MATLAB:functionValidation:PositionalAfterNamed | A positional or repeating arg appears after a name-value arg | | MATLAB:functionValidation:MultipleRepeatingBlocks | More than one (Repeating) block (input or output) | | MATLAB:functionValidation:RepeatingHasDefault | A (Repeating) arg has a default value |

If you're unsure whether a combination is legal, don't fabricate a restriction — write a minimal version and run it. The error identifier (or its absence) is the answer.

Maximal example

A single function with required + optional + ignored + repeating + ignored repeating + name-value + class-imported name-value (here SensorConfig — the class defined in the .?ClassName section above):

function maximal(req, opt, ~, x, ~, options, classArg)
    arguments
        req (1,1) double
        opt (1,1) double = 7
        ~
    end
    arguments (Repeating)
        x (1,1) double
        ~
    end
    arguments
        options.Title (1,1) string = "default"
        options.Verbose (1,1) logical = false
        classArg.?SensorConfig
    end
    % function body
end

Call: maximal(1, 2, 3, 4, 'a', 5, 'b', Title="t", SampleRate=44100) — parses and runs. SampleRate is one of the name-value args imported from SensorConfig by the .? line.

Don't pick a class with no public-settable properties for .?ClassName — onCleanup, for example, has only task (private set), so .?onCleanup imports zero name-value args. The line is syntactically valid but a no-op, and any "name-value" the caller writes against it is treated as an unknown name — see "unknown Name=Value is silently swallowed" in Common Mistakes.

For combining repeating args with name-value options, see the Maximal example above and references/examples/repeating-args.md.

.?ClassName — Import Properties as Name-Value Args

Use .?ClassName in constructors to derive name-value arguments directly from property definitions. This avoids redeclaring properties in the arguments block.

For additional patterns — overriding specific properties, static factory with forwarding, and wrappi