- Undocumented Matlab - https://undocumentedmatlab.com -

Setting class property types

Posted By Yair Altman On April 18, 2013 | 40 Comments

When I wrote about the undocumented aspects of classdef properties [1] half a year ago, I did not expect to learn of another major undocumented aspect in Matlab’s class-object system. last month I discovered the additional undocumented classdef Description and DetailedDescription attributes, and updated that article accordingly. But a few days ago I was pleasantly surprised to read Amro’s comment [2] about an entirely new and undocumented aspect of Matlab MCOS classes.

Amro [3] is a top contributor on StackOverflow, where he frequently answers questions before I even get any subscription notification about them… His answers are generally characterized by a deep technical understanding of Matlab, and I’ve learned quite a lot from him in the past few years. This time was no different.

In a nutshell, Amro found an undocumented way to specify a class object property’s type, in such a way that would prevent accidental setting to an incompatible value. For example, if we have a class with properties Width and Height, we probably want to restrict their possible values to numbers, to prevent setting a string or struct value.

In UDD classes, we can do this easily by setting the property’s DataType meta-property. An easy way to do this is by setting the second argument of the schema.prop function [4]. A detailed explanation was provided here [5].

We can still do this today, since UDD classes are still supported, side-by-side with the newer MCOS classes. Unfortunately, MCOS does not provide a documented [6] way of specifying the property type as in UDD.

One simple way to prevent unintentional MCOS property updates is to override the property’s set method [7]. In fact, this was the solution [8] of Jonas, another StackOverflow heavyweight:

classdef myClass
      myProperty = uint16(23); %# specify default value using correct type
      function obj = set.myProperty(obj,val)
         if ~isa(val,'uint16')
            error('only uint16 values allowed')
         %# assign the value
         obj.myProperty = val;

But it turns out that there’s a much cleaner and simpler solution, provided [9] by Amro:

classdef Packet
        PayloadLength@uint16 = uint16(0);

As Amro notes, if you try to set a property with the wrong type, you get an error:

>> p = Packet;
>> p.PacketType = 'tcp';  % ok
>> p.HeaderLength = 100;  % not ok - should be a uint16
While setting the 'HeaderLength' property of Packet:
Value must be 'uint16'.

This syntax apparently supports all primitive types (char, int32, double, struct, cell etc.), in addition to any user-defined ones (just use any class name).
Note that setting the type as above seems to override any set method that may have been specified for the property.

Amro came across this syntax in an internal class in R2013a (toolboxdir(‘matlab’)/graphics/+graphics/+internal/+figfile/@FigFile/FigFile.m), but it also worked in R2012a, and probably older versions as well…

I admit there’s not much original work here by me – it’s basically all by Amro (and Donn Shull for the UDD part). But I thought it’s important enough to bring to the attention of the community.

I love to discover such undocumented treasures by digging in Matlab’s function. If you ever discover other such buried treasures, please do let me know by email or a comment.

Addendum June 21, 2013: As Sebastian Hölz mentioned in his comment [10] below, the general syntax appears to be:

   propName@className dimensionType = initialValue

where className, dimensionType and initialValue are optional elements:

  • className can be any Matlab class/type, such as double, single, or UserClass
  • dimensionType can be one of the following terms: scalar, vector, or matrix
  • the property may also be initiated with an initialValue (otherwise it receives a default value, depending on the property class)

Addendum August 12, 2014: In a related matter, we can limit the values that a property can accept using the matlab.system.StringSet [11] class of the matlab.System [12] package, as recently discovered [13] by Oleg Komarov (additional details [14]; additional aspects of class property tab-completion [15]):

classdef foo < matlab.System
        CoordinatesSet = matlab.system.StringSet({'north','south','east','west'});

restricting Matlab property values

Addendum April 8, 2015: As reported by Martin A. here [16] and also below [17], R2015a has apparently added the new (and hidden) Type property to the meta.property class and the InputTypes and OutputTypes properties to the the meta.method class. This enables specifying and querying the types of properties as well as method inputs/outputs. For example:

