Documentation

Basic Knowledge

The material presented in this section builds on an understanding of the information presented in the following sections.

MATLAB Concatenation Rules

MATLAB^® follows these rules for concatenating objects:

When converting to a dominant class during concatenation or subscripted assignment, MATLAB searches the non-dominant class for a conversion method that is the same name as the dominant class. If such a conversion method exists, MATLAB calls it. If a conversion method does not exist, MATLAB calls the dominant class constructor on the non-dominant object.

It is possible for the dominant class to define horzcat, vertcat, or cat methods that modify the default concatenation process.

Concatenating Objects

Concatenation combines objects into arrays:

ary = [obj1,obj2,obj3,...,objn];

The size of ary is 1-by-n.

ary = [obj1;obj2;obj3;...;objn];

The size of ary is n-by-1.

The class of the arrays is the same as the class of the objects being concatenated. Concatenating objects of different classes is possible if MATLAB can convert objects to the dominant class. MATLAB attempts to convert unlike objects by:

If conversion of the inferior object is successful, MATLAB returns an array that is of the dominant class. If conversion is not possible, MATLAB returns an error.

Calling the Dominant-Class Constructor

MATLAB calls the dominant class constructor to convert an object of an inferior class to the dominant class. MATLAB passes the inferior object to the constructor as an argument. If the class design enables the dominant class constructor to accept objects of inferior classes as input arguments, then concatenation is possible without implementing a separate converter method.

If the constructor simply assigns this argument to a property, the result is an object of the dominant class with an object of an inferior class stored in a property. If this assignment is not a desired result, then ensure that class constructors include adequate error checking.

For example, consider the class ColorClass and two subclasses, RGBColor and HSVColor:

classdef ColorClass
   properties
      Color
   end
end

The class RGBColor inherits the Color property from ColorClass. RGBColor stores a color value defined as a three-element vector of red, green, and blue (RGB) values. The constructor does not restrict the value of the input argument. It assigns this value directly to the Color property.

classdef RGBColor < ColorClass
   methods
      function obj = RGBColor(rgb)
         if nargin > 0
            obj.Color = rgb;
         end
      end
   end
end

The class HSVColor also inherits the Color property from ColorClass. HSVColor stores a color value defined as a three-element vector of hue, saturation, brightness value (HSV) values.

classdef HSVColor < ColorClass
   methods
      function obj = HSVColor(hsv)
         if nargin > 0
            obj.Color = hsv;
         end
      end
   end
end

Create an instance of each class and concatenate them into an array. The RGBColor object is dominant because it is the leftmost object and neither class defines a dominance relationship:

crgb = RGBColor([1 0 0]);
chsv = HSVColor([0 1 1]);
ary = [crgb,chsv];
class(ary)

ans =

RGBColor

You can combine these objects into an array because MATLAB can pass the inferior object of class HSVColor to the constructor of the dominant class. However, notice that the Color property of the second RGBColor object in the array actually contains an HSVColor object, not an RGB color specification:

ary(2).Color

ans = 

  HSVColor with properties:

    Color: [0 1 1]

Avoid this undesirable behavior by:

Converter Methods

If your class design requires object conversion, implement converter methods for this purpose.

The ColorClass class defines converter methods for RGBColor and HSVColor objects:

classdef ColorClass
   properties
      Color
   end
   methods
      function rgbObj = RGBColor(obj)
         if isa(obj,'HSVColor')
            rgbObj = RGBColor(hsv2rgb(obj.Color));
         end
      end
      function hsvObj = HSVColor(obj)
         if isa(obj,'RGBColor')
            hsvObj = HSVColor(rgb2hsv(obj.Color));
         end
      end
   end
end

Create an array of RGBColor and HSVColor objects with the revised superclass:

crgb = RGBColor([1 0 0]);
chsv = HSVColor([0 1 1]);
ary = [crgb,chsv];
class(ary)

ans =

RGBColor

MATLAB calls the converter method for the HSVColor object, which it inherits from the superclass. The second array element is now an RGBColor object with an RGB color specification assigned to the Color property:

ary(2)

ans = 

  RGBColor with properties:

    Color: [1 0 0]

ary(2).Color

ans =

     1     0     0

If the leftmost object is of class HSVColor, the array ary is also of class HSVColor, and MATLAB converts the Color property data to HSV color specification.

ary = [chsv crgb]

ary = 

  1x2 HSVColor

  Properties:
    Color

ary(2).Color

ans =

     0     1     1

Defining a converter method in the superclass and adding better argument checking in the subclass constructors produces more predicable results. Here is the RGBColor class constructor with argument checking:

classdef RGBColor < ColorClass
   methods
      function obj = RGBColor(rgb)
         if nargin == 0
            rgb = [0 0 0];
         else
            if ~(isa(rgb,'double')...
                  && size(rgb,2) == 3 ...
                  && max(rgb) <= 1 && min(rgb) >= 0)
               error('Specify color as RGB values')
            end
         end
         obj.Color = rgb;
      end
   end
end

Your applications can require additional error checking and other coding techniques. The classes in these examples are designed only to demonstrate concepts.