Main Content

Name=Value in Function Calls

Since R2021a

MATLAB® supports two syntaxes for passing name-value arguments.

plot(x,y,LineWidth=2) name=value syntax

plot(x,y,"LineWidth",2) comma-separated syntax

Use the name=value syntax to help identify name-value arguments for functions and to clearly distinguish names from values in lists of name-value arguments.

Most functions and methods support both syntaxes, but there are some limitations on where and how the name=value syntax can be used:

  • Mixing name,value and name=value syntaxes: The recommended practice is to use only one syntax in any given function call. However, if you do mix name=value and name,value syntaxes in a single call, all name=value arguments must appear after the name,value arguments. For example, plot(x,y,"Color","red",LineWidth=2) is a valid combination, but plot(x,y,Color="red","LineWidth",2) errors.

  • Using positional arguments after name-value arguments: Some functions have positional arguments that appear after name-value arguments. For example, this call to the verifyEqual method uses the RelTol name-value argument, followed by a string input:

    verifyEqual(testCase,1.5,2,"RelTol",0.1,...
    "Difference exceeds relative tolerance.")
    Using the name=value syntax (RelTol=0.1) causes the statement to error. In cases where a positional argument follows name-value arguments, use the name,value syntax.

  • Names that are invalid variable names: Name-value arguments with names that are invalid MATLAB variable names cannot be used with the name=value syntax. See Variable Names for more info. For example, a name-value argument like "allow-empty",true errors if passed as allow-empty=true. Use the name,value syntax in these cases.

Function authors do not need to code differently to support both the name,value and name=value syntaxes. For information on using argument validation with name-value arguments, see Validate Name-Value Arguments.