Highlights
Follow


New in R2021a: Name=Value syntax

Adam Danz on 31 Mar 2021 (Edited on 29 Apr 2021)
Latest activity Reply by Rik on 17 Oct 2023

Starting in MATLAB R2021a, name-value arguments have a new optional syntax!

A property name can be paired with its value by an equal sign and the property name is not enclosed in quotes.

Compare the comma-separated name,value syntax to the new equal-sign syntax, either of which can be used in >=r2021a:

  • plot(x, y, "b-", "LineWidth", 2)
  • plot(x, y, "b-", LineWidth=2)

It comes with some limitations:

  1. It's recommended to use only one syntax in a function call but if you're feeling rebellious and want to mix the syntaxes, all of the name=value arguments must appear after the comma-separated name,value arguments.
  2. Like the comma-separated name,value arguments, the name=value arguments must appear after positional arguments.
  3. Name=value pairs must be used directly in function calls and cannot be wrapped in cell arrays or additional parentheses.

Some other notes:

  1. The property names are not case-sensitive so color='r' and Color='r' are both supported.
  2. Partial name matches are also supported. plot(1:5, LineW=4)

The new syntax is helpful in distinguishing property names from property values in long lists of name-value arguments within the same line.

For example, compare the following 2 lines:

h = uicontrol(hfig, "Style", "checkbox", "String", "Long", "Units", "Normalize", "Tag", "chkBox1")

h = uicontrol(hfig,  Style="checkbox",    String="Long",    Units="Normalize",    Tag="chkBox1")

Here's another side-by-side comparison of the two syntaxes. See the attached mlx file for the full code and all content of this Community Highlight.

19 Comments

Matthew
Matthew on 16 Oct 2023
Is it possible to turn off partial name matching for a given function?
Rik
Rik on 17 Oct 2023

Only if that is your own function and you implement that. Why are you asking?

Stephen23
Stephen23 on 3 Mar 2023
"Some other notes" is not correct: case-insensitive matching and partial name matching are actually features of the ARGUMENTS block or INPUTPARSER object. They are not inherent features of the name=value syntax.
CAME18
CAME18 on 22 Aug 2021

I am enjoying so far the new feature "Name=Value", however, a real drawback is the lack of Code Suggestions and Completions when employing this syntax. Are there any plans on extending the Code Suggestions and Completions capabilities already present on .mlx files when using the classic "Name","Value" pairs syntax?

Wan Ji
Wan Ji on 11 Aug 2021

It is better to get the hints when we use Name=Value syntax when typing m-scripts. Another thing is how to make the user-defined function available to this syntax.

Adam Danz
Adam Danz on 11 Aug 2021 (Edited on 11 Aug 2021)

An quick & dirty example of the name=value syntax in a user-defined function:

function a = fcn(varargin)
p = inputParser;
addRequired(p,'A');
addOptional(p,'B',0);
addParameter(p,'C',1);

a = 5;

end

fcn(0,C=5)

Of course IRL you'd want to add validation functions to the input parser and actually use the inputs.

Derek Foster
Derek Foster on 26 Jan 2022

How would you use the inputs? I don't see how to access them when running this script locally.

Adam Danz
Adam Danz on 26 Jan 2022

The use of name=value inputs does not differ from using 'name',value pairs. Recall that only functions accept inputs/outputs but you can defined a function within a script.

Here's another example that you can copy into a script and run. The function normalizes an array data to a range specified by MinValue and MaxValue or to [0,1] if not specified.

The example above uses inputParser for input validation while this example uses the newer arguments parser.

data = rand(5,2)*10+5
datanorm = normalizeData(data,MinValue=-12,MaxValue=10)

function out = normalizeData(data,options)
    % varargin contains name-value pairs
    arguments
        data double
        options.MaxValue (1,1) {mustBeNumeric} = 1
        options.MinValue (1,1) {mustBeNumeric} = 0
    end
    % Normalize to range of data   
    dataNorm = (data - min(data,[],'all')) / (max(data,[],'all')-min(data,[],'all'));
    % Normalize to specified min/max values
    out = dataNorm * (options.MaxValue - options.MinValue)  + options.MinValue;
end
Derek Foster
Derek Foster on 26 Jan 2022

I assume "newer" means recommended? I'm ok with that, but it looks like arguments parses based on position rather than name?

function params = fcn(options)

