Community Highlights

Community Pick

Adam Danz
901 views (last 30 days)

New in R2021a: Name=Value syntax

Adam Danz 2021년 3월 31일 (2021년 4월 29일에 수정됨)
Latest activity Edit by cui 2021년 8월 26일

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 2021년 8월 22일

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 2021년 8월 11일

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개의 답글
Adam Danz
Adam Danz 2021년 8월 11일 (2021년 8월 11일에 수정됨)

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

function a = fcn(varargin)
p = inputParser;
a = 5;

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

1개의 답글
cui 2021년 8월 26일 (2021년 8월 26일에 수정됨)
function a = fcn(A,C)
C double = 5
a = C;

Using arguments is more intuitively appropriate

cui 2021년 7월 30일
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개의 답글
Adam Danz
Adam Danz 2021년 7월 30일 (2021년 7월 30일에 수정됨)

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,

 % invalid syntax

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

1개의 답글
cui 2021년 7월 30일 (2021년 7월 30일에 수정됨)

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!

1개의 답글
Rik 2021년 7월 30일

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 2021년 3월 31일

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):

1개의 답글
Adam Danz
Adam Danz 2021년 3월 31일

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!


Community Treasure Hunt

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

Start Hunting!