{"id":1190,"date":"2017-12-22T17:53:00","date_gmt":"2017-12-22T22:53:00","guid":{"rendered":"https:\/\/blogs.mathworks.com\/developer\/?p=1190"},"modified":"2017-12-26T10:59:50","modified_gmt":"2017-12-26T15:59:50","slug":"property-validation","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/developer\/2017\/12\/22\/property-validation\/","title":{"rendered":"The Gift of Property Cheer"},"content":{"rendered":"

Well, it's that time of year, Christmas, Hanukkah, Kwanzaa, Ramadan, Winter Solstice, or you know.......Friday. You deserve the gift of a blog post. Here's a nugget of object oriented goodness in MATLAB, what better gift could there be?<\/p>

Well perhaps a quick follow up discussion on some more benefits of MATLAB object properties as we have discussed a couple<\/a> times<\/a> before. This time I'd like to focus on an awesome (and relatively new) feature that allows for much more streamlined validation of properties.<\/p>

First, a quick reminder, take a look at this special string class called FancyString<\/tt> that enables decorating individual elements it the string array with additional information such as hyperlinking or bolding. This starts with the FancyString<\/tt> itself:<\/p>

\r\nclassdef<\/span> FancyString \r\n    \r\n    properties<\/span>\r\n        PlainValue\r\n        \r\n        % Each element uses the \"do nothing\" decorator by default<\/span>\r\n        Decorator = DefaultDecorator; \r\n    end<\/span>\r\n    \r\n    properties<\/span>(Dependent)\r\n        DecoratedValue\r\n    end<\/span>\r\n    \r\n    \r\n    methods<\/span>\r\n        function<\/span> fancyString = FancyString(varargin)\r\n            if<\/span> nargin < 1\r\n                return<\/span>\r\n            end<\/span>\r\n                        \r\n            plainValue = string(varargin{:});\r\n            fancyString(numel(plainValue)) = FancyString;\r\n\r\n            plainValueCell = num2cell(plainValue);\r\n            [fancyString.PlainValue] = plainValueCell{:};\r\n        end<\/span>\r\n\r\n        function<\/span> decorated = get.DecoratedValue(fancyString)\r\n            % The decorated value returns whatever the decorator adds to<\/span>\r\n            % the plain string.<\/span>\r\n            decorated = fancyString.Decorator.decorate(fancyString.PlainValue);\r\n        end<\/span>\r\n        function<\/span> s = string(fancyString)\r\n            s = reshape([fancyString.PlainValue], size(fancyString));\r\n        end<\/span>\r\n    end<\/span>\r\nend<\/span>\r\n\r\n<\/pre>
As well as a couple decorators to add some fanciness:<\/p>
\r\nclassdef<\/span> DefaultDecorator\r\n    \r\n    methods<\/span>\r\n        function<\/span> decoratedString = decorate(~, undecoratedString)\r\n            decoratedString =  undecoratedString;\r\n        end<\/span>\r\n    end<\/span>       \r\n\r\nend<\/span>\r\n\r\n\r\n\r\nclassdef<\/span> HyperlinkDecorator\r\n   \r\n    properties<\/span>\r\n        LinkTarget\r\n    end<\/span>\r\n    \r\n    methods<\/span>\r\n        function<\/span> decorator = HyperlinkDecorator(linkTarget)\r\n            decorator.LinkTarget = linkTarget;\r\n        end<\/span>\r\n        function<\/span> decoratedString = decorate(decorator, undecoratedString)\r\n            decoratedString = \"<a href=\"\"\"<\/span> + decorator.LinkTarget + \"\"\">\"<\/span> + undecoratedString + \"<\/a>\"<\/span>;\r\n        end<\/span>\r\n    end<\/span>       \r\n    \r\n    \r\nend<\/span>\r\n\r\n\r\n\r\nclassdef<\/span> BoldDecorator\r\n      \r\n    methods<\/span>\r\n        function<\/span> decoratedString = decorate(~, undecoratedString)\r\n            decoratedString = \"<strong>\"<\/span> + undecoratedString + \"<\/strong>\"<\/span>;\r\n        end<\/span>\r\n    end<\/span>       \r\n    \r\n    \r\nend<\/span>\r\n\r\n<\/pre>
Now we can have a nice message with some bolding and hyperlinking holiday cheer:<\/p>
holidayMessage = [\"Happy\"<\/span> \"Holidays\"<\/span> \"!\"<\/span>];\r\n\r\ngreeting = FancyString(holidayMessage);\r\ngreeting(1).Decorator = BoldDecorator;\r\n\r\n% Add a link to US Holidays<\/span>\r\nholidayWikipediaSite = 'https:\/\/en.wikipedia.org\/wiki\/List_of_multinational_festivals_and_holidays#December'<\/span>;\r\ngreeting(2).Decorator = HyperlinkDecorator(holidayWikipediaSite);\r\n\r\njoin([greeting.DecoratedValue])\r\n<\/pre>
\r\nans = \r\n\r\n    \"Happy<\/strong> Holidays<\/a> !\"\r\n\r\n<\/pre>
Alright this is great, but there is a problem. Let's say we have an enumeration containing the different holidays and we'd like to put together a few different sets of greetings for our friends and neighbors with different preferences. Maybe this looks something like this:<\/p>
\r\nclassdef<\/span> Holidays\r\n    % Simple (and incomplete) enumeration of some winter holidays<\/span>\r\n    \r\n    enumeration<\/span>\r\n        Christmas\r\n        Hanukkah\r\n        Kwanzaa\r\n        Ramadan\r\n        WinterSolstice\r\n        NewYears\r\n    end<\/span>\r\nend<\/span>\r\n\r\n<\/pre>
That looks so nice I might just want to replace my string with one of these enumeration values. Seems reasonable.<\/p>
greeting(2).PlainValue = Holidays.Kwanzaa\r\n<\/pre>
\r\ngreeting = \r\n\r\n  1×3 FancyString array with properties:\r\n\r\n    PlainValue\r\n    Decorator\r\n    DecoratedValue\r\n\r\n<\/pre>
So far so good. Quick spot check?<\/p>
greeting.PlainValue\r\n<\/pre>
\r\nans = \r\n\r\n    \"Happy\"\r\n\r\n\r\nans = \r\n\r\n    Kwanzaa\r\n\r\n\r\nans = \r\n\r\n    \"!\"\r\n\r\n<\/pre>
Still looks good at first glance. Alright how about the DecoratedValue<\/tt>? Do the hyperlinking and bold operations still work? (hint: the try-catch<\/tt> I've added in the script I am using to publish this blog is a hint that something fishy might be going on):<\/p>
try<\/span>\r\n    greeting.DecoratedValue\r\ncatch<\/span> e\r\n    disp('Errored!'<\/span>);\r\n    disp(e.getReport('basic'<\/span>));\r\nend<\/span>\r\n<\/pre>
Errored!\r\nUndefined function 'plus' for input arguments of type 'Holidays'.\r\n<\/pre>
Alright this doesn't work because I've assigned to the PlainValue<\/tt> a value from our enumeration, but the FancyString<\/tt> (and the decorators) are expecting the value to be a string.<\/p>
In fact, we could have supplied any arbitrary value to the property and we likely wouldn't have noticed until much farther down the line. For example, let's add a structure, which is meaningless in this context:<\/p>
meaninglessStruct.SomeField = 5;\r\nmeaninglessStruct.AnotherField = true;\r\n\r\ngreeting(2).PlainValue = meaninglessStruct; % Assignment works!!<\/span>\r\ngreeting.PlainValue % Still doesn't error!<\/span>\r\n<\/pre>
\r\nans = \r\n\r\n    \"Happy\"\r\n\r\n\r\nans = \r\n\r\n  struct with fields:\r\n\r\n       SomeField: 5\r\n    AnotherField: 1\r\n\r\n\r\nans = \r\n\r\n    \"!\"\r\n\r\n<\/pre>
It only errors when we use it farther down the line, such as in concatenation:<\/p>
try<\/span>\r\n    [greeting.PlainValue]\r\ncatch<\/span> e\r\n    disp('Errored!'<\/span>);\r\n    disp(e.getReport('basic'<\/span>));\r\nend<\/span>\r\n<\/pre>
Errored!\r\nError using string\r\nConversion to string from struct is not possible.\r\n<\/pre>
This is clearly not optimal. Property validation to the rescue! We can make the simplest of tweaks to the FancyString<\/tt> so that we can always know for sure that the PlainValue<\/tt> property will always be a string. It's as easy as this slightly more fancy string implementation:<\/p>
\r\nclassdef<\/span> MoreFancyString \r\n    \r\n    properties<\/span>\r\n        \r\n        % Property validation for the win! Let's guarantee the PlainValue<\/span>\r\n        % is always a string<\/span>\r\n        PlainValue (1,1) string\r\n        \r\n        Decorator = DefaultDecorator; \r\n    end<\/span>\r\n    \r\n    properties<\/span>(Dependent)\r\n        DecoratedValue\r\n    end<\/span>\r\n    \r\n    \r\n    methods<\/span>\r\n        function<\/span> fancyString = MoreFancyString(varargin)\r\n            if<\/span> nargin < 1\r\n                return<\/span>\r\n            end<\/span>\r\n                        \r\n            plainValue = string(varargin{:});\r\n            fancyString(numel(plainValue)) = MoreFancyString;\r\n\r\n            plainValueCell = num2cell(plainValue);\r\n            [fancyString.PlainValue] = plainValueCell{:};\r\n        end<\/span>\r\n\r\n        function<\/span> decorated = get.DecoratedValue(fancyString)\r\n            % The decorated value returns whatever the decorator adds to<\/span>\r\n            % the plain string.<\/span>\r\n            decorated = fancyString.Decorator.decorate(fancyString.PlainValue);\r\n        end<\/span>\r\n        function<\/span> s = string(fancyString)\r\n            s = reshape([fancyString.PlainValue], size(fancyString));\r\n        end<\/span>\r\n    end<\/span>\r\nend<\/span>\r\n\r\n<\/pre>
The only difference here is in the property block where plain value was defined:<\/p>
PlainValue (1,1) string<\/tt><\/p>
This states that the PlainValue<\/tt> must always be a scalar string, which gives us much more peace of mind as we process that code. How does it work now?<\/p>
greeting = MoreFancyString(holidayMessage);\r\ngreeting(1).Decorator = BoldDecorator;\r\ngreeting(2).Decorator = HyperlinkDecorator(holidayWikipediaSite);\r\ngreeting(2).PlainValue = Holidays.Kwanzaa\r\n<\/pre>
\r\ngreeting = \r\n\r\n  1×3 MoreFancyString array with properties:\r\n\r\n    PlainValue\r\n    Decorator\r\n    DecoratedValue\r\n\r\n<\/pre>
This time if you look closely you will see the enum was converted to a string<\/p>
greeting(2).PlainValue\r\n<\/pre>
\r\nans = \r\n\r\n    \"Kwanzaa\"\r\n\r\n<\/pre>
...and because of that everything else like concatenation and the string decoration works as expected:<\/p>
join([greeting.PlainValue])\r\n\r\njoin([greeting.DecoratedValue])\r\n<\/pre>
\r\nans = \r\n\r\n    \"Happy Kwanzaa !\"\r\n\r\n\r\nans = \r\n\r\n    \"Happy<\/strong> Kwanzaa<\/a> !\"\r\n\r\n<\/pre>
It also correctly errors right away with bunk values that don't know how to be represented as strings:<\/p>
try<\/span>\r\n    greeting(2).PlainValue = meaninglessStruct;\r\ncatch<\/span> e\r\n    disp('Errored!'<\/span>);\r\n    disp(e.getReport('basic'<\/span>));\r\nend<\/span>\r\n<\/pre>
Errored!\r\nError using y2017PropertyTypes (line 138)\r\nError setting property 'PlainValue' of class 'MoreFancyString':\r\nInvalid data type. Value must be string or be convertible to string.\r\n<\/pre>
Awesome! A couple concluding thoughts:<\/p>
  1. We could have also given this guarantee by implementing a set.PlainValue<\/tt> method that validates the input using the validateattributes<\/tt> or otherwise. This would be certainly possible, and a benefit of encapsulated properties. However, if this validation is all that is needed property validators are much more convenient and accessible.<\/li>
  2. Classes that are convertible to the datatype specified (in this case string<\/tt>) are automatically converted. In this case the enumeration really knows how to be interpreted correctly as a string, and so it just intuitively worked out of the box!<\/li>
  3. This conversion has a flipside. What this really provides is a guarantee that the actual stored value will be a string<\/tt>. However,you can set non-string values to this property as long as they are convertible to a string, and the conversion will be performed upon setting the property. This is typically the right behavior, since the value with a type conversion is the class that should be able to decide that it can be interpeted as a string. However, if you find that you wish to disallow any datatype from being assigned to the property unless it is the precise type to start with, then you may need to leverage the setter method instead to enforce that restriction directly.<\/li><\/ol><\/div>
    Have you used the new property validation features? I hope so. Actually there is much more richness to property validation than I've shown here, check out the documentation<\/a>. I've hinted at size\/shape validation but there is also the ability to pass validation functons to the value being set, as well as a rich library of validation functions<\/a> in MATLAB for your benefit. Let us know what you think!....oh, and<\/p>
    holidays = enumeration('Holidays'<\/span>);\r\nfor<\/span> idx = 1:numel(holidays)\r\n    greeting(2).PlainValue = holidays(idx);\r\n    if<\/span> strcmp(holidays(idx), 'Christmas'<\/span>) % There's always a special case<\/span>\r\n        specialGreeting = greeting;\r\n        specialGreeting(1).PlainValue = \"Merry\"<\/span>;\r\n        disp(join([specialGreeting.DecoratedValue]));\r\n        continue<\/span>;\r\n    end<\/span>\r\n    disp(join([greeting.DecoratedValue]));\r\nend<\/span>\r\n<\/pre>
    \r\n\r\nMerry<\/strong> Christmas<\/a> !\r\nHappy<\/strong> Hanukkah<\/a> !\r\nHappy<\/strong> Kwanzaa<\/a> !\r\nHappy<\/strong> Ramadan<\/a> !\r\nHappy<\/strong> WinterSolstice<\/a> !\r\nHappy<\/strong> NewYears<\/a> !\r\n<\/pre>
    \"\" <\/p>