/usr/share/doc/octave/octave.html/Issuing-Warnings.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Issuing Warnings (GNU Octave)</title>

<meta name="description" content="Issuing Warnings (GNU Octave)">
<meta name="keywords" content="Issuing Warnings (GNU Octave)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Handling-Warnings.html#Handling-Warnings" rel="up" title="Handling Warnings">
<link href="Enabling-and-Disabling-Warnings.html#Enabling-and-Disabling-Warnings" rel="next" title="Enabling and Disabling Warnings">
<link href="Handling-Warnings.html#Handling-Warnings" rel="prev" title="Handling Warnings">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">


</head>

<body lang="en">
<a name="Issuing-Warnings"></a>
<div class="header">
<p>
Next: <a href="Enabling-and-Disabling-Warnings.html#Enabling-and-Disabling-Warnings" accesskey="n" rel="next">Enabling and Disabling Warnings</a>, Up: <a href="Handling-Warnings.html#Handling-Warnings" accesskey="u" rel="up">Handling Warnings</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Issuing-Warnings-1"></a>
<h4 class="subsection">12.2.1 Issuing Warnings</h4>

<p>It is possible to issue warnings from any code using the <code>warning</code>
function.  In its most simple form, the <code>warning</code> function takes a
string describing the warning as its input argument.  As an example,
the following code controls if the variable &lsquo;<samp>a</samp>&rsquo; is non-negative,
and if not issues a warning and sets &lsquo;<samp>a</samp>&rsquo; to zero.
</p>
<div class="example">
<pre class="example">a = -1;
if (a &lt; 0)
  warning (&quot;'a' must be non-negative.  Setting 'a' to zero.&quot;);
  a = 0;
endif
     -| 'a' must be non-negative.  Setting 'a' to zero.
</pre></div>

<p>Since warnings aren&rsquo;t fatal to a running program, it is not possible
to catch a warning using the <code>try</code> statement or something similar.
It is however possible to access the last warning as a string using the
<code>lastwarn</code> function.
</p>
<p>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 <code>warning</code> 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 <code>&quot;NAMESPACE:WARNING-NAME&quot;</code>.  The
namespace <code>&quot;Octave&quot;</code> is used for Octave&rsquo;s own warnings.  Any other string
is available as a namespace for user&rsquo;s own warnings.
</p>
<a name="XREFwarning"></a><dl>
<dt><a name="index-warning"></a>: <em></em> <strong>warning</strong> <em>(<var>template</var>, &hellip;)</em></dt>
<dt><a name="index-warning-1"></a>: <em></em> <strong>warning</strong> <em>(<var>id</var>, <var>template</var>, &hellip;)</em></dt>
<dt><a name="index-warning-2"></a>: <em></em> <strong>warning</strong> <em>(&quot;on&quot;, <var>id</var>)</em></dt>
<dt><a name="index-warning-3"></a>: <em></em> <strong>warning</strong> <em>(&quot;off&quot;, <var>id</var>)</em></dt>
<dt><a name="index-warning-4"></a>: <em></em> <strong>warning</strong> <em>(&quot;query&quot;, <var>id</var>)</em></dt>
<dt><a name="index-warning-5"></a>: <em></em> <strong>warning</strong> <em>(&quot;error&quot;, <var>id</var>)</em></dt>
<dt><a name="index-warning-6"></a>: <em></em> <strong>warning</strong> <em>(<var>state</var>, &quot;backtrace&quot;)</em></dt>
<dt><a name="index-warning-7"></a>: <em></em> <strong>warning</strong> <em>(<var>state</var>, <var>id</var>, &quot;local&quot;)</em></dt>
<dd><p>Display a warning message or control the behavior of Octave&rsquo;s warning
system.
</p>
<p>Format the optional arguments under the control of the template string
<var>template</var> using the same rules as the <code>printf</code> family of
functions (see <a href="Formatted-Output.html#Formatted-Output">Formatted Output</a>) and print the resulting message
on the <code>stderr</code> stream.  The message is prefixed by the character
string &lsquo;<samp>warning: </samp>&rsquo;.
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.
</p>
<p>The optional message identifier allows users to enable or disable
warnings tagged by <var>id</var>.  A message identifier is of the form
&quot;NAMESPACE:WARNING-NAME&quot;.  Octave&rsquo;s own warnings use the
<code>&quot;Octave&quot;</code> namespace (see <a href="#XREFwarning_005fids">warning_ids</a>).  The special
identifier <code>&quot;all&quot;</code> may be used to set the state of all warnings.
</p>
<p>If the first argument is <code>&quot;on&quot;</code> or <code>&quot;off&quot;</code>,
set the state of a particular warning using the identifier <var>id</var>.  If the
first argument is <code>&quot;query&quot;</code>, query the state of this warning
instead.  If the identifier is omitted, a value of <code>&quot;all&quot;</code> is
assumed.  If you set the state of a warning to <code>&quot;error&quot;</code>, the
warning named by <var>id</var> is handled as if it were an error instead.  So,
for example, the following handles all warnings as errors:
</p>
<div class="example">
<pre class="example">warning (&quot;error&quot;);
</pre></div>

