annotate chordtools/checkomissions.m @ 1:8973548174c1 tip

adding tools to repo

%
% CHECKOMISSIONS
% 
% [success, errormessage] = checkomissions(shortints, intervals, {verbose})
% 
% Checks that any omitted intervals are actually present in the interval
% list that makes up a shorthand definition. For example C:maj(*4) is an
% incorrect chord because the shorthand does not contain interval 4 so
% there is no reason to omit it.
%
% Arguments 'shortints' and 'intervals' should either be interval lists
% (characters) or arrays of [degree, modifier, present] triples of the type
% produced by the function 'parseintervals'.
% 
% Success = 1 if the interval list does not contain an omitted interval
% that is not present in the shorthand list.
% 
% If optional argument 'verbose' is 1, function prints any errormessage to 
% the screen.
% 
% returns:  success (boolean)
%           errormessage (string)
%
%
% Author: Christopher Harte, December 2009
% 
% Copyright: Centre for Digital Music, Queen Mary University of London 2005 
%
% This file is part of the C4DM Chord Toolkit V2.0  
%
% The C4DM Chord Toolkit is free software; you can redistribute it and/or 
% modify it under the terms of the GNU General Public License as published 
% by the Free Software Foundation; either version 2 of the License, or
% (at your option) any later version.
%
% The C4DM Chord Toolkit is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with the C4DM Toolkit; if not, write to the Free Software
% Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
% USA

function [success, errormessage] = checkomissions(shortints,intervals,verbose)

if nargin < 3
    verbose = 0;
end

errormessage = '';

success = 1;

% if 'shortints' is a character string interval list, convert it to
% [degree,modifier,present] triples
if ischar(shortints)
    [shortints,success,errormessage] = parseintervals(shortints);
end

% if 'intervals' is a character string interval list, convert it to
% [degree,modifier,present] triples
if success && ischar(intervals)
    [intervals, success, errormessage] = parseintervals(intervals);
end

% if everything is ok so far, check any omissions
if success 

    [sizey,sizex] = size(intervals);
    [sizey2,sizex2] = size(shortints);

    success = 1;

    % for each interval in the intervals list
    for indexa = 1:sizey

        % if it is an omitted interval
        if intervals(indexa,3) == 0

            % check that the shorthand list contains that interval to omit
            success = 0;

            for indexb = 1:sizey2

                if shortints(indexb,1:2) == intervals(indexa,1:2)
                    % if the omitted interval is found in the shorthand
                    % list then the omission is valid
                    success = 1;
                end
            end
        end 
    end
end 

    
% if there was an error, format the error message appropriately:
if success == 0
        if isempty(errormessage)
            errormessage = sprintf(['Error in checkommisions: ommitted interval not present in shorthand. \n']);
        else
            errormessage = [sprintf(['Error in checkommisions: badly formatted argument \n']) errormessage];
        end
        
        if verbose == 1
            fprintf(1,errormessage);
        end

end