Function mssg(messagelevels, template, ...)
mssg(messagelevels, margins, template, ...)
mssg(messagelevelcode, template, ...)
mssg(messagelevelcode, margins, template, ...)
mssg("-filename", filenames)
mssg("-filename", filenames, keepopen)
mssg("-close")
mssg("-levels", levelcodestruct)
mssg("-verbositylevel", verbositylevels)
mssg("-margins", margins)
mssg("-setcounterarray", counters)
counters = mssg("-getcounterarray")
mssg("-resetcounters")
n = mssg("-getcounters", levels)
n = mssg("-getcounters", levelcodes)
mssg("-setstate", statestruct)
statestruct = mssg("-getstate")
mssg("-defaults")
prints a message formated by sprintf(template, ...)
to a stream i (i.e. the screen or a text file), if the
corresponding messagelevel(i) <= verbositylevel(i).
Variables messagelevel and verbositylevel are internal
variables. They are manipulated and set via input
variables messagelevels, verbositylevel and others.
The streams are defined by input variable filenames. It
consists of a a cell array with one row and N columns,
i.e. for N streams. Use filenames{1,i}='-screen' for
printing to the screen, and filenames{1,i}='myfile.txt'
for printing to text file "myfile.txt". The default
definition of the variable is filenames{1,1}='-screen'.
With mssg("-filename", filenames) each text file is
opened for writing (i.e. appending). If input variable
keepopen is set to one, all text file streams are
kept open; otherwise, they are reopened for appending
and imediately closed, at each call with
mssg(..., template, ...). The default value of
keepopen is zero.
All text file streams are closed with mssg("-close").
Do not forget issuing this, if keepopen has been
set to one!
If input variable messagelevels consists of N integers,
and if N streams have been defined, then internal
variable messagelevel is set to row vector
[messagelevels]. If input variable messagelevels does
not consist of N integers, then internal variable
messagelevel is set to row vector
[messagelevels(1)*ones(1,N)].
Input variable messagelevelcode consists of one string
(of characters). With this input, internal variable
messagelevel is set to row vector
[levelcodestruct.(messagelevelcode)*ones(1,N)]. If
messagelevelcode is not an existing field in
levelcodestruct, messagelevel is set to row vector
[ones(1,N)].
Variable levelcodestruct is a struct of which each
member contains one integer (> 0). The struct thus
"returns" a message level (integer) for a given level
code (string). The defaults are given below.
If input variable verbositylevels consists of N
integers, and if N streams have been defined, then
internal variable verbositylevel is set to row vector
[verbositylevels]. If input variable verbositylevels
does not consist of N integers, then internal variable
verbositylevel is set to row vector
[verbositylevels(1)*ones(1,N)].
Input variable margins must be a cell array of one
row and three columns, and the cells consist of
strings which are to be added before the message, at
the beginning of the template and after the message,
respectively. The result is equivalent to:
fprintf(fid,margins{1,1});
fprintf(fid,[margins{1,2} template], ...);
fprintf(fid,margins{1,3});
E.g. when the number of arguments after (!) the
template is >1 times the number of arguments within (!)
the template, the result of:
mssg(...,{"a","b","c"},"%d,%d,%d",1,2,3,4,5,6)
is:
"ab1,2,3b4,5,6c"
In/output variable counters is a row vector, for
which counters(k) is the number of times the message
level k is issued by calls of mssg(..., template, ...).
With mssg("-resetcounters"), the counters are set to
zero.
With mssg("-getcounters", ...), a row vector with a
selection of counters is returned. Input variable
levels is a row vector or a row cell array of integers
indicating each a message level; input variable
levelcodes is a row cell array of strings indicating
a message level code. If a level code has not been
defined, zero is returned!
In/output variable statestruct is a struct containing
all (internal) settings and thus the (actual) state.
With mssg("-defaults"), all the internal settings are
reset to the defaults. When mssg(...) is called for the
first time, the default settings are set automatically.
The defaults consist a default value for levelcodestruct,
with the following level codes, levels and meanings:
levelcode level meaning
--------- ----- ---------------------------------------
"err" 1 error message
"war" 2 warning message,
"hvy" 3 information about time consuming calculations
"imp" 4 important information
"lst" 5 less important information
"dbg" 6 debugging information
(c) 2026 fabien van mook
2026.08.20 release of this file within package "fvm-miscellaneous" under GNU GPLv3+
