Undocumented Matlab
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT
  • SERVICES
    • Consulting
    • Development
    • Training
    • Gallery
    • Testimonials
  • PRODUCTS
    • IQML: IQFeed-Matlab connector
    • IB-Matlab: InteractiveBrokers-Matlab connector
    • EODML: EODHistoricalData-Matlab connector
    • Webinars
  • BOOKS
    • Secrets of MATLAB-Java Programming
    • Accelerating MATLAB Performance
    • MATLAB Succinctly
  • ARTICLES
  • ABOUT
    • Policies
  • CONTACT

Setting class property types – take 2

April 27, 2016 11 Comments

Three years ago, almost to the day, I wrote about a very handy undocumented feature of Matlab classes that enables us to specify type restrictions for any Matlab class property. We can specify property type (for example, char, double or any Matlab class) as well as dimensionality (scalar, vector, or matrix) and complexity indication (complex). Doing so has multiple benefits for code performance, robustness and maintainability. For example:

% Undocumented syntax - works well since at least R2010a (possibly earlier)
classdef Packet
    properties
        PacketType@char
        HeaderLength@uint16
        PayloadLength@uint16 scalar = uint16(0);  % initial value
        PacketData@uint8 vector
    end
end

% Undocumented syntax - works well since at least R2010a (possibly earlier) classdef Packet properties PacketType@char HeaderLength@uint16 PayloadLength@uint16 scalar = uint16(0); % initial value PacketData@uint8 vector end end

In the recent release of Matlab R2016a, a similar feature have finally become fully supported and documented. The corresponding snippet above would look something like this:

% Documented syntax - only works in R2016a or newer
classdef Packet
    properties
        PacketType char
        HeaderLength uint16
        PayloadLength uint16 = uint16(0);  % initial value
        PacketData uint8
    end
end

% Documented syntax - only works in R2016a or newer classdef Packet properties PacketType char HeaderLength uint16 PayloadLength uint16 = uint16(0); % initial value PacketData uint8 end end

Unfortunately, I dislike the new documented functionality, so I didn’t feel like promoting it in this blog when it came out. But since a blog reader mentioned it a few days ago, I wanted to come out publicly with my opinion and a detailed explanation.

If you look closely at the code snippets above, you will notice two important differences:

  1. The “@” symbol was replaced with a space
  2. The dimensionality and complexity cannot be specified

The new syntax has some drawbacks compared to the previous (undocumented) one:

  1. Backward compatibility – We can run the older (undocumented) syntax on any Matlab release since who-knows-when (at least as far back as R2010a [tested], and possibly older releases [untested]), including the very latest R2016a. On the other hand, the new (documented) syntax will only work on R2016a and will crash the program if you try to run it in older releases. This is not even something that you can catch with a try-catch block – the class will simply not load on any older Matlab release. If you need your code to run on older releases in addition to 16a, you have no choice other than to use the older syntax.
  2. Dimensionality – the new syntax, unlike the undocumented syntax, does not enable users to limit the data dimensionality (scalar/vector/array). This is a very important feature for program robustness and maintainability. Complexity is another type limitation that is missing, although it is less important than the dimensionality. And just in case you were wondering – the new syntax does not accept the additional scalar, vector, matrix and complex attributes like the older syntax; using them with the new syntax evokes an error.
  3. Cross compatibility – it is very confusing to users coming to Matlab from other programming languages, all of which (without any important exception) place the type name to the LEFT of the identifier name, not to its RIGHT. People coding in both Matlab and Java/C/C++ would easily get confused and frustrated.
  4. Consistency – despite what I hoped, the new syntax still does not apply to function input args: we cannot (AFAIK) limit the input/output args of methods/functions in the same way that we can limit properties. If there’s a way to do this, I’d be delighted to learn (this comment may indicate that it is work in progress). It is true that this feature is not a drawback of the new syntax compared to the older one, since the old syntax didn’t have it either (AFAIK). But I would have expected a documented feature to be consistent across the Matlab language (or at least across the MCOS subset), and unfortunately the new feature fails this test.

