function fixedExponent = fixptbestexp( RealWorldValue, TotalBits, IsSigned )
%  FIXPTBESTEXP  Determine the exponent that gives the best precision
%            fixed point representation for a value.
%
% Usage:
%   fixedExponent = FIXPTBESTEXP( RealWorldValue, TotalBits, IsSigned )
% or
%   fixedExponent = FIXPTBESTEXP( RealWorldValue, FixPtDataType )
%
%  The best precision (power of 2) fixed point representation is based
%  on the formula
%     RealWorldValue = StoredInteger * 2^fixedExponent
%  where StoredInteger is an integer with a specified size and  
%  signed/unsigned status.
%
%  The negative of the fixed exponent specifies the number of bits to the
%  right of the binary point.
%
%  For example, 
%      fixptbestexp(4/3,16,1) 
%  or
%      fixptbestexp(4/3,sfix(16))
%  would return
%      -14
%  This says that if a signed sixteen bit number is used then the maximum 
%  precision representation of 
%      1.33333333333333 (base 10) 
%  is obtained by placing 14 bits to the right of the binary point.  The 
%  representation would be
%      01.01010101010101 (base 2)  =  21845 * 2^-14 
%                                  =  1.33331298828125 (base 10)
%  The precision of this representation would be specified in fixed point 
%  blocks by setting the scaling to 
%      2^-14
%  or
%      2^fixptbestexp(4/3,16,1)
%
%  See also SFIX, UFIX, FIXPTBESTPREC


% Copyright 1994-2012 The MathWorks, Inc.

if nargin < 2
    DAStudio.error('modelexplorer:numericType:fixptbest1');
elseif nargin < 3
    myDattypeSpecs = getdatatypespecs(TotalBits,1,0,0,1);    
    fixedExponent = fixed.GetBestPrecisionExponent(RealWorldValue, double(myDattypeSpecs.WordLength), ...
        double(myDattypeSpecs.Signed));
    
else
    fixedExponent = fixed.GetBestPrecisionExponent(RealWorldValue, double(TotalBits), double(IsSigned));
end    