mc = ?matlab.graphics.axis.Axes;
mc.PropertyList(1).Name % Camera
mc.PropertyList(1).Type % matlab.graphics.axis.camera.Camera
mc.MethodList(49).Name % addlistener
mc.MethodList(49).InputNames % [sources, propertyname, eventname, callback]
mc.MethodList(49).InputTypes % [handle, asciiString, char vector, function_handle scalar]

Addendum November 11, 2015: Apparently [18], when using the @double syntax, Matlab only allows the property to receive real values. In order to enable complex values, we can also add the undocumented "complex" attribute. Note that we have to enter the dimensionality (scalar/vector/matrix) first, since "complex" is not accepted as a valid dimensionality value. For example:

% This is ok:
classdef foo
        bar@double scalar complex = 1 + 2i
% This causes an error:
classdef foo
        bar@double complex = 1 + 2i

Addendum April 28, 2016: Matlab R2016a now has a similar documented functionality. However, I feel that there are important drawbacks to the new functionality compared to the one presented here. Read the full discussion about this [19].
The new (documented) syntax automatically type-casts the data to the specified data type, were possible, something that the undocumented (@) syntax presented above does not. In other words, the undocumented syntax is stricter and expects the data to be exactly the specified data type, without attempting any type-casting. As reported by Martin Afanasjew [20], we can add the property attribute to the data type to replicate the new syntax's automatic type-casting:

classdef foo
        prop1@char = 'A'  % will only accept char inputs, not numeric values
        prop2@char property = 65  % will automatically type-cast: 65 will be converted to 'A'

Addendum September 30, 2022: Matlab R2022a has made the legacy @ syntax unsupported, displaying an error message about it in the Matlab Editor, and generating a run-time error if you try to use a class that uses this syntax.

Categories: Medium risk of breaking in future versions, Undocumented feature

40 Comments (Open | Close)

40 Comments To "Setting class property types"

#1 Comment By Donn Shull On April 18, 2013 @ 09:27

For users with Simulink there is a documented way for setting a few data types on properties using the PropertyType qualifier. Examples include

properties(PropertyType = 'int32 scalar') 


properties(PropertyType = 'char', AllowedValues ={'a', 'b', 'c'})

When I discovered this I noticed that mlint flags this syntax as an error. I submitted a bug report to The MathWorks and have been informed that that this will be addressed in a future version of MATLAB. The MathWorks has updated the documentation to reflect this problem. To me this syntax seems slightly more readable than the form from this article (good catch finding this undocumented gem). It would be nice if The MathWorks extended this syntax to classdef in general and expanded the PropertyType specification to include all data types.

#2 Comment By Jim Hokanson On April 27, 2013 @ 05:26

Interesting, however this seems like something that would be better to implement at the property level, and not for a set of properties. I am sure there was a decent amount of discussion at TMW about applying property attributes to a block or to each property. I sometimes find the block syntax to be highly disruptive to related properties that I would like to have grouped together, but that require different attributes. In this case it seems like allowed values and types would be better at the level of a property and not the block, although in the case of Simulink it seems like TMW felt otherwise.

#3 Comment By Donn Shull On April 27, 2013 @ 08:36

With the R2012a release of MATLAB Simulink.Parameter and Simulink.Signal became MCOS objects. In previous releases they were UDD objects. The documented way to create subclasses of these classes before R2012a was to use a GUI known as the Simulink Data Class Designer. I suspect that the PropertyType qualifier was added to give some compatibility with the UDD version of these objects.

#4 Comment By Kristian Svartveit On April 18, 2013 @ 23:52

I have been using this from the first time I got a beta version of Matlab’s new OO classes. Never knew it wasn’t documented…


#5 Comment By Yair Altman On April 19, 2013 @ 02:03

@Kristian – interesting: Do you remember where you had first learned of this syntax?

#6 Comment By Jonas On April 19, 2013 @ 07:03

Thanks for the mention. I’m glad to have been able to contribute at least the “boring” example to your great blog 🙂

#7 Comment By Yair Altman On April 19, 2013 @ 07:55