In fact, aside from the fact that the new syntax is documented, I can see no advantages that it offers over the older syntax, only disadvantages. Or am I missing something? Please do tell if you see any important advantages that I’ve missed.
Luckily for us, the old syntax remains operational, side-by-side with the new one. This enables us to keep running our existing code without worrying [too much] that it might break in R2016a. Maybe the new syntax will grow on me (or improve) in upcoming years, but for the time being I see no benefit in switching away from the @ syntax.
For the past few years, I hoped that the property typing feature will become documented and that it will be a continuation of the undocumented syntax rather than what eventually aired. I’m afraid it’s too late to revert it now that it has… Realistically speaking, the best we can hope for now is for the older syntax to remain operational, and not be withdrawn in some future Matlab release. Making the undocumented syntax documented as-is would be great, but I’m afraid it is unrealistic given the new circumstances.
I’m sorry if I take the wind off MathWorks’ sails a bit here, but MathWorks knows that it can count on me to speak my mind without bullshit. Sometimes for the good, sometimes not. All in good spirit and the common interest of improving Matlab over time. No offence intended – it’s just my personal opinion after all.
In my opinion this is one of those rare cases where the developers obviously intended to make something better but eventually came out with something worse. They should have stuck to what was. After all, the first and foremost rule of engineering is, and always was:

Don’t fix it if it ain’t broke!

Related posts:

  1. Setting class property types – Matlab's class properties have a simple and effective mechanism for setting their type....
  2. Handle object as default class property value – MCOS property initialization has a documented but unexpected behavior that could cause many bugs in user code. ...
  3. Getting default HG property values – Matlab has documented how to modify default property values, but not how to get the full list of current defaults. This article explains how to do this. ...
  4. Types of undocumented Matlab aspects – This article lists the different types of undocumented/unsupported/hidden aspects in Matlab...
  5. Undocumented plot marker types – Undocumented plot marker styles can easily be accesses using a hidden plot-line property. ...
  6. Class object tab completion & improper field names – Tab completions and property access can be customized for user-created Matlab classes. ...
