Next: Enabling and Disabling Warnings, Up: Handling Warnings [Contents][Index]
It is possible to issue warnings from any code using the warning
function. In its most simple form, the warning
function takes a
string describing the warning as its input argument. As an example,
the following code controls if the variable ‘a’ is non-negative,
and if not issues a warning and sets ‘a’ to zero.
a = -1; if (a < 0) warning ("'a' must be non-negative. Setting 'a' to zero."); a = 0; endif -| 'a' must be non-negative. Setting 'a' to zero.
Since warnings aren’t fatal to a running program, it is not possible
to catch a warning using the try
statement or something similar.
It is however possible to access the last warning as a string using the
lastwarn
function.
It is also possible to assign an identification string to a warning.
If a warning has such an ID the user can enable and disable this warning
as will be described in the next section. To assign an ID to a warning,
simply call warning
with two string arguments, where the first
is the identification string, and the second is the actual warning. Note
that warning IDs are in the format "NAMESPACE:WARNING-NAME"
. The
namespace "Octave"
is used for Octave’s own warnings. Any other string
is available as a namespace for user’s own warnings.
Display a warning message or control the behavior of Octave’s warning system.
The first call form uses a template template and optional additional
arguments to display a message on the stderr
stream. The message is
formatted using the same rules as the printf
family of functions
(see Formatted Output) and prefixed by the character string
‘warning: ’. You should use this function when you want to notify the
user of an unusual condition, but only when it makes sense for your program to
go on. For example:
warning ("foo: maybe something wrong here");
If the warning message does not end with a newline character, Octave will
print a traceback of all the function calls leading to the warning. If the
warning message does end in a newline character, Octave will suppress the
traceback messages as it returns control to the top level. For more details
and examples, see error
.
The optional warning identifier id allows users to enable or disable
warnings tagged by this identifier. A message identifier is a string of the
form "NAMESPACE:WARNING-NAME"
. Octave’s own warnings use the
"Octave"
namespace (see warning_ids
). For
example:
warning ("MyNameSpace:check-something", "foo: maybe something wrong here");
The second call form is meant to change and/or query the state of warnings.
The first input argument must be a string state ("on"
,
"off"
, "error"
, or "query"
) followed by an optional
warning identifier id or "all"
(default).
The optional output argument warning_struct is a structure or structure
array with fields "state"
and "identifier"
. The state
argument may have the following values:
"on"
|"off"
:Enable or disable the display of warnings identified by id and optionally return their previous state stout.
"error"
:Turn warnings identified by id into errors and optionally return their previous state stout.
"query"
:Return the current state of warnings identified by id.
A structure or structure array warning_struct, with fields
"state"
and "identifier"
, may be given as an input to achieve
equivalent results. The following example shows how to temporarily disable a
warning and then restore its original state:
loglog (-1:10); ## Disable the previous warning and save its original state [~, id] = lastwarn (); warnstate = warning ("off", id); loglog (-1:10); ## Restore its original state warning (warnstate);
If a final argument "local"
is provided then the warning state will be
set temporarily until the end of the current function. Changes to warning
states that are set locally affect the current function and all functions
called from the current scope. The previous warning state is restored on
return from the current function. The "local"
option is ignored if
used in the top-level workspace.
With no input argument warning ()
is equivalent to
warning ("query", "all")
except that in the absence of an output
argument, the state of warnings is displayed on stderr
.
The level of verbosity of the warning system may also be controlled by two modes mode:
"backtrace"
:enable/disable the display of the stack trace after the warning message
"verbose"
:enable/disable the display of additional information after the warning message
In this case the state argument may only be "on"
or
"off"
.
Implementation Note: For compatibility with MATLAB, escape sequences in
template (e.g., "\n"
=> newline) are processed
regardless of whether template has been defined with single quotes, as
long as there are two or more input arguments. To disable escape sequence
expansion use a second backslash before the sequence (e.g.,
"\\n"
) or use the
regexptranslate
function.
See also: warning_ids, lastwarn, error.
Query or set the last warning message.
When called without input arguments, return the last warning message and message identifier.
With one argument, set the last warning message to msg.
With two arguments, also set the last message identifier.
The functions distributed with Octave can issue one of the following warnings.
Octave:abbreviated-property-match
If the Octave:abbreviated-property-match
warning is enabled, a
warning is printed if a non-exact or ambiguous match is being used for a
operation specifying an object property. For example, for a graphics
object, fig, with the property 'displayname'
,
get (fig, 'dis')
elicits a warning if the
Octave:abbreviated-property-match
warning is enabled.
By default, the Octave:abbreviated-property-match
warning is enabled.
Octave:addpath-pkg
If the Octave:addpath-pkg
warning is enabled,
Octave will warn when a package directory (i.e., +package_name) is added
to the path
. Typically, only the parent directory which contains the
package directory should be added to the load path.
By default, the Octave:addpath-pkg
warning is enabled.
Octave:array-as-logical
If the Octave:array-as-logical
warning is enabled,
Octave will warn when an array of size greater than 1x1 is used
as a truth value in an if, while, or until statement.
By default, the Octave:array-as-logical
warning is disabled.
Octave:array-to-scalar
If the Octave:array-to-scalar
warning is enabled, Octave will
warn when an implicit conversion from an array to a scalar value is
attempted.
By default, the Octave:array-to-scalar
warning is disabled.
Octave:array-to-vector
If the Octave:array-to-vector
warning is enabled, Octave will
warn when an implicit conversion from an array to a vector value is
attempted.
By default, the Octave:array-to-vector
warning is disabled.
Octave:assign-as-truth-value
If the Octave:assign-as-truth-value
warning is
enabled, a warning is issued for statements like
if (s = t) …
since such statements are not common, and it is likely that the intent was to write
if (s == t) …
instead.
There are times when it is useful to write code that contains
assignments within the condition of a while
or if
statement. For example, statements like
while (c = getc ()) …
are common in C programming.
It is possible to avoid all warnings about such statements by
disabling the Octave:assign-as-truth-value
warning,
but that may also let real errors like
if (x = 1) # intended to test (x == 1)! …
slip by.
In such cases, it is possible suppress errors for specific statements by writing them with an extra set of parentheses. For example, writing the previous example as
while ((c = getc ())) …
will prevent the warning from being printed for this statement, while allowing Octave to warn about other assignments used in conditional contexts.
By default, the Octave:assign-as-truth-value
warning is enabled.
Octave:autoload-relative-file-name
If the Octave:autoload-relative-file-name
is enabled,
Octave will warn when parsing autoload() function calls with relative
paths to function files. This usually happens when using autoload()
calls in PKG_ADD files, when the PKG_ADD file is not in the same
directory as the .oct file referred to by the autoload() command.
By default, the Octave:autoload-relative-file-name
warning is
enabled.
Octave:charmat-truncated
If the Octave:charmat-truncated
warning is enabled, a warning is
printed when a character matrix with multiple rows is converted to a string.
In this case, the Octave interpreter keeps only the first row and discards
the others.
By default, the Octave:charmat-truncated
warning is enabled.
Octave:classdef-to-struct
If the Octave:classdef-to-struct
warning is enabled, a warning
is issued when a classdef object is forcibly converted into a struct with
struct (CLASSDEF_OBJ)
. Conversion removes the access
restrictions from the object and makes private and protected properties
visible.
By default, the Octave:classdef-to-struct
warning is enabled.
Octave:colon-complex-argument
If the Octave:colon-complex-argument
warning is enabled, a warning
is issued when one of the three arguments to the colon operator (base,
increment, limit) is a complex value. For example, 1:3*i
will
cause a warning to be emitted.
By default, the Octave:colon-complex-argument
warning is enabled.
Octave:colon-nonscalar-argument
If the Octave:colon-nonscalar-argument
warning is enabled, a warning
is issued when one of the three arguments to the colon operator (base,
increment, limit) is not a scalar. For example, 1:[3, 5]
will
cause a warning to be emitted.
By default, the Octave:colon-nonscalar-argument
warning is enabled.
Octave:data-file-in-path
If the Octave:data-file-in-path
warning is enabled, a warning is
issued when Octave does not find the target of a file operation such as
load
or fopen
directly, but is able to locate the file in
Octave’s search path
for files. The warning could indicate that a
different file target than the programmer intended is being used.
By default, the Octave:data-file-in-path
warning is enabled.
Octave:deprecated-function
If the Octave:deprecated-function
warning is enabled, a
warning is issued when Octave encounters a function that is obsolete and
scheduled for removal from Octave.
By default, the Octave:deprecated-function
warning is enabled.
Octave:deprecated-keyword
If the Octave:deprecated-keyword
warning is enabled, a
warning is issued when Octave encounters a keyword that is obsolete and
scheduled for removal from Octave.
By default, the Octave:deprecated-keyword
warning is enabled.
Octave:deprecated-option
If the Octave:deprecated-option
warning is enabled, a
warning is issued when an obsolete option or input to a function is used.
By default, the Octave:deprecated-option
warning is enabled.
Octave:deprecated-property
If the Octave:deprecated-property
warning is enabled, a
warning is issued when Octave encounters a graphics property that
is obsolete and scheduled for removal from Octave.
By default, the Octave:deprecated-property
warning is enabled.
Octave:eigs:UnconvergedEigenvalues
If the Octave:eigs:UnconvergedEigenvalues
warning is enabled then
the eigs function will issue a warning if the number of calculated
eigenvalues is less than the number of requested eigenvalues.
By default, the Octave:eigs:UnconvergedEigenvalues
warning is
enabled.
Octave:empty-index
If the Octave:empty-index
warning is enabled then Octave will emit a
warning whenever indexing operators are used without an index, for example
x()
.
By default, the Octave:empty-index
warning is enabled.
Octave:erase:chararray
If the Octave:erase:chararray
warning is enabled then the erase
function will issue a warning if the input pattern is a character array
rather than a string or cell array of strings.
By default, the Octave:erase:chararray
warning is enabled.
Octave:function-name-clash
If the Octave:function-name-clash
warning is enabled, a
warning is issued when Octave finds that the name of a function
defined in a function file differs from the name of the file. (If
the names disagree, the name declared inside the file is ignored.)
By default, the Octave:function-name-clash
warning is enabled.
Octave:future-time-stamp
If the Octave:future-time-stamp
warning is enabled, Octave
will print a warning if it finds a function file with a time stamp
that is in the future.
By default, the Octave:future-time-stamp
warning is enabled.
Octave:glyph-render
If the Octave:glyph-render
warning is enabled, Octave will
print a warning if the glyph for a character couldn’t be rendered with
the current font.
By default, the Octave:glyph-render
warning is enabled.
Octave:imag-to-real
If the Octave:imag-to-real
warning is enabled, a warning is
printed for implicit conversions of complex numbers to real numbers.
By default, the Octave:imag-to-real
warning is disabled.
Octave:infinite-loop
If the Octave:infinite-loop
warning is enabled, a warning is
printed when an infinite loop is detected such as for i = 1:Inf
or
while (1)
.
By default, the Octave:infinite-loop
warning is enabled.
Octave:language-extension
Print warnings when using features that are unique to the Octave
language and that may still be missing in MATLAB.
By default, the Octave:language-extension
warning is disabled.
The --traditional or --braindead startup options for
Octave may also be of use, see Command Line Options.
Octave:legacy-function
If the Octave:legacy-function
warning is enabled, a
warning is issued when Octave encounters a function that MATLAB has
suggested should be avoided. The function may become obsolete at some
point in the future and removed, in which case the warning will change to
Octave:deprecated-function
, and the function will continue to exist
for two further versions of Octave before being removed.
By default, the Octave:legacy-function
warning is enabled.
Octave:logical-conversion
If the Octave:logical-conversion
warning is enabled, a warning is
printed if an implicit conversion of an array from numerical to boolean
occurs and any of the elements in the array are not equal to zero or one.
By default, the Octave:logical-conversion
warning is enabled.
Octave:lu:sparse_input
If the Octave:lu:sparse_input
warning is enabled, Octave
will warn when the lu function is called with a sparse input and less than
four output arguments. In this case, sparsity-preserving column
permutations are not performed and the result may be inaccurate.
By default, the Octave:lu:sparse_input
warning is enabled.
Octave:missing-glyph
If the Octave:glyph-render
warning is enabled, Octave will
print a warning if the current font doesn’t provide a glyph for a
used character.
By default, the Octave:missing-glyph
warning is enabled.
Octave:missing-semicolon
If the Octave:missing-semicolon
warning is enabled, Octave
will warn when statements in function definitions don’t end in
semicolons.
By default the Octave:missing-semicolon
warning is disabled.
Octave:mixed-string-concat
If the Octave:mixed-string-concat
warning is enabled, print a
warning when concatenating a mixture of double and single quoted strings.
By default, the Octave:mixed-string-concat
warning is disabled.
Octave:nearly-singular-matrix
Octave:singular-matrix
These warnings are emitted if a (nearly) singular matrix is inverted.
By default, the Octave:nearly-singular-matrix
and
Octave:singular-matrix
warnings are enabled.
Octave:neg-dim-as-zero
If the Octave:neg-dim-as-zero
warning is enabled, print a warning
for expressions like
eye (-1)
By default, the Octave:neg-dim-as-zero
warning is disabled.
Octave:noninteger-range-as-index
If the Octave:noninteger-range-as-index
warning is enabled, a warning
is printed if an array is indexed with a range that contains non-integer
values. For example,
a = [1 2 3 4 5]; b = 2.2:4.2 ⇒ 1.2 2.2 3.2 a(b) ⇒ 2 3 4
elicits a warning if the Octave:noninteger-range-as-index
warning is
enabled.
By default, the Octave:noninteger-range-as-index
warning is enabled.
Octave:num-to-str
If the Octave:num-to-str
warning is enabled, a warning is
printed for implicit conversions of numbers to their UTF-8 encoded character
equivalents when strings are constructed using a mixture of strings and
numbers in matrix notation. For example,
[ "f", 111, 111 ] ⇒ "foo"
elicits a warning if the Octave:num-to-str
warning is
enabled. By default, the Octave:num-to-str
warning is enabled.
Octave:possible-matlab-short-circuit-operator
If the Octave:possible-matlab-short-circuit-operator
warning
is enabled, Octave will warn about using the not short circuiting
operators &
and |
inside if
or while
conditions. They normally never short circuit, but they do short
circuit when used in a condition.
By default, the Octave:possible-matlab-short-circuit-operator
warning
is enabled.
Octave:recursive-path-search
If the Octave:recursive-path-search
warning is enabled, Octave
will issue a warning if addpath
is used with double trailing
slashes.
By default, the Octave:recursive-path-search
warning is enabled.
Octave:remove-init-dir
The path
function changes the search path that Octave uses
to find functions. It is possible to set the path to a value which
excludes Octave’s own built-in functions. If the
Octave:remove-init-dir
warning is enabled then Octave will warn
when the path
function has been used in a way that may render
Octave unworkable.
By default, the Octave:remove-init-dir
warning is enabled.
Octave:reload-forces-clear
If several functions have been loaded from the same file, Octave must
clear all the functions before any one of them can be reloaded. If
the Octave:reload-forces-clear
warning is enabled, Octave will
warn you when this happens, and print a list of the additional
functions that it is forced to clear.
By default, the Octave:reload-forces-clear
warning is enabled.
Octave:separator-insert
Print warning if commas or semicolons might be inserted
automatically in literal matrices.
By default, the Octave:separator-insert
warning is disabled.
Octave:shadowed-function
If the Octave:shadowed-function
warning is enabled, Octave will
warn if a path is added to the search path that contains functions
that shadow core functions.
By default, the Octave:shadowed-function
warning is enabled.
Octave:single-quote-string
Print warning if a single quote character is used to introduce a
string constant.
By default, the Octave:single-quote-string
warning is disabled.
Octave:sqrtm:SingularMatrix
If the Octave:sqrtm:SingularMatrix
warning is enabled, a warning is
printed if the matrix square root function sqrtm
is called with an
input matrix that is singular.
By default, the Octave:sqrtm:SingularMatrix
warning is enabled.
Octave:str-to-num
If the Octave:str-to-num
warning is enabled, a warning is printed
for implicit conversions of strings to their numeric UTF-8 encoded byte
sequences. For example,
"abc" + 0 ⇒ 97 98 99
elicits a warning if the Octave:str-to-num
warning is enabled.
By default, the Octave:str-to-num
warning is disabled.
Octave:LaTeX:internal-error
If the Octave:LaTeX:internal-error
warning is enabled, a warning is
printed whenever the LaTeX renderer for text in plots encounters an issue.
By default, the Octave:LaTeX:internal-error
warning is enabled.
Octave:unimplemented-matlab-functionality
If the Octave:unimplemented-matlab-functionality
warning is enabled,
a warning is printed when a MATLAB code construct is used which the
Octave interpreter parses as valid, but for which Octave does not yet
implement the functionality.
By default, the Octave:unimplemented-matlab-functionality
warning is
enabled.
Octave:variable-switch-label
If the Octave:variable-switch-label
warning is enabled, Octave
will print a warning if a switch label is not a constant or constant
expression.
By default, the Octave:variable-switch-label
warning is disabled.
Next: Enabling and Disabling Warnings, Up: Handling Warnings [Contents][Index]