@Jonas – it’s a sad world that we live in, if the textbook solution is called “boring”…
You, Amro and gnovice always seem to post detailed answers on SO so fast, before I even get a chance to see the questions. You don’t leave the little guys like me much of a chance to score rep points… 🙂

#8 Comment By Amro On April 19, 2013 @ 07:14

@Donn Shull:
matlab.System objects also have a similar documented qualifier, although less powerful. Only Logical and PositiveInteger are available: [27]

For example:

classdef Adder < matlab.System
    properties (PositiveInteger) % limit values to positive integers
        a = 1;
    methods (Access=protected)
        function y = stepImpl(obj,x)
            y = x + obj.a;


h = Adder;
h.a = -1;   % error
h.a = 2;    % ok

@Yair Altman:
I did a search on my MATLAB installation, and I found only one other use of the prop@type syntax inside some file part of a Simulink toolbox: toolboxdir(‘sl3d’)/sl3d/+vr/@figure/figure.m (line 286).

In fact my grep-fu skills uncovered a couple more undocumented OOP things! Many internal functions used by the Parallel Computing toolbox seem to be using custom property attributes like:

properties ( PCTGetSet, PCTConstraint='string' )
properties ( PCTGetSet, PCTConstraint='callback' )
properties ( PCTGetSet, PCTConstraint='logicalscalar|presubmission' )

For example, refer to the file: which -all parallel.Task

In this case I don’t think this is just a case of undocumented language syntax. I am starting to think that there is a way to define your own custom property attributes on classes and have them do stuff like type checking, much like matlab.System system objects or Simulink data classes.

Unfortunately several classes which others derive from are either protected as p-code files or implemented as builtins… So more digging is needed 😉

#9 Comment By Jim Hokanson On April 27, 2013 @ 05:59

This is an exciting move by TMW to start to allow easy, optional ways of strictly defining property types. What wasn’t immediately clear from a quick skim of the post (but was in fact present on further review), was that you can apply class definitions to this approach as well


I recently posted an enhancement request asking TMW to allow the editor to assume that the first input to a method is an instance of the class. This would significantly enhance tab complete functionality. The workaround is to first enter the method and to do all of the programming in debug mode where Matlab can tell what all the variables are.
They politely informed me that the first variable is not always an object instance due to inferior/superior relations (Useful for operator methods like +,*,| etc). I think having tab complete be wrong 1% (0.00001%?) of the time would be fine, given the enhancement and the fact that it is tab complete, not code execution.

Back to this post, if an object instance can now be inferred from the object method, and we can specify properties as belonging to classes, then it would be possible to tab complete the property as well!


Switching topics …
As those that commonly use OOP in Matlab know, their design is rapidly evolving. This also includes a large host (IMHO) of bugs that have yet to be fixed, or that are fixed and make backwards compatibility difficult.

This undocumented feature is not immune. In my testing, assignment of a numeric scalar to a property that is defined as a class type is allowed.

From code bit above:

my_prop = my_second_class; %Correct
my_prop = some_different_class; %Throws an error
my_prop = 1; %No error :/

#10 Comment By Donn Shull On April 27, 2013 @ 08:22

This numerical argument “bug” may be intentional since The MathWorks frequently uses numeric handles for classes.

#11 Comment By Jim Hokanson On April 30, 2013 @ 06:17

Apparently this only occurs in limited cases. The example I noticed it in was assignment in the constructor which is followed by more property assignments within the constructor.

#12 Comment By Chris Hoogeboom On May 1, 2013 @ 08:37

Wow, This is a great find, and will save me so much time! Thanks a lot!

#13 Comment By Sam P On May 28, 2013 @ 16:22

Do you have any experience with using this kind of undocumented feature for production code? Does “undocumented” imply “unsupported” in your experience? This kind of thing is super useful, but will it last the next 10 releases?

#14 Comment By Yair Altman On May 28, 2013 @ 16:42

@Sam – undocumented indeed means unsupported in most cases. What this means in practice is that we are allowed to use these features, but if you find a bug or encounter problems you should not expect MathWorks to help you (they might but they do not have to). Everything in this blog abides by the license agreement as far as I know (note that I am an engineer, not a lawyer), so AFAIK there is no legal question, only a question of supportability. You may use these features as you see fit, but only on an as-is basis, without any warranty or support of any kind.