MCOS Object oriented Pure Matlab Undocumented feature
Print Print
« Previous
Next »
11 Responses
  1. Martin Afanasjew April 28, 2016 at 22:58 Reply

    @Yair – Addressing your “In fact, aside from the fact that the new syntax is documented, I can see no advantages that it offers over the older syntax, only disadvantages. Or am I missing something? Please do tell if you see any important advantages that I’ve missed.”

    Some may see it as an advantage, but I think the following is making things even worse. In addition to different syntax there is also different semantics of the old (undocumented) and new property type declarations. Assuming obj is an instance of a class with the following properties block

    OldStyle@char = 'old'
    NewStyle char = 'new'

    OldStyle@char = 'old' NewStyle char = 'new'

    there is this interesting behavior:

    ›› obj.OldStyle = 65;
    While setting the 'OldStyle' property of 'Properties2016a': Value must be 'char'. 
     
    ›› obj.NewStyle = 65;
    ›› obj.NewStyle
    ans =
    A

    ›› obj.OldStyle = 65; While setting the 'OldStyle' property of 'Properties2016a': Value must be 'char'. ›› obj.NewStyle = 65; ›› obj.NewStyle ans = A

    This means the new syntax automatically converts to the declared type, if possible. (To be fair, this is documented.) The old syntax is more strict and throws an error on type mismatch, something I find much more desirable.

    The following transcript reveals the difference in internal representation:

    ›› m = metaclass(obj);
    ›› m.PropertyList(1).Type.Name
    ans =
    char
    ›› m.PropertyList(2).Type.Name
    ans =
    char property

    ›› m = metaclass(obj); ›› m.PropertyList(1).Type.Name ans = char ›› m.PropertyList(2).Type.Name ans = char property

    This also means that writing NewStyle@char property is equivalent to NewStyle char and will give the new behavior using the old syntax. All of this feels pretty convoluted and like you I fail to see the benefit of creating yet another syntax instead of documenting (and extending) the old syntax that has existed for a long time.

  2. YishaiE April 29, 2016 at 03:53 Reply

    Isn’t inputParser a solution to the function input typecheck issue (kludgy and convoluted, but functional)?

    • Yair Altman April 30, 2016 at 20:25 Reply

      @YishaiE – inputParser is simply a function that checks the validity inputs. It is essentially no different than using other programmatic solutions such as assert or isa() etc. The potential benefits of constricting the input args at the function declaration level is that it would avoid the need to add these programmatic checks, and also the overheads associated with the function/method call in case of a type mismatch. Moreover, the code becomes cleaner, smaller, more robust and more maintainable. These are basically the same benefits of constricting property types.

      Hag Same’ach!

  3. Ulrik April 29, 2016 at 20:57 Reply

    Just a warning:
    The @ for properties only works well for built-in objects in the older versions of Matlab.
    If you use the @ for custom classes you can crash Matlab if the path to the classdef becomes unknown (e.g. you have not set it using addpath or the path is modified in a bad way).
    Some of the built-in stuff in Matlab is written a bit “alternative” (e.g. uigetdir) and can trigger and a bug where the Matlab UI path goes out of sync with the actual path.
    The bug seems to be (Matlab internal) event related.

    Now with the new functionality I am looking forward to testing if this bug has been fixed or not. If not Mathworks can expect a bug-report.

  4. Egon May 1, 2016 at 15:28 Reply

    Cross compatibility – it is very confusing to users coming to Matlab from other programming languages, all of which (without any important exception) place the type name to the LEFT of the identifier name, not to its RIGHT. People coding in both Matlab and Java/C/C++ would easily get confused and frustrated.
    I disagree with this. There are quite a few languages that annotate the type to the right of variable names. Just have a look at Pascal (for an old language), and newer (and popular) languages such as Scala, Swift, Go, Rust, …: all of those define the type after the variable name.

    Technically, this simplifies semantic analysis and is easier when type inference is needed.
    From a human point of view, I also think it makes more sense. Specifically: the important part is the name of a variable (what does it mean?) rather than its type (implementation detail).
    More info also at StackOverflow.

    I hence really like that in MATLAB the type declaration is after the field name (no need to replicate the behavior of languages such as C that were explicitly written to be really concise and have quite some peculiarities as a result: e.g. defining both a variable and a pointer on the same line is possible but confusing).

    On the other hand, I fully agree with your main point that MATLAB should have just documented the old syntax and not create new ones that are not backwards compatible. But if I’m completely honest, I would rather have seen the syntax as in Pascal, Swift, Scala, …:

    name : type = value

    where the :type part is optional from the start.
    I particularly dislike how the old syntax uses @while those types don’t have an obvious link to function handles, and how this only works for properties, not for function/method arguments.

    • Yair Altman May 2, 2016 at 01:32 Reply

      @Egon – surely you are not equating the importance of Pascal (which I love, don’t get me wrong) et al, with that of C/C++/C#/Java. By whichever measure that you choose, these 4 latter languages far outweigh the others in importance.

      Moreover, even the sample languages that you cite use the : operator to separate the identifier from its type, and in this respect they are much closer to Matlab’s old (undocumented) syntax that uses the @ operator.

      Finally, the @ syntax is actually consistent with Matlab classes: after all, Matlab classes use @ to indicate folders containing class methods that are implemented as independent m-files, and also to call super-class methods from a sub-class.

  5. Adam May 3, 2016 at 18:37 Reply

    Thanks, this is certainly interesting. More so for me because I somehow missed your previous post from 3 years ago and knew nothing about the undocumented syntax (or the new documented one) previously! I did see some new appdesigner code recently though which included this new syntax and surprised me since I had never seen it before and thought it must somehow be special for appdesigner-produced code.

    I have been using assignments to e.g. someClass.empty in a properties block to act mostly as documentation about what is expected and help with certain array-based initialisations and always use a validateattributes block in property set functions, but using this syntax (well, the undocumented older one at least) is potentially something I will look at for new classes.

  6. Simon May 4, 2016 at 18:58 Reply

    Matlab typing in general isn’t great. Try this;

    inceptDate datetime = datetime([],[],[]);  % The period start date as datetime

    inceptDate datetime = datetime([],[],[]); % The period start date as datetime

    Then set it like to the string –

    '1-Jan-2010'

    '1-Jan-2010'

    Matlab accepts this in both old and new ‘type checking’ formats. If you retrieve the inceptdate variable, it’s a character array, not a datetime.
    Functionally then, you *still* need to roll your own type checking, whether you use the old or new style.

    For small projects this is okay. For larger living projects, not having type safety is terrible…

  7. Chris Hoogeboom June 17, 2016 at 15:30 Reply

    Hi Yair,

    I agree with you on all of your points, especially with regards to the backwards compatibility issue. One nice thing that I noticed while reading through the documentation is that you can now specify properties to be a part of an enumeration class, which then allows you to set those properties as strings. For instance, suppose I have an enumeration

    classdef WeekDay
        enumeration
            Monday
            Tuesday
            Wednesday
            Thursday
            Friday
        end
    end

    classdef WeekDay enumeration Monday Tuesday Wednesday Thursday Friday end end

    Now I can define a class as such

    classdef DayExample
        properties
            day WeekDay = WeekDay.Monday
        end
    end

    classdef DayExample properties day WeekDay = WeekDay.Monday end end

    and now I can do

    obj = DayExample();
    obj.day = WeekDay.Monday;
    obj.day = 'Tuesday';

    obj = DayExample(); obj.day = WeekDay.Monday; obj.day = 'Tuesday';

    where in previous versions of MATLAB, I would have to implement it as

    classdef DayExampleLegacy01
        properties
            day@WeekDay = WeekDay.Monday
        end
     
        methods
            function this = set.day(this, d)
                if ischar(d) && isvector(d)
                    d = WeekDay.(d);
                end
                this.day = d;
            end
        end
    end

    classdef DayExampleLegacy01 properties day@WeekDay = WeekDay.Monday end methods function this = set.day(this, d) if ischar(d) && isvector(d) d = WeekDay.(d); end this.day = d; end end end

    or

    classdef DayExampleLegacy02
        properties
            day@char = 'Monday'
        end
     
        methods
            function this = set.day(this, d)
                WEEK_DAYS = {'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'};
                assert(ismember(d, WEEK_DAYS), ...
                    'DayExampleLegacy02:IllegalDay', ...
                    '"%" is not a valid week day.', d);
                this.day = d;
            end
        end
    end

    classdef DayExampleLegacy02 properties day@char = 'Monday' end methods function this = set.day(this, d) WEEK_DAYS = {'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'}; assert(ismember(d, WEEK_DAYS), ... 'DayExampleLegacy02:IllegalDay', ... '"%" is not a valid week day.', d); this.day = d; end end end

    • Yair Altman June 22, 2016 at 10:47 Reply

      @Chris – nice to see you here!

      Your report chimes with Martin’s comment above. The new syntax’s documented automatic type-casting can be replicated in the old (undocumented @) syntax using the property attribute:

      classdef DayExample
          properties
              day@WeekDay property = WeekDay.Monday
          end
      end

      classdef DayExample properties day@WeekDay property = WeekDay.Monday end end

      which allows setting the value as either an enumerated value or its char representation:

      >> d = DayExample
      d = 
        DayExample with properties:
       
          day: Monday
       
      >> d.day = WeekDay.Tuesday
      d = 
        DayExample with properties:
       
          day: Tuesday
       
      >> d.day = 'Thursday'
      d = 
        DayExample with properties:
       
          day: Thursday

      >> d = DayExample d = DayExample with properties: day: Monday >> d.day = WeekDay.Tuesday d = DayExample with properties: day: Tuesday >> d.day = 'Thursday' d = DayExample with properties: day: Thursday

  8. anonymous March 16, 2017 at 11:46 Reply

    Actually, Matlab has relased a new syntax to define property restrictions (Size, Class, Validation Functions):

    https://de.mathworks.com/help/matlab/matlab_oop/validate-property-values.html

  9. Kyle October 23, 2019 at 21:25 Reply

    I have serious issues with the new syntax actually. If you want to have abstract classes, the old method would work. The new method does not. For example the below 3 classes work with the old way, but the new way does not. Also sorry for the formatting. I couldn’t seem to indent and add spaces properly

    classdef Printer
        properties
           %graphicToPrint Graphic  % doesn't work
            graphicToPrint@Graphic
        end
        methods
            function print(this)
                % do some printing acting on graphicToPrint
                this.graphicToPrint.print();
            end
        end
    end
     
    classdef Graphic
        methods (Abstract)
            print(this);
        end
    end
     
    classdef ConcreteGraphic < Graphic
        methods
            function print(this)
                disp('print on ConcreteGraphic happened')
            end
        end
    end
     
    >> p = Printer;
    >> p.graphicToPrint = ConcreteGraphic;
    >> p.print
    print on ConcreteGraphic happened

    classdef Printer properties %graphicToPrint Graphic % doesn't work graphicToPrint@Graphic end methods function print(this) % do some printing acting on graphicToPrint this.graphicToPrint.print(); end end end classdef Graphic methods (Abstract) print(this); end end classdef ConcreteGraphic < Graphic methods function print(this) disp('print on ConcreteGraphic happened') end end end >> p = Printer; >> p.graphicToPrint = ConcreteGraphic; >> p.print print on ConcreteGraphic happened

    • Martin Lechner October 31, 2019 at 13:59 Reply

      Hi Kyle,

      I normally initialize the property with

      properties
          graphicToPrint Graphic = ConcreteGraphic.empty
      end

      properties graphicToPrint Graphic = ConcreteGraphic.empty end

      and have no problems with the new syntax.

