progress_msg

PROGRESS_MSG Progress messages and timing.
 
 PROGRESS_MSG('msg',I,N,opt) where I = 0 or -1 initilises the messages. 
   'msg'   [optional] string to print
   I       [optional] if I=0 initialises and prints '0%', '0/N', or '0'
                      if I=-1 suppresses the initial progress message and
                      ignores options of the immediately following 
                      initialisation message                      
   N       [optional] if N=0 prints 'I', if N>0 prints 'I/N' 
                      if absent, prints 'I%' (default)
   opt     [optional] structure with the following fields and defaults:
      .log_level = 2        controls verbosity, see EIDORD_MSG for details
      .final_msg            customises the text of the final message
                   'Done'   default
                   ''       last message will not be erased, but time will
                            be printed
                   'none'   completely suppress the final message
      .num_digits = 6       controls the text field width for N=0

 PROGRESS_MSG(I) displays I%
 PROGRESS_MSG(I,N) displays I/N
 PROGRESS_MSG(I,0) displays I

 PROGRESS_MSG(Inf) prints the final message, including the time elapsed
  since initialisation, measured using tic/toc.
 PROGRESS_MSG('msg',Inf) prints the 'msg' instead of the opt.final_msg

 Example:
   progress_msg('The big loop:', 0,10);         % prints 0/10
   for i = 1:10
       progress_msg(i,10);     % e.g.   3/10
       pause(.2); % think
   end
   progress_msg(Inf)           % final message, e.g. Done (2.015 s)

   opt.final_msg = 'none'                   % suppress final message 
   progress_msg('Start calculations...',-1);% suppress next initialisation
   res = function_using_progress_msg;
   progress_msg(sprintf('Size is %d',numel(res)), Inf);

 SEE ALSO EIDORS_MSG, TIC, TOC