I know of many people/firms who use these features in production system, but I also know many who only use fully-documented/supported stuff – the choice is entirely yours.

As for the next 10 releases I have absolutely no idea. I do not believe that even MathWorks have a detailed roadmap so far into the future. Many of these features have remained as-is for the past 10 releases, but nobody can promise they will remain. Some of them may be removed in the very next release, or in 5 years, or never. As long as you stay with your current release in your production system and retest thoroughly whenever you upgrade the Matlab release, then you should be ok (after all, you can always remove the extra features if something starts to break in the future).

Having said that, I try to label my articles in one of three categories based on my personal subjective gut feeling on their presumed risk of failing in some future Matlab release. Hover your mouse over the low/medium/high category links in the Categories list on the right of this page to see a detailed description of what the different levels mean. This may help you make a personal decision on which features to use in your system. Just note that I base my labeling on gut feeling, not on any insider information (I am independent of MathWorks). My personal subjective labeling of this article was “Medium risk of breaking in a future release“.

#15 Comment By Martin Lechner On June 5, 2013 @ 23:12

That are great news for me.

I tried to add scalar behind the type of the property. This restricts the values to scalar values and also works for user defined classes. This saves me a lot of type checks.
Thanks, Martin

   val@double scalar
   val2@pack.subpack.UserClass scalar

#16 Comment By Sebastian Hölz On June 21, 2013 @ 03:13

Interesting …

I took a look into some examples in the Matlab installation and found several examples. The general syntax seems to be:

   val@classname dimension = value

classname can be anything like double, single, UserClass etc. and dimension can be scalar, vector, matrix. As last input the property may also be initiated with a value.

Maybe there is a way to prevent empty values, infinity, … I don’t know, but maybe someone else does.



#17 Comment By Yair Altman On June 21, 2013 @ 03:32

@Sebastian – thanks for the clarification, I updated the main article text accordingly.

#18 Comment By Sebastian Hölz On June 21, 2013 @ 05:45

Yair states that ” … Note that setting the type as above seems to override any set method that may have been specified for the property.”. I can not confirm this for the above syntax (tested in Matlab 2011b and 2013a). Property-set functions are called as expected.

#19 Comment By Sumaia On June 27, 2013 @ 13:50

I have a question in MATLAB and still a student
use matlab to design a 3_tap fir low pass filter with a cutoff frequency of 800HZ and sampling rate 8000HZ usin
Rectangular window
Triangular window
Hanning window
Blackman window

#20 Comment By Yair Altman On June 27, 2013 @ 13:56

@Sumaia – this is not a general Matlab forum, but a website dedicated to specific advanced Matlab topics. In any case, we do not solve homework assignments here.

Good luck in your studies. Do visit again when you become proficient enough with Matlab to benefit from the articles here.

#21 Comment By Jaxor24 On August 20, 2013 @ 19:06

Finally! This will save me a lot of type checking. One (perhaps obvious) thing I’ve noticed is that when
properties are UserClass vectors you need to use .empty() to manually initialize.


You will need to call


to ‘reset’ the object, rather than

listOfObjects = []

#22 Comment By Toea On July 25, 2014 @ 01:53

The fact that for user classes we need to use


instead of

listOfObjects = []

prevent us to remove an element in a list using for example

listOfObjects(id) = []

It takes me hours to understand what was wrong in my delete method!!

Do you think there is a way to remove easily an element when you use this undocumented features?

#23 Comment By Jan On June 4, 2015 @ 06:54

@Toea: I don’t quite understand the problem. In my 2013b the assignment

   function deleteFirst(self)
      self.listOfObjects(1) = [];

worked just as expected. Otherwise:

   function deleteFirst(self)
      self.listOfObjects(1) = UserClass.empty();

works just as well, as long as UserClass is not abstract.

#24 Pingback By More on Typing Systems | Matlab Love! On March 25, 2014 @ 12:59

[…] I came across this article from the blog Undocumented Matlab. It basically shows a way to define a type for each of the […]