arguments
    options.signal
end

signal = options.signal

When I then call (intentionally trying to break it)

fcn(s='M')

I get

signal = 'M'

From the first snippet. I would expect this to error?

Adam Danz
Adam Danz on 26 Jan 2022 (Edited on 26 Jan 2022)

@Derek, as Rik mentioned and as is mentioned in note #2 within the main post, name-value pairs can be partial matches when there is no ambiguity. This is also covered in the documentation .

This is why your test worked, because "signal" starts with "s" and there are no other params that start with s. To break it, add a second parameter that starts with s or try calling fcn(signals='M') .

I try to avoid using partial matches, especially when my code is being shared. An exception is when I'm quickly testing something from the command window. But many times people use partial matches without knowing it. To set boxplot color, the official param name is Colors with an s while the param name that defines color in other functions such as plot is Color . Rather than remembering this, we can just use Color in both cases.

Rik
Rik on 26 Jan 2022

It automatically completes to the full argument name, as long as there is a unique match. That is why you often see people abbreviate UniformOutput to uni when calling cellfun or arrayfun.

I never work with this syntax, so I don't know if you can force it to error.

Derek Foster
Derek Foster on 27 Jan 2022

Ah got it. I missed that. Thank you both!

cui,xingxing
cui,xingxing on 26 Aug 2021 (Edited on 26 Aug 2021) 
fcn(0,C=5)

function a = fcn(A,C)
arguments
A
C double = 5
end

a = C;
end

Using arguments is more intuitively appropriate

cui,xingxing
cui,xingxing on 30 Jul 2021 
A = [ 1 2 3 4 ]
B = padarray(A,3,9,'pre') % official document example, It is not easy to see the meaning of the numbers 3 and 9
B = padarray(A,padsize=3,padval=9,direction='pre') % Desired enhancements，but there is an error！
Adam Danz
Adam Danz on 30 Jul 2021 (Edited on 30 Jul 2021)

The error is because padsize, padval, and direction are not name-value pairs. The first is a required input and the second two are optional positional inputs. The names for those input values are for documentation purposes only.

This new syntax is only for name-value pair parameters.

If padsize, padval, and direction were name-value pairs, the legacy syntax would appear as,

   padarray(A,'padsize',3,'padval',9,'direction','pre')
 % invalid syntax

Let me know if you have any questions about the difference between name-value pairs and optional positional inputs.

cui,xingxing
cui,xingxing on 30 Jul 2021 (Edited on 30 Jul 2021)

I understand exactly what you mean, but in terms of language universality, I hope this feature will be enhanced in future versions

both support positional and optional arguments!

https://www.mathworks.com/matlabcentral/answers/888872-is-it-possible-to-enhance-the-new-syntax-name-value-syntax-introduced-in-version-r2021a

Rik
Rik on 30 Jul 2021

What you're asking for is closer to the syntax structure that R uses.

What you're implying is that you want functions to be extended with Name,Value input options. That is very different from supporting this style for positional arguments as well. That would be a fundamental break in how calling functions works in Matlab. In some functions it might make sense to allow inputs as Name,Value pairs, but in a lot of cases it is simply too verbose.

What you're asking for is exposing the internals of functions. I understand you might want a syntax like Adam suggested, but a universal implementation would break a HUGE amount of code.

The documentation is also just a click away. Every time I work with another programming language I realize how good the documentation is for Matlab.

Rik
Rik on 31 Mar 2021

The benefits I see are maily for people who didn't use line breaks (with ...) to separate arguments.

One thing I couldn't find in the documentation: the parameter name will be provided to the function as a string in the varargin cell array. So if your input parsing already allowed scalar strings in addition to char arrays, you don't even have to change your functions.

If you plan on using my minify function, make sure you don't use this (this is a legal syntax in R2021a):

FontSize=12;
text(0.5,0.5,'a',FontSize=FontSize)
Adam Danz
Adam Danz on 31 Mar 2021

Another benefit is that Name=value syntax may be familiar to Matlab newbies who have experience in other software that support that syntax.

The new syntax also supports partial name matching, identical to the comma-separated syntax. I think I'll add that to the main post.

plot(1:5, LineW=4)

Thanks for mentioning input parsing. I initially planned to cover input validation examples with the name=value syntax but the highlight got too long.

Now I'm going to check out minify - I'm digging the formatting in your example file!

Tags