Leave a Reply
HTML tags such as <b> or <i> are accepted.
Wrap code fragments inside <pre lang="matlab"> tags, like this:
<pre lang="matlab">
a = magic(3);
disp(sum(a))
</pre>
I reserve the right to edit/delete comments (read the site policies).
Not all comments will be answered. You can always email me (altmany at gmail) for private consulting.

Click here to cancel reply.

Useful links
  •  Email Yair Altman
  •  Subscribe to new posts (feed)
  •  Subscribe to new posts (reader)
  •  Subscribe to comments (feed)
 
Accelerating MATLAB Performance book
Recent Posts

Speeding-up builtin Matlab functions – part 3

Improving graphics interactivity

Interesting Matlab puzzle – analysis

Interesting Matlab puzzle

Undocumented plot marker types

Matlab toolstrip – part 9 (popup figures)

Matlab toolstrip – part 8 (galleries)

Matlab toolstrip – part 7 (selection controls)

Matlab toolstrip – part 6 (complex controls)

Matlab toolstrip – part 5 (icons)

Matlab toolstrip – part 4 (control customization)

Reverting axes controls in figure toolbar

Matlab toolstrip – part 3 (basic customization)

Matlab toolstrip – part 2 (ToolGroup App)

Matlab toolstrip – part 1

