1@c DO NOT EDIT! Generated automatically by munge-texi.pl. 2 3@c Copyright (C) 1996-2019 John W. Eaton 4@c 5@c This file is part of Octave. 6@c 7@c Octave is free software: you can redistribute it and/or modify it 8@c under the terms of the GNU General Public License as published by 9@c the Free Software Foundation, either version 3 of the License, or 10@c (at your option) any later version. 11@c 12@c Octave is distributed in the hope that it will be useful, but 13@c WITHOUT ANY WARRANTY; without even the implied warranty of 14@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15@c GNU General Public License for more details. 16@c 17@c You should have received a copy of the GNU General Public License 18@c along with Octave; see the file COPYING. If not, see 19@c <https://www.gnu.org/licenses/>. 20 21@node Errors and Warnings 22@chapter Errors and Warnings 23 24Octave includes several functions for printing error and warning 25messages. When you write functions that need to take special action 26when they encounter abnormal conditions, you should print the error 27messages using the functions described in this chapter. 28 29Since many of Octave's functions use these functions, it is also useful 30to understand them, so that errors and warnings can be handled. 31 32@menu 33* Handling Errors:: 34* Handling Warnings:: 35@end menu 36 37@node Handling Errors 38@section Handling Errors 39 40An error is something that occurs when a program is in a state where 41it doesn't make sense to continue. An example is when a function is 42called with too few input arguments. In this situation the function 43should abort with an error message informing the user of the lacking 44input arguments. 45 46Since an error can occur during the evaluation of a program, it is 47very convenient to be able to detect that an error occurred, so that 48the error can be fixed. This is possible with the @code{try} statement 49described in @ref{The try Statement}. 50 51@menu 52* Raising Errors:: 53* Catching Errors:: 54* Recovering From Errors:: 55@end menu 56 57@node Raising Errors 58@subsection Raising Errors 59 60The most common use of errors is for checking input arguments to 61functions. The following example calls the @code{error} function if 62the function @code{f} is called without any input arguments. 63 64@example 65@group 66function f (arg1) 67 if (nargin == 0) 68 error ("not enough input arguments"); 69 endif 70endfunction 71@end group 72@end example 73 74When the @code{error} function is called, it prints the given message 75and returns to the Octave prompt. This means that no code following 76a call to @code{error} will be executed. 77 78It is also possible to assign an identification string to an error. 79If an error has such an ID the user can catch this error 80as will be described in the next section. To assign an ID to an error, 81simply call @code{error} with two string arguments, where the first 82is the identification string, and the second is the actual error. Note 83that error IDs are in the format @qcode{"NAMESPACE:ERROR-NAME"}. The namespace 84@qcode{"Octave"} is used for Octave's own errors. Any other string is 85available as a namespace for user's own errors. 86 87@c error libinterp/corefcn/error.cc 88@anchor{XREFerror} 89@deftypefn {} {} error (@var{template}, @dots{}) 90@deftypefnx {} {} error (@var{id}, @var{template}, @dots{}) 91Display an error message and stop m-file execution. 92 93Format the optional arguments under the control of the template string 94@var{template} using the same rules as the @code{printf} family of 95functions (@pxref{Formatted Output}) and print the resulting message 96on the @code{stderr} stream. The message is prefixed by the character 97string @samp{error: }. 98 99Calling @code{error} also sets Octave's internal error state such that 100control will return to the top level without evaluating any further 101commands. This is useful for aborting from functions or scripts. 102 103If the error message does not end with a newline character, Octave will 104print a traceback of all the function calls leading to the error. For 105example, given the following function definitions: 106 107@example 108@group 109function f () g (); end 110function g () h (); end 111function h () nargin == 1 || error ("nargin != 1"); end 112@end group 113@end example 114 115@noindent 116calling the function @code{f} will result in a list of messages that 117can help you to quickly find the exact location of the error: 118 119@example 120@group 121f () 122error: nargin != 1 123error: called from: 124error: h at line 1, column 27 125error: g at line 1, column 15 126error: f at line 1, column 15 127@end group 128@end example 129 130If the error message ends in a newline character, Octave will print the 131message but will not display any traceback messages as it returns 132control to the top level. For example, modifying the error message 133in the previous example to end in a newline causes Octave to only print 134a single message: 135 136@example 137@group 138function h () nargin == 1 || error ("nargin != 1\n"); end 139f () 140error: nargin != 1 141@end group 142@end example 143 144A null string ("") input to @code{error} will be ignored and the code 145will continue running as if the statement were a NOP@. This is for 146compatibility with @sc{matlab}. It also makes it possible to write code 147such as 148 149@example 150@group 151err_msg = ""; 152if (CONDITION 1) 153 err_msg = "CONDITION 1 found"; 154elseif (CONDITION2) 155 err_msg = "CONDITION 2 found"; 156@dots{} 157endif 158error (err_msg); 159@end group 160@end example 161 162@noindent 163which will only stop execution if an error has been found. 164 165Implementation Note: For compatibility with @sc{matlab}, escape 166sequences in @var{template} (e.g., @qcode{"@xbackslashchar{}n"} => 167newline) are processed regardless of whether @var{template} has been defined 168with single quotes, as long as there are two or more input arguments. To 169disable escape sequence expansion use a second backslash before the sequence 170(e.g., @qcode{"@xbackslashchar{}@xbackslashchar{}n"}) or use the 171@code{regexptranslate} function. 172@xseealso{@ref{XREFwarning,,warning}, @ref{XREFlasterror,,lasterror}} 173@end deftypefn 174 175 176Since it is common to use errors when there is something wrong with 177the input to a function, Octave supports functions to simplify such code. 178When the @code{print_usage} function is called, it reads the help text 179of the function calling @code{print_usage}, and presents a useful error. 180If the help text is written in Texinfo it is possible to present an 181error message that only contains the function prototypes as described 182by the @code{@@deftypefn} parts of the help text. When the help text 183isn't written in Texinfo, the error message contains the entire help 184message. 185 186Consider the following function. 187 188@example 189@group 190## -*- texinfo -*- 191## @@deftypefn @{@} f (@@var@{arg1@}) 192## Function help text goes here@dots{} 193## @@end deftypefn 194function f (arg1) 195 if (nargin == 0) 196 print_usage (); 197 endif 198endfunction 199@end group 200@end example 201 202@noindent 203When it is called with no input arguments it produces the following 204error. 205 206@example 207@group 208f () 209 210@print{} error: Invalid call to f. Correct usage is: 211@print{} 212@print{} -- f (ARG1) 213@print{} 214@print{} 215@print{} Additional help for built-in functions and operators is 216@print{} available in the online version of the manual. Use the command 217@print{} 'doc <topic>' to search the manual index. 218@print{} 219@print{} Help and information about Octave is also available on the WWW 220@print{} at https://www.octave.org and via the help@@octave.org 221@print{} mailing list. 222@end group 223@end example 224 225@c print_usage scripts/help/print_usage.m 226@anchor{XREFprint_usage} 227@deftypefn {} {} print_usage () 228@deftypefnx {} {} print_usage (@var{name}) 229Print the usage message for the function @var{name}. 230 231When called with no input arguments the @code{print_usage} function displays 232the usage message of the currently executing function. 233@xseealso{@ref{XREFhelp,,help}} 234@end deftypefn 235 236 237@c beep scripts/io/beep.m 238@anchor{XREFbeep} 239@deftypefn {} {} beep () 240Produce a beep from the speaker (or visual bell). 241 242This function sends the alarm character @qcode{"@xbackslashchar{}a"} to 243the terminal. Depending on the user's configuration this may produce an 244audible beep, a visual bell, or nothing at all. 245@xseealso{@ref{XREFputs,,puts}, @ref{XREFfputs,,fputs}, @ref{XREFprintf,,printf}, @ref{XREFfprintf,,fprintf}} 246@end deftypefn 247 248 249@c beep_on_error libinterp/corefcn/error.cc 250@anchor{XREFbeep_on_error} 251@deftypefn {} {@var{val} =} beep_on_error () 252@deftypefnx {} {@var{old_val} =} beep_on_error (@var{new_val}) 253@deftypefnx {} {} beep_on_error (@var{new_val}, "local") 254Query or set the internal variable that controls whether Octave will try 255to ring the terminal bell before printing an error message. 256 257When called from inside a function with the @qcode{"local"} option, the 258variable is changed locally for the function and any subroutines it calls. 259The original variable value is restored when exiting the function. 260@end deftypefn 261 262 263@node Catching Errors 264@subsection Catching Errors 265 266When an error occurs, it can be detected and handled using the 267@code{try} statement as described in @ref{The try Statement}. 268As an example, the following piece of code counts the number of errors 269that occurs during a @code{for} loop. 270 271@example 272@group 273number_of_errors = 0; 274for n = 1:100 275 try 276 @dots{} 277 catch 278 number_of_errors++; 279 end_try_catch 280endfor 281@end group 282@end example 283 284The above example treats all errors the same. In many situations it 285can however be necessary to discriminate between errors, and take 286different actions depending on the error. The @code{lasterror} 287function returns a structure containing information about the last 288error that occurred. As an example, the code above could be changed 289to count the number of errors related to the @samp{*} operator. 290 291@example 292@group 293number_of_errors = 0; 294for n = 1:100 295 try 296 @dots{} 297 catch 298 msg = lasterror.message; 299 if (strfind (msg, "operator *")) 300 number_of_errors++; 301 endif 302 end_try_catch 303endfor 304@end group 305@end example 306 307@noindent 308Alternatively, the output of the @code{lasterror} function can be found 309in a variable indicated immediately after the @code{catch} keyword, as 310in the example below showing how to redirect an error as a warning: 311 312@example 313@group 314try 315 @dots{} 316catch err 317 warning(err.identifier, err.message); 318 @dots{} 319end_try_catch 320@end group 321@end example 322 323@c lasterror libinterp/corefcn/error.cc 324@anchor{XREFlasterror} 325@deftypefn {} {@var{lasterr} =} lasterror () 326@deftypefnx {} {} lasterror (@var{err}) 327@deftypefnx {} {} lasterror ("reset") 328Query or set the last error message structure. 329 330When called without arguments, return a structure containing the last error 331message and other information related to this error. The elements of the 332structure are: 333 334@table @code 335@item message 336The text of the last error message 337 338@item identifier 339The message identifier of this error message 340 341@item stack 342A structure containing information on where the message occurred. This may 343be an empty structure if the information cannot be obtained. The fields of 344the structure are: 345 346@table @code 347@item file 348The name of the file where the error occurred 349 350@item name 351The name of function in which the error occurred 352 353@item line 354The line number at which the error occurred 355 356@item column 357An optional field with the column number at which the error occurred 358@end table 359@end table 360 361The last error structure may be set by passing a scalar structure, 362@var{err}, as input. Any fields of @var{err} that match those above are 363set while any unspecified fields are initialized with default values. 364 365If @code{lasterror} is called with the argument @qcode{"reset"}, all 366fields are set to their default values. 367@xseealso{@ref{XREFlasterr,,lasterr}, @ref{XREFerror,,error}, @ref{XREFlastwarn,,lastwarn}} 368@end deftypefn 369 370 371@c lasterr libinterp/corefcn/error.cc 372@anchor{XREFlasterr} 373@deftypefn {} {[@var{msg}, @var{msgid}] =} lasterr () 374@deftypefnx {} {} lasterr (@var{msg}) 375@deftypefnx {} {} lasterr (@var{msg}, @var{msgid}) 376Query or set the last error message. 377 378When called without input arguments, return the last error message and 379message identifier. 380 381With one argument, set the last error message to @var{msg}. 382 383With two arguments, also set the last message identifier. 384@xseealso{@ref{XREFlasterror,,lasterror}, @ref{XREFerror,,error}, @ref{XREFlastwarn,,lastwarn}} 385@end deftypefn 386 387 388The next example counts indexing errors. The errors are caught using the 389field identifier of the structure returned by the function @code{lasterror}. 390 391@example 392@group 393number_of_errors = 0; 394for n = 1:100 395 try 396 @dots{} 397 catch 398 id = lasterror.identifier; 399 if (strcmp (id, "Octave:invalid-indexing")) 400 number_of_errors++; 401 endif 402 end_try_catch 403endfor 404@end group 405@end example 406 407The functions distributed with Octave can issue one of the following 408errors. 409 410@c error_ids scripts/help/error_ids.m 411@anchor{XREFerror_ids} 412@cindex error ids 413 414@table @code 415@item Octave:bad-alloc 416Indicates that memory couldn't be allocated. 417 418@item Octave:invalid-context 419Indicates the error was generated by an operation that cannot be executed in 420the scope from which it was called. For example, the function 421@code{print_usage ()} when called from the Octave prompt raises this error. 422 423@item Octave:invalid-fun-call 424Indicates that a function was called in an incorrect way, e.g., wrong number 425of input arguments. 426 427@item Octave:invalid-indexing 428Indicates that a data-type was indexed incorrectly, e.g., real-value index 429for arrays, nonexistent field of a structure. 430 431@item Octave:invalid-input-arg 432Indicates that a function was called with invalid input arguments. 433 434@item Octave:undefined-function 435Indicates a call to a function that is not defined. The function may exist 436but Octave is unable to find it in the search path. 437 438@end table 439 440 441 442When an error has been handled it is possible to raise it again. This 443can be useful when an error needs to be detected, but the program should 444still abort. This is possible using the @code{rethrow} function. The 445previous example can now be changed to count the number of errors 446related to the @samp{*} operator, but still abort if another kind of 447error occurs. 448 449@example 450@group 451number_of_errors = 0; 452for n = 1:100 453 try 454 @dots{} 455 catch 456 msg = lasterror.message; 457 if (strfind (msg, "operator *")) 458 number_of_errors++; 459 else 460 rethrow (lasterror); 461 endif 462 end_try_catch 463endfor 464@end group 465@end example 466 467@c rethrow libinterp/corefcn/error.cc 468@anchor{XREFrethrow} 469@deftypefn {} {} rethrow (@var{err}) 470Reissue a previous error as defined by @var{err}. 471 472@var{err} is a structure that must contain at least the @qcode{"message"} 473and @qcode{"identifier"} fields. @var{err} can also contain a field 474@qcode{"stack"} that gives information on the assumed location of the 475error. Typically @var{err} is returned from @code{lasterror}. 476@xseealso{@ref{XREFlasterror,,lasterror}, @ref{XREFlasterr,,lasterr}, @ref{XREFerror,,error}} 477@end deftypefn 478 479 480@c FIXME: I have no idea what the rest of the functions are used for... 481 482@c errno libinterp/corefcn/utils.cc 483@anchor{XREFerrno} 484@deftypefn {} {@var{err} =} errno () 485@deftypefnx {} {@var{err} =} errno (@var{val}) 486@deftypefnx {} {@var{err} =} errno (@var{name}) 487Query or set the system-dependent variable errno. 488 489When called with no inputs, return the current value of errno. 490 491When called with a numeric input @var{val}, set the current value of errno 492to the specified value. The previous value of errno is returned as @var{err}. 493 494When called with a character string @var{name}, return the numeric value of 495errno which corresponds to the specified error code. If @var{name} is not 496a recognized error code then -1 is returned. 497 498@xseealso{@ref{XREFerrno_list,,errno_list}} 499@end deftypefn 500 501 502@c errno_list libinterp/corefcn/utils.cc 503@anchor{XREFerrno_list} 504@deftypefn {} {} errno_list () 505Return a structure containing the system-dependent errno values. 506@xseealso{@ref{XREFerrno,,errno}} 507@end deftypefn 508 509 510@node Recovering From Errors 511@subsection Recovering From Errors 512 513Octave provides several ways of recovering from errors. There are 514@code{try}/@code{catch} blocks, 515@code{unwind_protect}/@code{unwind_protect_cleanup} blocks, 516and finally the @code{onCleanup} command. 517 518The @code{onCleanup} command associates an ordinary Octave variable (the 519trigger) with an arbitrary function (the action). Whenever the Octave variable 520ceases to exist---whether due to a function return, an error, or simply because 521the variable has been removed with @code{clear}---then the assigned function 522is executed. 523 524The function can do anything necessary for cleanup such as closing open file 525handles, printing an error message, or restoring global variables to their 526initial values. The last example is a very convenient idiom for Octave code. 527For example: 528 529@example 530@group 531function rand42 532 old_state = rand ("state"); 533 restore_state = onCleanup (@@() rand ("state", old_state)); 534 rand ("state", 42); 535 @dots{} 536endfunction # rand generator state restored by onCleanup 537@end group 538@end example 539 540@c onCleanup libinterp/octave-value/ov-oncleanup.cc 541@anchor{XREFonCleanup} 542@deftypefn {} {@var{obj} =} onCleanup (@var{function}) 543Create a special object that executes a given function upon destruction. 544 545If the object is copied to multiple variables (or cell or struct array 546elements) or returned from a function, @var{function} will be executed after 547clearing the last copy of the object. Note that if multiple local onCleanup 548variables are created, the order in which they are called is unspecified. 549For similar functionality @xref{The unwind_protect Statement}. 550@end deftypefn 551 552 553@node Handling Warnings 554@section Handling Warnings 555 556Like an error, a warning is issued when something unexpected happens. 557Unlike an error, a warning doesn't abort the currently running program. 558A simple example of a warning is when a number is divided by zero. In 559this case Octave will issue a warning and assign the value @code{Inf} 560to the result. 561 562@example 563@group 564a = 1/0 565 @print{} warning: division by zero 566 @result{} a = Inf 567@end group 568@end example 569 570@menu 571* Issuing Warnings:: 572* Enabling and Disabling Warnings:: 573@end menu 574 575@node Issuing Warnings 576@subsection Issuing Warnings 577 578It is possible to issue warnings from any code using the @code{warning} 579function. In its most simple form, the @code{warning} function takes a 580string describing the warning as its input argument. As an example, 581the following code controls if the variable @samp{a} is non-negative, 582and if not issues a warning and sets @samp{a} to zero. 583 584@example 585@group 586a = -1; 587if (a < 0) 588 warning ("'a' must be non-negative. Setting 'a' to zero."); 589 a = 0; 590endif 591 @print{} 'a' must be non-negative. Setting 'a' to zero. 592@end group 593@end example 594 595Since warnings aren't fatal to a running program, it is not possible 596to catch a warning using the @code{try} statement or something similar. 597It is however possible to access the last warning as a string using the 598@code{lastwarn} function. 599 600It is also possible to assign an identification string to a warning. 601If a warning has such an ID the user can enable and disable this warning 602as will be described in the next section. To assign an ID to a warning, 603simply call @code{warning} with two string arguments, where the first 604is the identification string, and the second is the actual warning. Note 605that warning IDs are in the format @qcode{"NAMESPACE:WARNING-NAME"}. The 606namespace @qcode{"Octave"} is used for Octave's own warnings. Any other string 607is available as a namespace for user's own warnings. 608 609@c warning libinterp/corefcn/error.cc 610@anchor{XREFwarning} 611@deftypefn {} {} warning (@var{template}, @dots{}) 612@deftypefnx {} {} warning (@var{id}, @var{template}, @dots{}) 613@deftypefnx {} {} warning ("on", @var{id}) 614@deftypefnx {} {} warning ("off", @var{id}) 615@deftypefnx {} {} warning ("error", @var{id}) 616@deftypefnx {} {} warning ("query", @var{id}) 617@deftypefnx {} {} warning (@var{state}, @var{id}, "local") 618@deftypefnx {} {} warning (@var{warning_struct}) 619@deftypefnx {} {@var{warning_struct} =} warning (@dots{}) 620@deftypefnx {} {} warning (@var{state}, @var{mode}) 621 622Display a warning message or control the behavior of Octave's warning system. 623 624The first call form uses a template @var{template} and optional additional 625arguments to display a message on the @code{stderr} stream. The message is 626formatted using the same rules as the @code{printf} family of functions 627(@pxref{Formatted Output}) and prefixed by the character string 628@w{@samp{warning: }}. You should use this function when you want to notify the 629user of an unusual condition, but only when it makes sense for your program to 630go on. For example: 631 632@example 633@group 634warning ("foo: maybe something wrong here"); 635@end group 636@end example 637 638If the warning message does not end with a newline character, Octave will 639print a traceback of all the function calls leading to the warning. If the 640warning message does end in a newline character, Octave will suppress the 641traceback messages as it returns control to the top level. For more details 642and examples, see @ref{XREFerror,,error}. 643 644The optional warning identifier @var{id} allows users to enable or disable 645warnings tagged by this identifier. A message identifier is a string of the 646form @qcode{"NAMESPACE:WARNING-NAME"}. Octave's own warnings use the 647@qcode{"Octave"} namespace (@pxref{XREFwarning_ids,,warning_ids}). For 648example: 649 650@example 651@group 652warning ("MyNameSpace:check-something", 653 "foo: maybe something wrong here"); 654@end group 655@end example 656 657The second call form is meant to change and/or query the state of warnings. 658The first input argument must be a string @var{state} (@qcode{"on"}, 659@qcode{"off"}, @qcode{"error"}, or @qcode{"query"}) followed by an optional 660warning identifier @var{id} or @qcode{"all"} (default). 661 662The optional output argument @var{warning_struct} is a structure or structure 663array with fields @qcode{"state"} and @qcode{"identifier"}. The @var{state} 664argument may have the following values: 665 666@table @asis 667@item @qcode{"on"}|@qcode{"off"}: 668Enable or disable the display of warnings identified by @var{id} and optionally 669return their previous state @var{stout}. 670 671@item @qcode{"error"}: 672Turn warnings identified by @var{id} into errors and optionally return their 673previous state @var{stout}. 674 675@item @qcode{"query"}: 676Return the current state of warnings identified by @var{id}. 677@end table 678 679A structure or structure array @var{warning_struct}, with fields 680@qcode{"state"} and @qcode{"identifier"}, may be given as an input to achieve 681equivalent results. The following example shows how to temporarily disable a 682warning and then restore its original state: 683 684@example 685@group 686loglog (-1:10); 687## Disable the previous warning and save its original state 688[~, id] = lastwarn (); 689warnstate = warning ("off", id); 690loglog (-1:10); 691## Restore its original state 692warning (warnstate); 693@end group 694@end example 695 696If a final argument @qcode{"local"} is provided then the warning state will be 697set temporarily until the end of the current function. Changes to warning 698states that are set locally affect the current function and all functions 699called from the current scope. The previous warning state is restored on 700return from the current function. The @qcode{"local"} option is ignored if 701used in the top-level workspace. 702 703With no input argument @code{warning ()} is equivalent to 704@code{warning ("query", "all")} except that in the absence of an output 705argument, the state of warnings is displayed on @code{stderr}. 706 707The level of verbosity of the warning system may also be controlled by two 708modes @var{mode}: 709 710@table @asis 711@item @qcode{"backtrace"}: 712enable/disable the display of the stack trace after the warning message 713 714@item @qcode{"verbose"}: 715enable/disable the display of additional information after the warning message 716@end table 717 718In this case the @var{state} argument may only be @qcode{"on"} or 719@qcode{"off"}. 720 721Implementation Note: For compatibility with @sc{matlab}, escape sequences in 722@var{template} (e.g., @qcode{"@xbackslashchar{}n"} => newline) are processed 723regardless of whether @var{template} has been defined with single quotes, as 724long as there are two or more input arguments. To disable escape sequence 725expansion use a second backslash before the sequence (e.g., 726@qcode{"@xbackslashchar{}@xbackslashchar{}n"}) or use the 727@code{regexptranslate} function. 728@xseealso{@ref{XREFwarning_ids,,warning_ids}, @ref{XREFlastwarn,,lastwarn}, @ref{XREFerror,,error}} 729@end deftypefn 730 731 732@c lastwarn libinterp/corefcn/error.cc 733@anchor{XREFlastwarn} 734@deftypefn {} {[@var{msg}, @var{msgid}] =} lastwarn () 735@deftypefnx {} {} lastwarn (@var{msg}) 736@deftypefnx {} {} lastwarn (@var{msg}, @var{msgid}) 737Query or set the last warning message. 738 739When called without input arguments, return the last warning message and 740message identifier. 741 742With one argument, set the last warning message to @var{msg}. 743 744With two arguments, also set the last message identifier. 745@xseealso{@ref{XREFwarning,,warning}, @ref{XREFlasterror,,lasterror}, @ref{XREFlasterr,,lasterr}} 746@end deftypefn 747 748 749The functions distributed with Octave can issue one of the following 750warnings. 751 752@c warning_ids scripts/help/warning_ids.m 753@anchor{XREFwarning_ids} 754@cindex warning ids 755 756@table @code 757@item Octave:abbreviated-property-match 758By default, the @code{Octave:abbreviated-property-match} warning is enabled. 759 760@item Octave:addpath-pkg 761If the @code{Octave:addpath-pkg} warning is enabled, 762Octave will warn when a package directory (i.e., +package_name) is added 763to the @code{path}. Typically, only the parent directory which contains the 764package directory should be added to the load path. 765By default, the @code{Octave:addpath-pkg} warning is enabled. 766 767@item Octave:array-as-logical 768If the @code{Octave:array-as-logical} warning is enabled, 769Octave will warn when an array of size greater than 1x1 is used 770as a truth value in an if, while, or until statement. 771By default, the @code{Octave:array-as-logical} warning is disabled. 772 773@item Octave:array-to-scalar 774If the @code{Octave:array-to-scalar} warning is enabled, Octave will 775warn when an implicit conversion from an array to a scalar value is 776attempted. 777By default, the @code{Octave:array-to-scalar} warning is disabled. 778 779@item Octave:array-to-vector 780If the @code{Octave:array-to-vector} warning is enabled, Octave will 781warn when an implicit conversion from an array to a vector value is 782attempted. 783By default, the @code{Octave:array-to-vector} warning is disabled. 784 785@item Octave:assign-as-truth-value 786If the @code{Octave:assign-as-truth-value} warning is 787enabled, a warning is issued for statements like 788 789@example 790@group 791if (s = t) 792 @dots{} 793@end group 794@end example 795 796@noindent 797since such statements are not common, and it is likely that the intent 798was to write 799 800@example 801@group 802if (s == t) 803 @dots{} 804@end group 805@end example 806 807@noindent 808instead. 809 810There are times when it is useful to write code that contains 811assignments within the condition of a @code{while} or @code{if} 812statement. For example, statements like 813 814@example 815@group 816while (c = getc ()) 817 @dots{} 818@end group 819@end example 820 821@noindent 822are common in C programming. 823 824It is possible to avoid all warnings about such statements by 825disabling the @code{Octave:assign-as-truth-value} warning, 826but that may also let real errors like 827 828@example 829@group 830if (x = 1) # intended to test (x == 1)! 831 @dots{} 832@end group 833@end example 834 835@noindent 836slip by. 837 838In such cases, it is possible suppress errors for specific statements by 839writing them with an extra set of parentheses. For example, writing the 840previous example as 841 842@example 843@group 844while ((c = getc ())) 845 @dots{} 846@end group 847@end example 848 849@noindent 850will prevent the warning from being printed for this statement, while 851allowing Octave to warn about other assignments used in conditional 852contexts. 853 854By default, the @code{Octave:assign-as-truth-value} warning is enabled. 855 856@item Octave:autoload-relative-file-name 857If the @code{Octave:autoload-relative-file-name} is enabled, 858Octave will warn when parsing autoload() function calls with relative 859paths to function files. This usually happens when using autoload() 860calls in PKG_ADD files, when the PKG_ADD file is not in the same 861directory as the .oct file referred to by the autoload() command. 862By default, the @code{Octave:autoload-relative-file-name} warning is 863enabled. 864 865@item Octave:built-in-variable-assignment 866By default, the @code{Octave:built-in-variable-assignment} warning is 867enabled. 868 869@item Octave:classdef-to-struct 870If the @code{Octave:classdef-to-struct} warning is enabled, a warning 871is issued when a classdef object is forcibly converted into a struct with 872@code{struct (@var{CLASSDEF_OBJ})}. Conversion removes the access 873restrictions from the object and makes private and protected properties 874visible. 875By default, the @code{Octave:classdef-to-struct} warning is enabled. 876 877@item Octave:colon-complex-argument 878If the @code{Octave:colon-complex-argument} warning is enabled, a warning 879is issued when one of the three arguments to the colon operator (base, 880increment, limit) is a complex value. For example, @code{1:3*i} will 881cause a warning to be emitted. 882By default, the @code{Octave:colon-complex-argument} warning is enabled. 883 884@item Octave:colon-nonscalar-argument 885If the @code{Octave:colon-nonscalar-argument} warning is enabled, a warning 886is issued when one of the three arguments to the colon operator (base, 887increment, limit) is not a scalar. For example, @code{1:[3, 5]} will 888cause a warning to be emitted. 889By default, the @code{Octave:colon-nonscalar-argument} warning is enabled. 890 891@item Octave:data-file-in-path 892If the @code{Octave:data-file-in-path} warning is enabled, a warning is 893issued when Octave does not find the target of a file operation such as 894@code{load} or @code{fopen} directly, but is able to locate the file in 895Octave's search @code{path} for files. The warning could indicate that a 896different file target than the programmer intended is being used. 897By default, the @code{Octave:data-file-in-path} warning is enabled. 898 899@item Octave:deprecated-function 900If the @code{Octave:deprecated-function} warning is enabled, a 901warning is issued when Octave encounters a function that is obsolete and 902scheduled for removal from Octave. 903By default, the @code{Octave:deprecated-function} warning is enabled. 904 905@item Octave:deprecated-keyword 906If the @code{Octave:deprecated-keyword} warning is enabled, a 907warning is issued when Octave encounters a keyword that is obsolete and 908scheduled for removal from Octave. 909By default, the @code{Octave:deprecated-keyword} warning is enabled. 910 911@item Octave:deprecated-property 912If the @code{Octave:deprecated-property} warning is enabled, a 913warning is issued when Octave encounters a graphics property that 914is obsolete and scheduled for removal from Octave. 915By default, the @code{Octave:deprecated-property} warning is enabled. 916 917@item Octave:eigs:UnconvergedEigenvalues 918If the @code{Octave:eigs:UnconvergedEigenvalues} warning is enabled then 919the eigs function will issue a warning if the number of calculated 920eigenvalues is less than the number of requested eigenvalues. 921By default, the @code{Octave:eigs:UnconvergedEigenvalues} warning is 922enabled. 923 924@item Octave:empty-index 925If the @code{Octave:empty-index} warning is enabled then Octave will emit a 926warning whenever indexing operators are used without an index, for example 927@code{@var{x}()}. 928By default, the @code{Octave:empty-index} warning is enabled. 929 930@item Octave:erase:chararray 931If the @code{Octave:erase:chararray} warning is enabled then the erase 932function will issue a warning if the input pattern is a character array 933rather than a string or cell array of strings. 934By default, the @code{Octave:erase:chararray} warning is enabled. 935 936@item Octave:function-name-clash 937If the @code{Octave:function-name-clash} warning is enabled, a 938warning is issued when Octave finds that the name of a function 939defined in a function file differs from the name of the file. (If 940the names disagree, the name declared inside the file is ignored.) 941By default, the @code{Octave:function-name-clash} warning is enabled. 942 943@item Octave:future-time-stamp 944If the @code{Octave:future-time-stamp} warning is enabled, Octave 945will print a warning if it finds a function file with a time stamp 946that is in the future. 947By default, the @code{Octave:future-time-stamp} warning is enabled. 948 949@item Octave:glyph-render 950If the @code{Octave:glyph-render} warning is enabled, Octave will 951print a warning if the glyph for a character couldn't be rendered with 952the current font. 953By default, the @code{Octave:glyph-render} warning is enabled. 954 955@item Octave:imag-to-real 956If the @code{Octave:imag-to-real} warning is enabled, a warning is 957printed for implicit conversions of complex numbers to real numbers. 958By default, the @code{Octave:imag-to-real} warning is disabled. 959 960@item Octave:language-extension 961Print warnings when using features that are unique to the Octave 962language and that may still be missing in @sc{matlab}. 963By default, the @code{Octave:language-extension} warning is disabled. 964The @option{--traditional} or @option{--braindead} startup options for 965Octave may also be of use, @pxref{Command Line Options}. 966 967@item Octave:legacy-function 968If the @code{Octave:legacy-function} warning is enabled, a 969warning is issued when Octave encounters a function that @sc{matlab} has 970suggested should be avoided. The function may become obsolete at some 971point in the future and removed, in which case the warning will change to 972@code{Octave:deprecated-function}, and the function will continue to exist 973for two further versions of Octave before being removed. 974By default, the @code{Octave:legacy-function} warning is enabled. 975 976@item Octave:logical-conversion 977By default, the @code{Octave:logical-conversion} warning is enabled. 978 979@item Octave:lu:sparse_input 980If the @code{Octave:lu:sparse_input} warning is enabled, Octave 981will warn when the lu function is called with a sparse input and less than 982four output arguments. In this case, sparsity-preserving column 983permutations are not performed and the result may be inaccurate. 984By default, the @code{Octave:lu:sparse_input} warning is enabled. 985 986@item Octave:missing-glyph 987If the @code{Octave:glyph-render} warning is enabled, Octave will 988print a warning if the current font doesn't provide a glyph for a 989used character. 990By default, the @code{Octave:missing-glyph} warning is enabled. 991 992@item Octave:missing-semicolon 993If the @code{Octave:missing-semicolon} warning is enabled, Octave 994will warn when statements in function definitions don't end in 995semicolons. 996By default the @code{Octave:missing-semicolon} warning is disabled. 997 998@item Octave:mixed-string-concat 999If the @code{Octave:mixed-string-concat} warning is enabled, print a 1000warning when concatenating a mixture of double and single quoted strings. 1001By default, the @code{Octave:mixed-string-concat} warning is disabled. 1002 1003@item Octave:nearly-singular-matrix 1004@itemx Octave:singular-matrix 1005These warnings are emitted if a (nearly) singular matrix is inverted. 1006By default, the @code{Octave:nearly-singular-matrix} and 1007@code{Octave:singular-matrix} warnings are enabled. 1008 1009@item Octave:neg-dim-as-zero 1010If the @code{Octave:neg-dim-as-zero} warning is enabled, print a warning 1011for expressions like 1012 1013@example 1014eye (-1) 1015@end example 1016 1017@noindent 1018By default, the @code{Octave:neg-dim-as-zero} warning is disabled. 1019 1020@item Octave:noninteger-range-as-index 1021By default, the @code{Octave:noninteger-range-as-index} warning is enabled. 1022 1023@item Octave:num-to-str 1024If the @code{Octave:num-to-str} warning is enable, a warning is 1025printed for implicit conversions of numbers to their UTF-8 encoded character 1026equivalents when strings are constructed using a mixture of strings and 1027numbers in matrix notation. For example, 1028 1029@example 1030@group 1031[ "f", 111, 111 ] 1032@result{} "foo" 1033@end group 1034@end example 1035 1036@noindent 1037elicits a warning if the @code{Octave:num-to-str} warning is 1038enabled. By default, the @code{Octave:num-to-str} warning is enabled. 1039 1040@item Octave:possible-matlab-short-circuit-operator 1041If the @code{Octave:possible-matlab-short-circuit-operator} warning 1042is enabled, Octave will warn about using the not short circuiting 1043operators @code{&} and @code{|} inside @code{if} or @code{while} 1044conditions. They normally never short circuit, but they do short 1045circuit when used in a condition. 1046By default, the @code{Octave:possible-matlab-short-circuit-operator} warning 1047is enabled. 1048 1049@item Octave:recursive-path-search 1050If the @code{Octave:recursive-path-search} warning is enabled, Octave 1051will issue a warning if @code{addpath} is used with double trailing 1052slashes. 1053By default, the @code{Octave:recursive-path-search} warning is enabled. 1054 1055@item Octave:remove-init-dir 1056The @code{path} function changes the search path that Octave uses 1057to find functions. It is possible to set the path to a value which 1058excludes Octave's own built-in functions. If the 1059@code{Octave:remove-init-dir} warning is enabled then Octave will warn 1060when the @code{path} function has been used in a way that may render 1061Octave unworkable. 1062By default, the @code{Octave:remove-init-dir} warning is enabled. 1063 1064@item Octave:reload-forces-clear 1065If several functions have been loaded from the same file, Octave must 1066clear all the functions before any one of them can be reloaded. If 1067the @code{Octave:reload-forces-clear} warning is enabled, Octave will 1068warn you when this happens, and print a list of the additional 1069functions that it is forced to clear. 1070By default, the @code{Octave:reload-forces-clear} warning is enabled. 1071 1072@item Octave:separator-insert 1073Print warning if commas or semicolons might be inserted 1074automatically in literal matrices. 1075By default, the @code{Octave:separator-insert} warning is disabled. 1076 1077@item Octave:shadowed-function 1078If the @code{Octave:shadowed-function} warning is enabled, Octave will 1079warn if a path is added to the search path that contains functions 1080that shadow core functions. 1081By default, the @code{Octave:shadowed-function} warning is enabled. 1082 1083@item Octave:single-quote-string 1084Print warning if a single quote character is used to introduce a 1085string constant. 1086By default, the @code{Octave:single-quote-string} warning is disabled. 1087 1088@item Octave:sqrtm:SingularMatrix 1089By default, the @code{Octave:sqrtm:SingularMatrix} warning is enabled. 1090 1091@item Octave:str-to-num 1092If the @code{Octave:str-to-num} warning is enabled, a warning is printed 1093for implicit conversions of strings to their numeric UTF-8 encoded byte 1094sequences. For example, 1095 1096@example 1097@group 1098"abc" + 0 1099@result{} 97 98 99 1100@end group 1101@end example 1102 1103@noindent 1104elicits a warning if the @code{Octave:str-to-num} warning is enabled. 1105By default, the @code{Octave:str-to-num} warning is disabled. 1106 1107@item Octave:text_interpreter 1108If the @code{Octave:text_interpreter} warning is enabled, a warning is 1109printed when the @qcode{"interpreter"} property of a text graphics object 1110is set to the unsupported value of @qcode{"latex"}. Even when enabled, 1111the warning message is printed just once per Octave session. 1112By default, the @code{Octave:glyph-render} warning is enabled. 1113 1114@item Octave:variable-switch-label 1115If the @code{Octave:variable-switch-label} warning is enabled, Octave 1116will print a warning if a switch label is not a constant or constant 1117expression. 1118By default, the @code{Octave:variable-switch-label} warning is disabled. 1119@end table 1120 1121 1122 1123@node Enabling and Disabling Warnings 1124@subsection Enabling and Disabling Warnings 1125 1126The @code{warning} function also allows you to control which warnings 1127are actually printed to the screen. If the @code{warning} function 1128is called with a string argument that is either @qcode{"on"} or @qcode{"off"} 1129all warnings will be enabled or disabled. 1130 1131It is also possible to enable and disable individual warnings through 1132their string identifications. The following code will issue a warning 1133 1134@example 1135@group 1136warning ("example:non-negative-variable", 1137 "'a' must be non-negative. Setting 'a' to zero."); 1138@end group 1139@end example 1140 1141@noindent 1142while the following won't issue a warning 1143 1144@example 1145@group 1146warning ("off", "example:non-negative-variable"); 1147warning ("example:non-negative-variable", 1148 "'a' must be non-negative. Setting 'a' to zero."); 1149@end group 1150@end example 1151