<p>If the state is <code>&quot;on&quot;</code> or <code>&quot;off&quot;</code> and the third argument
is <code>&quot;backtrace&quot;</code>, then a stack trace is printed along with the
warning message when warnings occur inside function calls.  This option
is enabled by default.
</p>
<p>If the state is <code>&quot;on&quot;</code>, <code>&quot;off&quot;</code>, or <code>&quot;error&quot;</code>
and the third argument is <code>&quot;local&quot;</code>, 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 <code>&quot;local&quot;</code> option is ignored if used in the top-level
workspace.
</p>
<p>Implementation Note: For compatibility with <small>MATLAB</small>, escape
sequences in <var>template</var> (e.g., <code>&quot;\n&quot;</code> =&gt;
newline) are processed regardless of whether <var>template</var> 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., <code>&quot;\\n&quot;</code>) or use the
<code>regexptranslate</code> function.
</p>
<p><strong>See also:</strong> <a href="#XREFwarning_005fids">warning_ids</a>, <a href="#XREFlastwarn">lastwarn</a>, <a href="Raising-Errors.html#XREFerror">error</a>.
</p></dd></dl>


<a name="XREFlastwarn"></a><dl>
<dt><a name="index-lastwarn"></a>: <em>[<var>msg</var>, <var>msgid</var>] =</em> <strong>lastwarn</strong> <em>()</em></dt>
<dt><a name="index-lastwarn-1"></a>: <em></em> <strong>lastwarn</strong> <em>(<var>msg</var>)</em></dt>
<dt><a name="index-lastwarn-2"></a>: <em></em> <strong>lastwarn</strong> <em>(<var>msg</var>, <var>msgid</var>)</em></dt>
<dd><p>Query or set the last warning message.
</p>
<p>When called without input arguments, return the last warning message and
message identifier.
</p>
<p>With one argument, set the last warning message to <var>msg</var>.
</p>
<p>With two arguments, also set the last message identifier.
</p>
<p><strong>See also:</strong> <a href="#XREFwarning">warning</a>, <a href="Catching-Errors.html#XREFlasterror">lasterror</a>, <a href="Catching-Errors.html#XREFlasterr">lasterr</a>.
</p></dd></dl>


<p>The functions distributed with Octave can issue one of the following
warnings.
</p>
<a name="XREFwarning_005fids"></a><a name="index-warning-ids"></a>

