out=check_value(truth_value, test_value, tol)

function out=check_value(truth_value, test_value, tol)
% CHECK_VALUE compares a truth value against a test value.
%     CHECK_VALUE(truth_value, test_value)
%     Both inputs are strings, and a nice "unit test" type pass/fail
%     text will be output to the screen.  All input strings are evaluated
%     in the base workspace.  Comparisions are considered "equal" if the
%     difference is less than 2*EPS.
%
%     With a third argument, CHECK_VALUE(truth_value, test_value, TOL)
%     comparisions are considered "equal" if the difference is less than
%     TOL.
%
% See also EPS.

% $Source: /home/stpierre/cvsroot/matlab/tools/test_tools/check_value.m,v $
% $Revision: 1.5 $
% $Date: 2009-07-26 21:33:13 $

% Copyright (c) 2000-2009, Jay A. St. Pierre.  All rights reserved.

if nargin<2
  error('check_value() requires two input arguments')
elseif ~ischar(truth_value)
  error('truth_value must be a string (it will be evaluated internally)')
elseif ~ischar(test_value)
  error('test_value must be a string (it will be evaluated internally)')
end

if nargin==2
  tol=2*eps;
else
  if max(size(tol))~=1
    error('TOL must be a scalar value')
  end
  tol=abs(tol);
end

% Evaluate test and truth values
l_test_value  = evalin('base', test_value);
l_truth_value = evalin('base', truth_value);

% Calculate difference between truth and test values
test_truth_diff = l_test_value - l_truth_value;
max_diff=max(max(abs(test_truth_diff)));

% Are we checking floats or ints?
if max_diff~=0
  isfloat=1;
  disp(['Comparsion tolerance: ', num2str(tol)])
else
  isfloat=0;
end

if (max_diff<=tol)
  disp([test_value, ' == ', truth_value, '   ***PASSED***'])
  if isfloat
    disp(['(maximum difference: ', num2str(max_diff), ')'])
  end
  disp(' ')
  out=0;
else
  disp([test_value, ' ~= ', truth_value, '   ***FAILED***'])
  disp(' ')
  disp_value(test_value, 'base')
  disp(' ')
  disp_value(truth_value, 'base')
  disp(' ')
  if isfloat
    disp_value('test_truth_diff', 'caller')
    disp(' ')
  end
  out=1;
end