0001 function progress_msg(varargin)
0002 %PROGRESS_MSG Progress messages and timing.
0003 %
0004 % PROGRESS_MSG('msg',I,N,opt) where I = 0 or -1 initilises the messages.
0005 %   'msg'   [optional] string to print
0006 %   I       [optional] if I=0 initialises and prints '0%', '0/N', or '0'
0007 %                      if I=-1 suppresses the initial progress message and
0008 %                      ignores options of the immediately following
0009 %                      initialisation message
0010 %   N       [optional] if N=0 prints 'I', if N>0 prints 'I/N'
0011 %                      if absent, prints 'I%' (default)
0012 %   opt     [optional] structure with the following fields and defaults:
0013 %      .log_level = 2        controls verbosity, see EIDORD_MSG for details
0014 %      .final_msg            customises the text of the final message
0015 %                   'Done'   default
0016 %                   ''       last message will not be erased, but time will
0017 %                            be printed
0018 %                   'none'   completely suppress the final message
0019 %      .num_digits = 6       controls the text field width for N=0
0020 %
0021 % PROGRESS_MSG(I) displays I%
0022 % PROGRESS_MSG(I,N) displays I/N
0023 % PROGRESS_MSG(I,0) displays I
0024 %
0025 % PROGRESS_MSG(Inf) prints the final message, including the time elapsed
0026 %  since initialisation, measured using tic/toc.
0027 % PROGRESS_MSG('msg',Inf) prints the 'msg' instead of the opt.final_msg
0028 %
0029 % Example:
0030 %   progress_msg('The big loop:', 0,10);         % prints 0/10
0031 %   for i = 1:10
0032 %       progress_msg(i,10);     % e.g.   3/10
0033 %       pause(.2); % think
0034 %   end
0035 %   progress_msg(Inf)           % final message, e.g. Done (2.015 s)
0036 %
0037 %   opt.final_msg = 'none'                   % suppress final message
0038 %   progress_msg('Start calculations...',-1);% suppress next initialisation
0039 %   res = function_using_progress_msg;
0040 %   progress_msg(sprintf('Size is %d',numel(res)), Inf);
0041 %
0042 % SEE ALSO EIDORS_MSG, TIC, TOC
0043 
0044 % (C) 2015 Bartlomiej Grychtol - all rights reserved Swisstom AG
0045 % License: GPL version 2 or 3
0046 % $Id: progress_msg.m 5321 2017-02-13 16:02:54Z bgrychtol $
0047 
0048 % >> SWISSTOM CONTRIBUTION <<
0049 
0050 t0 = tic;
0051 
0052 if nargin > 0 && ischar(varargin{1}) && strcmp(varargin{1},'UNIT_TEST')
0053     varargin(1) = [];
0054     do_unit_test(varargin{:});
0055     return
0056 end
0057 
0058 persistent pvar;
0059 
0060 nargs = nargin;
0061 opt = default_opts;
0062 if nargs > 0 && isstruct(varargin{end})
0063     tmp = varargin{end};
0064     try
0065         if tmp.log_level > eidors_msg('log_level')
0066             return % don't even process options
0067         end
0068     end
0069     fld = fieldnames(tmp);
0070     for i = 1:numel(fld)
0071         opt.(fld{i}) = tmp.(fld{i});
0072     end
0073     nargs = nargs-1;
0074     varargin(end) = [];
0075 end
0076 
0077 
0078 msg = '';
0079 if nargs > 0 && ischar(varargin{1})
0080     if nargs > 1 && isinf(varargin{2})
0081         msg = varargin{1}; % custom final message from function call
0082     else
0083         msg = [repmat(' ',1,opt.log_level) datestr(now) ': ' varargin{1}]; % Fixed text
0084     end
0085     nargs = nargs-1;
0086     varargin(1) = [];
0087 end
0088 
0089 
0090 if nargs == 0 % there was only a message
0091     nargs = 1;
0092     varargin(1) = {0}; % starting number
0093 end
0094 
0095 first_msg = false;
0096 ignore = false;
0097 try 
0098     ignore = pvar.ignore_next;
0099 end
0100 
0101 if nargs == 0 || varargin{1} <=0 || isempty(pvar)
0102     first_msg = true;
0103     if ~ignore
0104         pvar.log_level = opt.log_level;
0105     end
0106     if pvar.log_level > eidors_msg('log_level');
0107         return
0108     end
0109     if ~ignore
0110         pvar.final_msg = opt.final_msg;
0111     end
0112     if varargin{1} < 0
0113         pvar.ignore_next = true;
0114     else
0115         pvar.ignore_next = false;
0116     end
0117     pvar.timerVal = tic;
0118     pvar.own_time = 0;
0119     if nargs <= 1
0120         pvar.nChars = 4;
0121     elseif varargin{2} == 0
0122         pvar.nChars = opt.num_digits;
0123     else
0124         pvar.numLength = floor(log10(varargin{2})) + 1;
0125         pvar.nChars = 2 * pvar.numLength + 1;
0126     end
0127 end
0128 
0129 if pvar.log_level > eidors_msg('log_level');
0130     return
0131 end
0132 
0133 if ~isempty(msg) && ~isinf(varargin{1}) && ~(first_msg && ignore);
0134     fprintf('%s ',msg);
0135 end
0136 
0137 if nargs > 0 && isinf(varargin{1})
0138     if isempty(msg)
0139         msg = pvar.final_msg;
0140         if strcmp(msg,'none')
0141            return
0142         end
0143     end
0144     print_final_msg(msg, pvar.nChars);
0145     print_time(pvar);
0146     if eidors_debug('query','progress_msg')
0147         fprintf('Self-time: %f\n',pvar.own_time);
0148     end
0149     return
0150 end
0151     
0152 
0153 if nargs == 1
0154     percentmsg(varargin{1},first_msg, pvar.nChars);
0155 elseif varargin{2} > 0
0156     outofmsg(varargin{1},varargin{2},first_msg,...
0157         pvar.numLength, pvar.nChars);
0158 else
0159     numbermsg(varargin{1},first_msg, pvar.nChars);
0160 end
0161 
0162 pvar.own_time = pvar.own_time + toc(t0);
0163 
0164 end
0165 
0166 
0167 function percentmsg(num, first, N)
0168     if first && num < 0, return, end
0169     str = '%3d%%';
0170     if ~first
0171         str = [repmat('\b',1,N) str ];
0172     end
0173     fprintf(str, round(100*num));
0174 end
0175 
0176 function outofmsg(a,b,first,N,T)
0177     if first && a < 0, return, end
0178     str = sprintf('%%%dd/%%%dd',N,N);
0179     if ~first
0180         str = [repmat('\b',1,T) str ];
0181     end
0182     
0183     fprintf(str,a,b);
0184 end
0185 
0186 function numbermsg(num, first, T)
0187     if first && num < 0, return, end
0188     str = sprintf('%%%dd',T);
0189     if ~first
0190         str = [repmat('\b',1,T) str];
0191     end
0192     fprintf(str, num);
0193             
0194 end
0195 
0196 function print_final_msg(msg, N)
0197     if isempty(msg) , return, end
0198     str = [repmat('\b',1,N) '%s'];
0199     fprintf(str, msg);
0200 end
0201 
0202 function print_time(pvar)
0203     fprintf(' (%.3f s)\n',...
0204         toc(pvar.timerVal) -  pvar.own_time);
0205 end
0206 
0207 function opt = default_opts
0208     opt.final_msg = 'Done';
0209     opt.log_level = 2;
0210     opt.num_digits = 6;
0211 end
0212 
0213 function do_unit_test(N)
0214     eidors_msg('log_level',2);
0215     eidors_debug on progress_msg
0216     if nargin == 0
0217         N = 1:35;
0218     end
0219     for n = N
0220         switch n
0221             case 1
0222                 progress_msg(0);
0223 
0224             case 2
0225                 progress_msg('Test 2',0);
0226             case 3
0227                 progress_msg('Test 3');
0228             case 4
0229                 progress_msg
0230             case 5
0231                 opt.final_msg = 'YUPPIE!';
0232                 progress_msg(opt);
0233             case 6
0234                 progress_msg('Test 6', opt);
0235             case 10
0236                 progress_msg('Test 10',0,10);
0237             case 11
0238                 progress_msg(0,10);
0239             case 20
0240                 opt.final_msg = 'Ready !!!';
0241                 progress_msg('Test 20', 0,10,opt);
0242             case 21
0243                 eidors_msg('log_level',1);
0244                 progress_msg('Test 21', 0,10,opt);
0245             case 22
0246                 opt.log_level = 1;
0247                 progress_msg('Test 22', 0,10,opt);
0248             case 23
0249                 opt.log_level = 4;
0250                 eidors_msg('log_level',5);
0251                 progress_msg('Test 23', 0,10,opt);
0252             case 24
0253                 eidors_msg('log_level',2);
0254                 progress_msg('Test 24', 0,10);
0255             case 30
0256                 progress_msg('Test 30',0,0)
0257             otherwise
0258                 continue
0259         end 
0260         if n < 10
0261             for i = 1:10
0262                 pause(.2);
0263                 progress_msg(i/10);
0264             end
0265         elseif n >= 30
0266             for i = 1:10
0267                 pause(.2);
0268                 progress_msg(i^4,0);
0269             end
0270         else
0271             for i = 1:10
0272                 pause(.2);
0273                 progress_msg(i,10);
0274             end
0275         end
0276         if n == 2
0277            progress_msg('Custom final message', Inf);
0278         else
0279            progress_msg(Inf);
0280         end
0281 
0282     end
0283     eidors_debug off progress_msg
0284 end