<dl compact="compact">
<dt><code>Octave:abbreviated-property-match</code></dt>
<dd><p>By default, the <code>Octave:abbreviated-property-match</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:array-as-logical</code></dt>
<dd><p>If the <code>Octave:array-as-logical</code> 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 <code>Octave:array-as-logical</code> warning is disabled.
</p>
</dd>
<dt><code>Octave:array-to-scalar</code></dt>
<dd><p>If the <code>Octave:array-to-scalar</code> warning is enabled, Octave will
warn when an implicit conversion from an array to a scalar value is
attempted.
By default, the <code>Octave:array-to-scalar</code> warning is disabled.
</p>
</dd>
<dt><code>Octave:array-to-vector</code></dt>
<dd><p>If the <code>Octave:array-to-vector</code> warning is enabled, Octave will
warn when an implicit conversion from an array to a vector value is
attempted.
By default, the <code>Octave:array-to-vector</code> warning is disabled.
</p>
</dd>
<dt><code>Octave:assign-as-truth-value</code></dt>
<dd><p>If the <code>Octave:assign-as-truth-value</code> warning is
enabled, a warning is issued for statements like
</p>
<div class="example">
<pre class="example">if (s = t)
  &hellip;
</pre></div>

<p>since such statements are not common, and it is likely that the intent
was to write
</p>
<div class="example">
<pre class="example">if (s == t)
  &hellip;
</pre></div>

<p>instead.
</p>
<p>There are times when it is useful to write code that contains
assignments within the condition of a <code>while</code> or <code>if</code>
statement.  For example, statements like
</p>
<div class="example">
<pre class="example">while (c = getc ())
  &hellip;
</pre></div>

<p>are common in C programming.
</p>
<p>It is possible to avoid all warnings about such statements by
disabling the <code>Octave:assign-as-truth-value</code> warning,
but that may also let real errors like
</p>
<div class="example">
<pre class="example">if (x = 1)  # intended to test (x == 1)!
  &hellip;
</pre></div>

<p>slip by.
</p>
<p>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
</p>
<div class="example">
<pre class="example">while ((c = getc ()))
  &hellip;
</pre></div>

<p>will prevent the warning from being printed for this statement, while
allowing Octave to warn about other assignments used in conditional
contexts.
</p>
<p>By default, the <code>Octave:assign-as-truth-value</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:associativity-change</code></dt>
<dd><p>If the <code>Octave:associativity-change</code> warning is
enabled, Octave will warn about possible changes in the meaning of
some code due to changes in associativity for some operators.
Associativity changes have typically been made for <small>MATLAB</small>
compatibility.
By default, the <code>Octave:associativity-change</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:autoload-relative-file-name</code></dt>
<dd><p>If the <code>Octave:autoload-relative-file-name</code> 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 <code>Octave:autoload-relative-file-name</code> warning is
enabled.
</p>
</dd>
<dt><code>Octave:built-in-variable-assignment</code></dt>
<dd><p>By default, the <code>Octave:built-in-variable-assignment</code> warning is
enabled.
</p>
</dd>
<dt><code>Octave:deprecated-function</code></dt>
<dd><p>If the <code>Octave:deprecated-function</code> warning is enabled, a
warning is issued when Octave encounters a function that is obsolete and
scheduled for removal from Octave.
By default, the <code>Octave:deprecated-function</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:deprecated-keyword</code></dt>
<dd><p>If the <code>Octave:deprecated-keyword</code> warning is enabled, a
warning is issued when Octave encounters a keyword that is obsolete and
scheduled for removal from Octave.
By default, the <code>Octave:deprecated-keyword</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:deprecated-property</code></dt>
<dd><p>If the <code>Octave:deprecated-property</code> 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 <code>Octave:deprecated-property</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:divide-by-zero</code></dt>
<dd><p>If the <code>Octave:divide-by-zero</code> warning is enabled, a
warning is issued when Octave encounters a division by zero.
By default, the <code>Octave:divide-by-zero</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:fopen-file-in-path</code></dt>
<dd><p>By default, the <code>Octave:fopen-file-in-path</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:function-name-clash</code></dt>
<dd><p>If the <code>Octave:function-name-clash</code> 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 <code>Octave:function-name-clash</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:future-time-stamp</code></dt>
<dd><p>If the <code>Octave:future-time-stamp</code> 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 <code>Octave:future-time-stamp</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:glyph-render</code></dt>
<dd><p>By default, the <code>Octave:glyph-render</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:imag-to-real</code></dt>
<dd><p>If the <code>Octave:imag-to-real</code> warning is enabled, a warning is
printed for implicit conversions of complex numbers to real numbers.
By default, the <code>Octave:imag-to-real</code> warning is disabled.
</p>
</dd>
<dt><code>Octave:language-extension</code></dt>
<dd><p>Print warnings when using features that are unique to the Octave
language and that may still be missing in <small>MATLAB</small>.
By default, the <code>Octave:language-extension</code> warning is disabled.
The <samp>--traditional</samp> or <samp>--braindead</samp> startup options for
Octave may also be of use, see <a href="Command-Line-Options.html#Command-Line-Options">Command Line Options</a>.
</p>
</dd>
<dt><code>Octave:load-file-in-path</code></dt>
<dd><p>By default, the <code>Octave:load-file-in-path</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:logical-conversion</code></dt>
<dd><p>By default, the <code>Octave:logical-conversion</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:missing-glyph</code></dt>
<dd><p>By default, the <code>Octave:missing-glyph</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:missing-semicolon</code></dt>
<dd><p>If the <code>Octave:missing-semicolon</code> warning is enabled, Octave
will warn when statements in function definitions don&rsquo;t end in
semicolons.
By default the <code>Octave:missing-semicolon</code> warning is disabled.
</p>
</dd>
<dt><code>Octave:mixed-string-concat</code></dt>
<dd><p>If the <code>Octave:mixed-string-concat</code> warning is enabled, print a
warning when concatenating a mixture of double and single quoted strings.
By default, the <code>Octave:mixed-string-concat</code> warning is disabled.
</p>
</dd>
<dt><code>Octave:neg-dim-as-zero</code></dt>
<dd><p>If the <code>Octave:neg-dim-as-zero</code> warning is enabled, print a warning
for expressions like
</p>
<div class="example">
<pre class="example">eye (-1)
</pre></div>