#25 Pingback By Class object tab completion & improper field names | Undocumented Matlab On August 12, 2014 @ 10:16

[…] a different way to constrict property data type […]

#26 Comment By ola On October 10, 2014 @ 04:24

Is there any way of introspect this type restriction? findproperty doesn’t seem to reveal it unfortunately…

#27 Comment By Yair Altman On October 10, 2014 @ 05:40

@Ola – I do not know of a direct way, but perhaps there is a way. Anyway, if the property happens to have a default value you can get its type:

>> classDef = ?Packet;  % or: metaclass(Packet)
>> payloadLengthProp = classDef.PropertyList(2);  % simpler for handle classes: findprop(object,propName)
>> payloadLengthType = class(payloadLengthProp.DefaultValue)
ans = 

#28 Comment By Martin On January 3, 2015 @ 16:33

There is a way to introspect this, but it was added very recently (R2015a), e.g.:

mc = ?meta.class

The hidden Type property of the meta.property class holds an instance of the hidden meta.type class (or the equally hidden meta.EnumeratedType for certain properties of graphics classes). No restriction on the type is expressed with a type name of any.

The hidden InputTypes and OutputTypes properties of the meta.method class are just cell arrays of strings containing the type names. (I’m not aware of a way to express this restriction on input and output arguments in pure MATLAB code, so this information seems to be only helpful for built-in methods.)

#29 Comment By Erich Ritz On October 8, 2015 @ 11:30

Warning! MATLAB 2015b crashes when referencing class properties defined as scalar using this method, if those properties are also Constant properties. I reported this to The MathWorks and the response is their development team is actively investigating to fix this issue, which may be included in future releases. In the meantime, remove the use of the undocumented type syntax or downgrade to R2015a.

classdef TestDataClass
    properties (Constant)
        x@double scalar = 1;

This will crash:

testData = TestDataClass;

#30 Comment By Yair Altman On October 8, 2015 @ 11:59

thanks for reporting this Erich

#31 Comment By PYC On November 24, 2015 @ 03:25

Very useful feature Yair! Unfortunately, I still cannot exploit it to its full potential, since I would like to specify that a property be a complex double scalar. If I use the syntax var@double scalar, then Matlab will only allow me to assign real values to var.

I have tried a number of ways to find the correct syntax. For example, [28] does not cover complex variables. Also, you can ask Matlab to tell you the variable type using the class() function, but this doesn’t distinguish between real and complex double floats. Lastly, the workspace panel says the type is “double (complex)”, but I have not been able to discover from this the correct syntax to use.

Do you have any ideas? Or perhaps this is simply impossible.

#32 Comment By Yair Altman On November 24, 2015 @ 06:18

Simply add the “complex” attribute:

classdef test_mcos
        value@double scalar complex = 1 + 2i

>> t = test_mcos
t = 
  test_mcos with properties:
    value: 1 +    2i

#33 Comment By Adam Gogacz On April 24, 2016 @ 14:18

Thanks for this Yair. I’ve used this approach in the past. However, as of 2016a MATLAB has a documented way of casting the property value.


#34 Comment By Yair Altman On April 27, 2016 @ 23:24

@Adam – see my response in detail here: [29]

#35 Comment By Adam Gogacz On May 4, 2016 @ 16:34

I agree with your point. I can think of many simple solutions to type-specification without breaking users’ code all the while sticking to the convention of having the type to the left of the variable. For example, specifying the type in brackets to the left of the property (i.e. myProp), or a thousand other ways. Another lacking feature is the ability to specify type when adding a property dynamically via “addprop”.

#36 Comment By Marshall On October 31, 2016 @ 19:44

Is there a way to specify that a property must be of a subclass type? For example, the following is not allowed:

configset@Simulink.ConfigSet scalar;

The ‘.’ in there messes up the syntax parser, and I can’t figure out how to get around this.

#37 Comment By Yair Altman On November 1, 2016 @ 00:19

@Marshall – perhaps you can create a new class that inherits Simulink.ConfigSet and adds nothing to it, whose only benefit is the fact that it does not have a dot in its class name:

classdef Simulink_ConfigSet < Simulink.ConfigSet

