Community Highlights

Community Pick

Adam Danz
972 views (last 30 days)

New in R2021a: Name=Value syntax

Adam Danz on 31 Mar 2021 (Edited on 29 Apr 2021)
Latest activity Edit by cui on 26 Aug 2021

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.

 
Camilo Andres Manrique Escobar
Camilo Andres Manrique Escobar 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.

 
1 Reply
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.

 
1 Reply
cui
cui 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
cui 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!
 
1 Reply
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.

 
1 Reply
cui
cui 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

 
1 Reply
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)
 
1 Reply
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!

 

Related Content

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!