<p>By default, the <code>Octave:neg-dim-as-zero</code> warning is disabled.
</p>
</dd>
<dt><code>Octave:nested-functions-coerced</code></dt>
<dd><p>By default, the <code>Octave:nested-functions-coerced</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:noninteger-range-as-index</code></dt>
<dd><p>By default, the <code>Octave:noninteger-range-as-index</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:num-to-str</code></dt>
<dd><p>If the <code>Octave:num-to-str</code> warning is enable, a warning is
printed for implicit conversions of numbers to their ASCII character
equivalents when strings are constructed using a mixture of strings and
numbers in matrix notation.  For example,
</p>
<div class="example">
<pre class="example">[ &quot;f&quot;, 111, 111 ]
&rArr; &quot;foo&quot;
</pre></div>

<p>elicits a warning if the <code>Octave:num-to-str</code> warning is
enabled.  By default, the <code>Octave:num-to-str</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:possible-matlab-short-circuit-operator</code></dt>
<dd><p>If the <code>Octave:possible-matlab-short-circuit-operator</code> warning
is enabled, Octave will warn about using the not short circuiting
operators <code>&amp;</code> and <code>|</code> inside <code>if</code> or <code>while</code>
conditions.  They normally never short circuit, but <small>MATLAB</small> always
short circuits if any logical operators are used in a condition.  You
can turn on the option
</p>
<div class="example">
<pre class="example">do_braindead_shortcircuit_evaluation (1)
</pre></div>