Then you can simply use the new class name:

configset@Simulink_ConfigSet scalar

#38 Comment By Wil Koenen On December 5, 2019 @ 14:30

The undocumented syntax, e.g.

classdef MyClass
        prop@double scalar = 3;

runs fine in R2019a, but produces a warning in R2019b:

Warning: Class 'MyClass' uses an undocumented syntax to restrict property values. 
Use property validation syntax instead. This warning will become an error in a future release.

#39 Comment By Jeremiah Sullivan On September 30, 2022 @ 16:50

For what its worth, I am still getting that same “undocumented syntax” warning in 2022a. I really hope they don’t create another breaking change…

#40 Comment By Yair Altman On September 30, 2022 @ 17:53

Starting in R2022b the legacy @ syntax has changed from a warning to an error. Classes that use the legacy syntax generate a run-time error and no longer run.

Article printed from Undocumented Matlab: https://undocumentedmatlab.com

URL to article: https://undocumentedmatlab.com/articles/setting-class-property-types

URLs in this post:

[1] undocumented aspects of classdef properties: http://undocumentedmatlab.com/blog/undocumented-classdef-attributes/

[2] comment: http://undocumentedmatlab.com/blog/undocumented-classdef-attributes/#comment-189056

[3] Amro: http://stackoverflow.com/users/97160/amro

[4] schema.prop function: http://undocumentedmatlab.com/blog/creating-a-simple-udd-class/

[5] here: http://undocumentedmatlab.com/blog/udd-properties/

[6] documented: http://www.mathworks.com/help/matlab/matlab_oop/defining-properties.html

[7] override the property’s set method: http://www.mathworks.com/help/matlab/matlab_oop/implementing-a-set-get-interface-for-properties.html

[8] solution: http://stackoverflow.com/a/7192964/233829

[9] provided: http://stackoverflow.com/a/15992558/233829

[10] comment: http://undocumentedmatlab.com/blog/setting-class-property-types/#comment-215669

[11] matlab.system.StringSet: http://www.mathworks.com/help/simulink/slref/matlab.system.stringset-class.html

[12] matlab.System: http://www.mathworks.com/help/simulink/slref/matlab.system-class.html

[13] discovered: http://www.mathworks.com/matlabcentral/answers/138149-autocomplete-of-properties-for-hgsetget-derived-class#answer_144336

[14] additional details: http://www.mathworks.com/help/simulink/ug/limit-property-values-to-a-finite-set-of-strings-1.html

[15] additional aspects of class property tab-completion: http://undocumentedmatlab.com/blog/class-object-tab-completion-and-improper-field-names

[16] here: http://undocumentedmatlab.com/blog/plot-legend-title#comment-347508

[17] below: http://undocumentedmatlab.com/blog/setting-class-property-types#comment-343150

[18] Apparently: http://undocumentedmatlab.com/blog/setting-class-property-types#comment-362420

[19] full discussion about this: http://undocumentedmatlab.com/blog/setting-class-property-types-2

[20] reported by Martin Afanasjew: http://undocumentedmatlab.com/blog/setting-class-property-types-2#comment-375230

[21] Setting class property types – take 2 : https://undocumentedmatlab.com/articles/setting-class-property-types-2

[22] Handle object as default class property value : https://undocumentedmatlab.com/articles/handle-object-as-default-class-property-value

[23] Getting default HG property values : https://undocumentedmatlab.com/articles/getting-default-hg-property-values

[24] Types of undocumented Matlab aspects : https://undocumentedmatlab.com/articles/types-of-undocumented-matlab-aspects

[25] Creating a simple UDD class : https://undocumentedmatlab.com/articles/creating-a-simple-udd-class

[26] Undocumented plot marker types : https://undocumentedmatlab.com/articles/undocumented-plot-marker-types

[27] : http://www.mathworks.com/help/comm/ref/matlab.systemclass.html

[28] : http://www.mathworks.com/help/simulink/ug/simulink-data-class-extension-using-matlab-class-syntax.html

[29] : https://undocumentedmatlab.com/blog/setting-class-property-types-2

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.