unit(stru)

function [this,privateHandle] = unit(stru)
% [this,privateHandle] = unit(stru)
%
% UNIT is the parent function for all the unit classes (i.e. m, mm, kg, sec,..)
% and the key class for UNITS CONVERSION OPERATIONS
%
% The direct instantiation of UNIT objects is deprecated. It should only be
% used used its children at instantiation.
%
% For instance, the class 'mm' is a child of UNIT and it will instantiate it 
% as a parent at its own instantiation.
%
% type POSSIBLE(UNIT) to see a list of all available units
%
% Examples:
%
%    typing in the command window:
%              mm
%
%    will display:
%              mm = 0.001000
%
% It is possible to create composite units, like:
%
%              kg/mm^3
%              kg/(mm^3) = 1000000000.000000
% 
% in this case the class returned variable is 'COMPOSITEUNIT'
%
%  or:
%              kg*m/sec^2
%              kg*m/(sec^2) = 1.000000
%
%
% Multiplication or division of a number (scalar or matrix) by a unit
% object (in any order) returns a double (scalar or matrix) resulting from 
% multiplying the matrix by the value associated with the unit object.
%    THIS IS IN FACT A UNITS CONVERSION OPERATION
%
% to display the value associated with the unit object use the function
% DOUBLE
%
% Example:
%
%   double(mm)
%
%   ans =
%
%     1.0000e-003
%
%
% see also:
% getName   possible   update  unit/double   private/unitsList


if nargin < 1
      this = class(makeEmptyStruct,'unit');
   else
      if isa(stru,'unit')
         this = stru;
      elseif ischar(stru)
         this = setUnit(unit,stru);
      else
         error('unexpected input type for ''unit'' class')
      end
   end
   
   % Create an handle to ''setComposite'' so that it can be called by
   % friends classes of the unit class
   privateHandle = @makeComposite;
end

% -----------------------------------------
function stru = makeEmptyStruct
   stru.name  = '-';
   stru.value = 1;
end

% -----------------------------------------
function this = makeComposite(this,callingObj,unitName,unitValue)
   if isFriend(callingObj)
      this = setComposite(this,unitName,unitValue);
   else
      error(['setComposite is a protected function, available to' ...
             'objects of ''unit'', ''compositeUnit''  and ''noUnit'' types'])
   end
end