Categories
  • Desktop (45)
  • Figure window (59)
  • Guest bloggers (65)
  • GUI (165)
  • Handle graphics (84)
  • Hidden property (42)
  • Icons (15)
  • Java (174)
  • Listeners (22)
  • Memory (16)
  • Mex (13)
  • Presumed future risk (394)
    • High risk of breaking in future versions (100)
    • Low risk of breaking in future versions (160)
    • Medium risk of breaking in future versions (136)
  • Public presentation (6)
  • Semi-documented feature (10)
  • Semi-documented function (35)
  • Stock Matlab function (140)
  • Toolbox (10)
  • UI controls (52)
  • Uncategorized (13)
  • Undocumented feature (217)
  • Undocumented function (37)
Tags
ActiveX (6) AppDesigner (9) Callbacks (31) Compiler (10) Desktop (38) Donn Shull (10) Editor (8) Figure (19) FindJObj (27) GUI (141) GUIDE (8) Handle graphics (78) HG2 (34) Hidden property (51) HTML (26) Icons (9) Internal component (39) Java (178) JavaFrame (20) JIDE (19) JMI (8) Listener (17) Malcolm Lidierth (8) MCOS (11) Memory (13) Menubar (9) Mex (14) Optical illusion (11) Performance (78) Profiler (9) Pure Matlab (187) schema (7) schema.class (8) schema.prop (18) Semi-documented feature (6) Semi-documented function (33) Toolbar (14) Toolstrip (13) uicontrol (37) uifigure (8) UIInspect (12) uitools (20) Undocumented feature (187) Undocumented function (37) Undocumented property (20)
Recent Comments
  • Nicholas (4 days 9 hours ago): Hi Yair, Thanks for the reply. I am on Windows 10. I also forgot to mention that this all works wonderfully out of the editor. It only fails once compiled. So, yes, I have tried a...
  • Nicholas (4 days 9 hours ago): Hi Yair, Thanks for the reply. I am on Windows 10. I also forgot to mention that this all works wonderfully out of the editor. It only fails once compiled. So, yes, I have tried a...
  • Yair Altman (4 days 16 hours ago): Nicholas – yes, I used it in a compiled Windows app using R2022b (no update). You didn’t specify the Matlab code location that threw the error so I can’t help...
  • Nicholas (5 days 13 hours ago): Hi Yair, Have you attempted your displayWebPage utility (or the LightweightHelpPanel in general) within a compiled application? It appears to fail in apps derived from both R2022b...
  • João Neves (8 days 17 hours ago): I am on matlab 2021a, this still works: url = struct(struct(struct(struct(hF ig).Controller).PlatformHost). CEF).URL; but the html document is empty. Is there still a way to do...
  • Yair Altman (11 days 16 hours ago): Perhaps the class() function could assist you. Or maybe just wrap different access methods in a try-catch so that if one method fails you could access the data using another...
  • Jeroen Boschma (11 days 19 hours ago): Never mind, the new UI components have an HTML panel available. Works for me…
  • Alexandre (11 days 20 hours ago): Hi, Is there a way to test if data dictionnatry entry are signal, simulink parameters, variables … I need to access their value, but the access method depends on the data...
  • Nicholas (12 days 10 hours ago): In case anyone is looking for more info on the toolbar: I ran into some problems creating a toolbar with the lightweight panel. Previously, the Browser Panel had an addToolbar...
  • Jeroen Boschma (15 days 17 hours ago): I do not seem to get the scrollbars (horizontal…) working in Matlab 2020b. Snippets of init-code (all based on Yair’s snippets on this site) handles.text_explorer...
  • Yair Altman (43 days 19 hours ago): m_map is a mapping tool, not even created by MathWorks and not part of the basic Matlab system. I have no idea why you think that the customizations to the builtin bar function...
  • chengji chen (44 days 1 hour ago): Hi, I have tried the method, but it didn’t work. I plot figure by m_map toolbox, the xticklabel will add to the yticklabel at the left-down corner, so I want to move down...
  • Yair Altman (51 days 18 hours ago): @Alexander – this is correct. Matlab stopped including sqlite4java in R2021b (it was still included in 21a). You can download the open-source sqlite4java project from...
  • Alexander Eder (57 days 14 hours ago): Unfortunately Matlab stopped shipping sqlite4java starting with R2021(b?)
  • K (64 days 1 hour ago): Is there a way to programmatically manage which figure gets placed where? Let’s say I have 5 figures docked, and I split it into 2 x 1, I want to place 3 specific figures on the...
Contact us
Captcha image for Custom Contact Forms plugin. You must type the numbers shown in the image
Undocumented Matlab © 2009 - Yair Altman
This website and Octahedron Ltd. are not affiliated with The MathWorks Inc.; MATLAB® is a registered trademark of The MathWorks Inc.
Scroll to top