<p>if you would like to enable this short-circuit evaluation in
Octave.  Note that the <code>&amp;&amp;</code> and <code>||</code> operators always short
circuit in both Octave and <small>MATLAB</small>, so it&rsquo;s only necessary to
enable <small>MATLAB</small>-style short-circuiting if it&rsquo;s too arduous to modify
existing code that relies on this behavior.
By default, the <code>Octave:possible-matlab-short-circuit-operator</code> warning
is enabled.
</p>
</dd>
<dt><code>Octave:precedence-change</code></dt>
<dd><p>If the <code>Octave:precedence-change</code> warning is enabled, Octave
will warn about possible changes in the meaning of some code due to
changes in precedence for some operators.  Precedence changes have
typically been made for <small>MATLAB</small> compatibility.
By default, the <code>Octave:precedence-change</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:recursive-path-search</code></dt>
<dd><p>By default, the <code>Octave:recursive-path-search</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:remove-init-dir</code></dt>
<dd><p>The <code>path</code> function changes the search path that Octave uses
to find functions.  It is possible to set the path to a value which
excludes Octave&rsquo;s own built-in functions.  If the
<code>Octave:remove-init-dir</code> warning is enabled then Octave will warn
when the <code>path</code> function has been used in a way that may render
Octave unworkable.
By default, the <code>Octave:remove-init-dir</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:reload-forces-clear</code></dt>
<dd><p>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 <code>Octave:reload-forces-clear</code> 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 <code>Octave:reload-forces-clear</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:resize-on-range-error</code></dt>
<dd><p>If the <code>Octave:resize-on-range-error</code> warning is enabled, print a
warning when a matrix is resized by an indexed assignment with
indices outside the current bounds.
By default, the <code>Octave:resize-on-range-error</code> warning is disabled.
</p>
</dd>
<dt><code>Octave:separator-insert</code></dt>
<dd><p>Print warning if commas or semicolons might be inserted
automatically in literal matrices.
By default, the <code>Octave:separator-insert</code> warning is disabled.
</p>
</dd>
<dt><code>Octave:shadowed-function</code></dt>
<dd><p>By default, the <code>Octave:shadowed-function</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:single-quote-string</code></dt>
<dd><p>Print warning if a single quote character is used to introduce a
string constant.
By default, the <code>Octave:single-quote-string</code> warning is disabled.
</p>
</dd>
<dt><code>Octave:nearly-singular-matrix</code></dt>
<dt><code>Octave:singular-matrix</code></dt>
<dd><p>By default, the <code>Octave:nearly-singular-matrix</code> and
<code>Octave:singular-matrix</code> warnings are enabled.
</p>
</dd>
<dt><code>Octave:sqrtm:SingularMatrix</code></dt>
<dd><p>By default, the <code>Octave:sqrtm:SingularMatrix</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:str-to-num</code></dt>
<dd><p>If the <code>Octave:str-to-num</code> warning is enabled, a warning is printed
for implicit conversions of strings to their numeric ASCII equivalents.
For example,
</p>
<div class="example">
<pre class="example">&quot;abc&quot; + 0
&rArr; 97 98 99
</pre></div>

<p>elicits a warning if the <code>Octave:str-to-num</code> warning is enabled.
By default, the <code>Octave:str-to-num</code> warning is disabled.
</p>
</dd>
<dt><code>Octave:undefined-return-values</code></dt>
<dd><p>If the <code>Octave:undefined-return-values</code> warning is disabled,
print a warning if a function does not define all the values in
the return list which are expected.
By default, the <code>Octave:undefined-return-values</code> warning is enabled.
</p>
</dd>
<dt><code>Octave:variable-switch-label</code></dt>
<dd><p>If the <code>Octave:variable-switch-label</code> warning is enabled, Octave
will print a warning if a switch label is not a constant or constant
expression.
By default, the <code>Octave:variable-switch-label</code> warning is disabled.
</p></dd>
</dl>



<hr>
<div class="header">
<p>
Next: <a href="Enabling-and-Disabling-Warnings.html#Enabling-and-Disabling-Warnings" accesskey="n" rel="next">Enabling and Disabling Warnings</a>, Up: <a href="Handling-Warnings.html#Handling-Warnings" accesskey="u" rel="up">Handling Warnings</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
octave-doc 4.2.2-1ubuntu1 / usr / share / doc / octave / octave.html / Issuing-Warnings.html
