1.1 Running Octave

On most systems, Octave is started with the shell command ‘octave’. This starts the graphical user interface. The central window in the GUI is the Octave command-line interface. In this window Octave displays an initial message and then a prompt indicating it is ready to accept input. If you have chosen the traditional command-line interface then only the command prompt appears in the same window that was running a shell. In either case, you can immediately begin typing Octave commands.

If you get into trouble, you can usually interrupt Octave by typing Control-C (written C-c for short). C-c gets its name from the fact that you type it by holding down CTRL and then pressing c. Doing this will normally return you to Octave’s prompt.

To exit Octave, type quit or exit at the Octave prompt.

On systems that support job control, you can suspend Octave by sending it a SIGTSTP signal, usually by typing C-z.

1.2 Simple Examples

The following chapters describe all of Octave’s features in detail, but before doing that, it might be helpful to give a sampling of some of its capabilities.

If you are new to Octave, we recommend that you try these examples to begin learning Octave by using it. Lines marked like so, ‘octave:13>’, are lines you type, ending each with a carriage return. Octave will respond with an answer, or by displaying a graph.

• Elementary Calculations
• Creating a Matrix
• Matrix Arithmetic
• Solving Systems of Linear Equations
• Integrating Differential Equations
• Producing Graphical Output
• Help and Documentation
• Editing What You Have Typed

 i*pi
e     = -1

octave:1> exp (i*pi)

octave:1> A = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ]

octave:2> B = rand (3, 2);

octave:3> B

octave:4> 2 * A

octave:5> A * B

octave:6> A' * A

x = A \ b

H2 + O2 --> H2O

x1*H2 + x2*O2 --> H2O
H: 2*x1 + 0*x2 --> 2
O: 0*x1 + 2*x2 --> 1

octave:1> A = [ 2, 0; 0, 2 ];
octave:2> b = [ 2; 1 ];
octave:3> x = A \ b

dx
-- = f (x, t)
dt

x(t = t0) = x0

octave:1> function xdot = f (x, t)
>
>  r = 0.25;
>  k = 1.4;
>  a = 1.5;
>  b = 0.16;
>  c = 0.9;
>  d = 0.8;
>
>  xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1));
>  xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2);
>
> endfunction

octave:2> x0 = [1; 2];

octave:3> t = linspace (0, 50, 200)';

octave:4> x = lsode ("f", x0, t);

octave:1> plot (t, x)

print foo.pdf

help print

help plot

1.3 Conventions

This section explains the notation conventions that are used in this manual. You may want to skip this section and refer back to it later.

• Fonts
• Evaluation Notation
• Printing Notation
• Error Messages
• Format of Descriptions

sqrt (2)
     ⇒ 1.4142

[1, 2; 3, 4] == [1, 3; 2, 4]
     ⇒ [ 1, 0; 0, 1 ]

eye (3)
     ⇒  1  0  0
         0  1  0
         0  0  1

rot90 ([1, 2; 3, 4], -1)
≡
rot90 ([1, 2; 3, 4], 3)
≡
rot90 ([1, 2; 3, 4], 7)

printf ("foo %s\n", "bar")
     -| foo bar
     ⇒ 1

fieldnames ([1, 2; 3, 4])
error: fieldnames: Invalid input argument

2.1 Invoking Octave from the Command Line

Normally, Octave is used interactively by running the program ‘octave’ without any arguments. Once started, Octave reads commands from the terminal until you tell it to exit.

You can also specify the name of a file on the command line, and Octave will read and execute the commands from the named file and then exit when it is finished.

You can further control how Octave starts by using the command-line options described in the next section, and Octave itself can remind you of the options available. Type ‘octave --help’ to display all available options and briefly describe their use (‘octave -h’ is a shorter equivalent).

• Command Line Options
• Startup Files

printf ("%s", program_name ());
arg_list = argv ();
for i = 1:nargin
  printf (" %s", arg_list{i});
endfor
printf ("\n");

__mfile_encoding__ ("utf-8");  # set new encoding
clear ("functions");  # re-parse all .m files in the new encoding

2.2 Quitting Octave

Shutdown is initiated with the exit or quit commands (they are equivalent). Similar to startup, Octave has a shutdown process that can be customized by user script files. During shutdown Octave will search for the script file finish.m in the function load path. Commands to save all workspace variables or cleanup temporary files may be placed there. Additional functions to execute on shutdown may be registered with atexit.

: quit ¶

: quit cancel ¶

: quit force ¶

: quit ("cancel") ¶

: quit ("force") ¶

: quit (status) ¶

: quit (status, "force") ¶

Quit the current Octave session.

The exit function is an alias for quit.

If the optional integer value status is supplied, pass that value to the operating system as Octave’s exit status. The default value is zero.

When exiting, Octave will attempt to run the m-file finish.m if it exists. User commands to save the workspace or clean up temporary files may be placed in that file. Alternatively, another m-file may be scheduled to run using atexit. If an error occurs while executing the finish.m file, Octave does not exit and control is returned to the command prompt.

If the optional argument "cancel" is provided, Octave does not exit and control is returned to the command prompt. This feature allows the finish.m file to cancel the quit process.

If the user preference to request confirmation before exiting, Octave will display a dialog and give the user an option to cancel the exit process.

If the optional argument "force" is provided, no confirmation is requested, and the execution of the finish.m file is skipped.

See also: atexit.

: atexit (fcn) ¶

: atexit (fcn, true) ¶

: atexit (fcn, false) ¶

: status = atexit (fcn, false) ¶

Register a function to be called when Octave exits.

For example,

function last_words ()
  disp ("Bye bye");
endfunction
atexit ("last_words");

will print the message "Bye bye" when Octave exits.

The additional argument flag will register or unregister fcn from the list of functions to be called when Octave exits. If flag is true, the function is registered, and if flag is false, it is unregistered. For example, after registering the function last_words above,

atexit ("last_words", false);

will remove the function from the list and Octave will not call last_words when it exits.

The optional output status is only available when unregistering a function. The value is true if the unregistering was successful and false otherwise.

Programming Note: atexit only removes the first occurrence of a function from the list; if a function was placed in the list multiple times with atexit, it must also be removed from the list multiple times.

See also: quit.

2.3 Commands for Getting Help

The entire text of this manual is available from the Octave prompt via the command doc. In addition, the documentation for individual user-written functions and variables is also available via the help command. This section describes the commands used for reading the manual and the documentation strings for user-supplied functions and variables. See Function Files, for more information about how to document the functions you write.

: help name ¶

: help --list ¶

: help . ¶

: help ¶

: help_text = help (…) ¶

Display the help text for name.

For example, the command help help prints a short message describing the help command.

Given the single argument --list, list all operators, keywords, built-in functions, and loadable functions available in the current session of Octave.

Given the single argument ., list all operators available in the current session of Octave.

If invoked without any arguments, help displays instructions on how to access help from the command line.

The help command can provide information about most operators, but name must be enclosed by single or double quotes to prevent the Octave interpreter from acting on name. For example, help "+" displays help on the addition operator.

See also: doc, lookfor, which, info.

: doc function_name ¶

: doc ¶

Display documentation for the function function_name directly from an online version of the printed manual, using the GNU Info browser.

If invoked without an argument, the manual is shown from the beginning.

For example, the command doc rand starts the GNU Info browser at the rand node in the online version of the manual.

Once the GNU Info browser is running, help for using it is available using the command C-h.

See also: help.

: lookfor str ¶

: lookfor -all str ¶

: [fcn, help1str] = lookfor (str) ¶

: [fcn, help1str] = lookfor ("-all", str) ¶

Search for the string str in the documentation of all functions in the current function search path.

By default, lookfor looks for str in just the first sentence of the help string for each function found. The entire help text of each function can be searched by using the "-all" argument. All searches are case insensitive.

When called with no output arguments, lookfor prints the list of matching functions to the terminal. Otherwise, the output argument fcns contains the function names and help1str contains the first sentence from the help string of each function.

Programming Note: The ability of lookfor to correctly identify the first sentence of the help text is dependent on the format of the function’s help. All Octave core functions are correctly formatted, but the same can not be guaranteed for external packages and user-supplied functions. Therefore, the use of the "-all" argument may be necessary to find related functions that are not a part of Octave.

The speed of lookup is greatly enhanced by having a cached documentation file. For more information, see doc_cache_create.

See also: help, doc, which, path, doc_cache_create.

To see what is new in the current release of Octave, use the news function.

: news ¶

: news package ¶

Display the current NEWS file for Octave or an installed package.

When called without an argument, display the NEWS file for Octave.

When given a package name package, display the current NEWS file for that package.

See also: ver, pkg.

: info () ¶

Display contact information for the GNU Octave community.

: warranty () ¶

Describe the conditions for copying and distributing Octave.

The following functions can be used to change which programs are used for displaying the documentation, and where the documentation can be found.

: val = info_file () ¶

: old_val = info_file (new_val) ¶

: old_val = info_file (new_val, "local") ¶

Query or set the internal variable that specifies the name of the Octave info file.

The default value is octave-home/share/info/octave.info, in which octave-home is the root directory of the Octave installation. The default value may be overridden by the environment variable OCTAVE_INFO_FILE, or the command line argument --info-file FNAME.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: info_program, doc, help, makeinfo_program.

: val = info_program () ¶

: old_val = info_program (new_val) ¶

: old_val = info_program (new_val, "local") ¶

Query or set the internal variable that specifies the name of the info program to run.

The default value is info. The default value may be overridden by the environment variable OCTAVE_INFO_PROGRAM, or the command line argument --info-program NAME.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: info_file, doc, help, makeinfo_program.

: val = makeinfo_program () ¶

: old_val = makeinfo_program (new_val) ¶

: old_val = makeinfo_program (new_val, "local") ¶

Query or set the internal variable that specifies the name of the program that Octave runs to format help text containing Texinfo markup commands.

The default value is makeinfo.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: texi_macros_file, info_file, info_program, doc, help.

: val = texi_macros_file () ¶

: old_val = texi_macros_file (new_val) ¶

: old_val = texi_macros_file (new_val, "local") ¶

Query or set the internal variable that specifies the name of the file containing Texinfo macros that are prepended to documentation strings before they are passed to makeinfo.

The default value is octave-home/share/octave/version/etc/macros.texi, in which octave-home is the root directory of the Octave installation, and version is the Octave version number. The default value may be overridden by the environment variable OCTAVE_TEXI_MACROS_FILE, or the command line argument --texi-macros-file FNAME.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: makeinfo_program.

: val = doc_cache_file () ¶

: old_val = doc_cache_file (new_val) ¶

: old_val = doc_cache_file (new_val, "local") ¶

Query or set the internal variable that specifies the name of the Octave documentation cache file.

A cache file significantly improves the performance of the lookfor command. The default value is octave-home/share/octave/version/etc/doc-cache, in which octave-home is the root directory of the Octave installation, and version is the Octave version number. The default value may be overridden by the environment variable OCTAVE_DOC_CACHE_FILE, or the command line argument --doc-cache-file FNAME.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: doc_cache_create, lookfor, info_program, doc, help, makeinfo_program.

See also: lookfor.

: val = built_in_docstrings_file () ¶

: old_val = built_in_docstrings_file (new_val) ¶

: old_val = built_in_docstrings_file (new_val, "local") ¶

Query or set the internal variable that specifies the name of the file containing docstrings for built-in Octave functions.

The default value is octave-home/share/octave/version/etc/built-in-docstrings, in which octave-home is the root directory of the Octave installation, and version is the Octave version number. The default value may be overridden by the environment variable OCTAVE_BUILT_IN_DOCSTRINGS_FILE, or the command line argument --built-in-docstrings-file FNAME.

Note: This variable is only used when Octave is initializing itself. Modifying it during a running session of Octave will have no effect.

: val = suppress_verbose_help_message () ¶

: old_val = suppress_verbose_help_message (new_val) ¶

: old_val = suppress_verbose_help_message (new_val, "local") ¶

Query or set the internal variable that controls whether Octave will add additional help information to the end of the output from the help command and usage messages for built-in commands.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

The following functions are principally used internally by Octave for generating the documentation. They are documented here for completeness and because they may occasionally be useful for users.

: doc_cache_create (out_file, directory) ¶

: doc_cache_create (out_file) ¶

: doc_cache_create () ¶

Generate documentation cache for all functions in directory.

A documentation cache is generated for all functions in directory which may be a single string or a cell array of strings. The cache is used to speed up the function lookfor.

The cache is saved in the file out_file which defaults to the value doc-cache if not given.

If no directory is given (or it is the empty matrix), a cache for built-in functions, operators, and keywords is generated.

See also: doc_cache_file, lookfor, path.

: [text, format] = get_help_text (name) ¶

Return the raw help text of function name.

The raw help text is returned in text and the format in format. The format is a string which is one of "texinfo", "html", or "plain text".

See also: get_help_text_from_file.

: [text, format] = get_help_text_from_file (fname) ¶

Return the raw help text from the file fname.

The raw help text is returned in text and the format in format. The format is a string which is one of "texinfo", "html", or "plain text".

See also: get_help_text.

: text = get_first_help_sentence (name) ¶

: text = get_first_help_sentence (name, max_len) ¶

: [text, status] = get_first_help_sentence (…) ¶

Return the first sentence of a function’s help text.

The first sentence is defined as the text after the function declaration until either the first period (".") or the first appearance of two consecutive newlines ("\n\n"). The text is truncated to a maximum length of max_len, which defaults to 80. If the text must be truncated the last three characters of the text are replaced with "..." to indicate that more text was available.

The optional output argument status returns the status reported by makeinfo. If only one output argument is requested, and status is nonzero, a warning is displayed.

As an example, the first sentence of this help text is

get_first_help_sentence ("get_first_help_sentence")
-| ans = Return the first sentence of a function's help text.

2.4 Command Line Editing

Octave uses the GNU Readline library to provide an extensive set of command-line editing and history features. Only the most common features are described in this manual. In addition, all of the editing functions can be bound to different key strokes at the user’s discretion. This manual assumes no changes from the default Emacs bindings. See the GNU Readline Library manual for more information on customizing Readline and for a complete feature list.

To insert printing characters (letters, digits, symbols, etc.), simply type the character. Octave will insert the character at the cursor and advance the cursor forward.

Many of the command-line editing functions operate using control characters. For example, the character Control-a moves the cursor to the beginning of the line. To type C-a, hold down CTRL and then press a. In the following sections, control characters such as Control-a are written as C-a.

Another set of command-line editing functions use Meta characters. To type M-u, hold down the META key and press u. Depending on the keyboard, the META key may be labeled ALT or even WINDOWS. If your terminal does not have a META key, you can still type Meta characters using two-character sequences starting with ESC. Thus, to enter M-u, you would type ESC u. The ESC character sequences are also allowed on terminals with real Meta keys. In the following sections, Meta characters such as Meta-u are written as M-u.

• Cursor Motion
• Killing and Yanking
• Commands for Changing Text
• Letting Readline Type for You
• Commands for Manipulating the History
• Customizing readline
• Customizing the Prompt
• Diary and Echo Commands

2.5 How Octave Reports Errors

Octave reports two kinds of errors for invalid programs.

A parse error occurs if Octave cannot understand something you have typed. For example, if you misspell a keyword,

octave:13> function z = f (x, y) z = x ||| 2; endfunction

Octave will respond immediately with a message like this:

parse error:

  syntax error

>>> function z = f (x, y) z = x ||| y; endfunction
                                  ^

For most parse errors, Octave uses a caret (‘^’) to mark the point on the line where it was unable to make sense of your input. In this case, Octave generated an error message because the keyword for the logical or operator (||) was misspelled. It marked the error at the third ‘|’ because the code leading up to this was correct but the final ‘|’ was not understood.

Another class of error message occurs at evaluation time. These errors are called run-time errors, or sometimes evaluation errors, because they occur when your program is being run, or evaluated. For example, if after correcting the mistake in the previous function definition, you type

octave:13> f ()

Octave will respond with

error: `x' undefined near line 1 column 24
error: called from:
error:   f at line 1, column 22

This error message has several parts, and gives quite a bit of information to help you locate the source of the error. The messages are generated from the point of the innermost error, and provide a traceback of enclosing expressions and function calls.

In the example above, the first line indicates that a variable named ‘x’ was found to be undefined near line 1 and column 24 of some function or expression. For errors occurring within functions, lines are counted from the beginning of the file containing the function definition. For errors occurring outside of an enclosing function, the line number indicates the input line number, which is usually displayed in the primary prompt string.

The second and third lines of the error message indicate that the error occurred within the function f. If the function f had been called from within another function, for example, g, the list of errors would have ended with one more line:

error:   g at line 1, column 17

These lists of function calls make it fairly easy to trace the path your program took before the error occurred, and to correct the error before trying again.

2.6 Executable Octave Programs

Once you have learned Octave, you may want to write self-contained Octave scripts, using the ‘#!’ script mechanism. You can do this on GNU systems and on many Unix systems ¹.

Self-contained Octave scripts are useful when you want to write a program which users can invoke without knowing that the program is written in the Octave language. Octave scripts are also used for batch processing of data files. Once an algorithm has been developed and tested in the interactive portion of Octave, it can be committed to an executable script and used again and again on new data files.

As a trivial example of an executable Octave script, you might create a text file named hello, containing the following lines:

#! octave-interpreter-name -qf
# a sample Octave program
printf ("Hello, world!\n");

(where octave-interpreter-name should be replaced with the full path and name of your Octave binary). Note that this will only work if ‘#!’ appears at the very beginning of the file. After making the file executable (with the chmod command on Unix systems), you can simply type:

hello

at the shell, and the system will arrange to run Octave as if you had typed:

octave hello

The line beginning with ‘#!’ lists the full path and filename of an interpreter to be run, and an optional initial command line argument to pass to that interpreter. The operating system then runs the interpreter with the given argument and the full argument list of the executed program. The first argument in the list is the full filename of the Octave executable. The rest of the argument list will either be options to Octave, or data files, or both. The ‘-qf’ options are usually specified in stand-alone Octave programs to prevent them from printing the normal startup message, and to keep them from behaving differently depending on the contents of a particular user’s ~/.octaverc file. See Invoking Octave from the Command Line.

Note that some operating systems may place a limit on the number of characters that are recognized after ‘#!’. Also, the arguments appearing in a ‘#!’ line are parsed differently by various shells/systems. The majority of them group all the arguments together in one string and pass it to the interpreter as a single argument. In this case, the following script:

#! octave-interpreter-name -q -f # comment

is equivalent to typing at the command line:

octave "-q -f # comment"

which will produce an error message. Unfortunately, it is not possible for Octave to determine whether it has been called from the command line or from a ‘#!’ script, so some care is needed when using the ‘#!’ mechanism.

• Passing Arguments to Executable Scripts
• Dual-Purpose Executable Scripts and Octave Functions

#! /bin/octave -qf
printf ("%s", program_name ());
arg_list = argv ();
for i = 1:nargin
  printf (" %s", arg_list{i});
endfor
printf ("\n");

#! /bin/octave -qf
function retval = mysin (x = str2double (argv(){end}))
  retval = sin (x)
endfunction

mysin.m 1.5

mysin (1.5)

2.7 Comments in Octave Programs

A comment is some text that is included in a program for the sake of human readers, and which is NOT an executable part of the program. Comments can explain what the program does, and how it works. Nearly all programming languages have provisions for comments, because programs are typically hard to understand without them.

• Single Line Comments
• Block Comments
• Comments and the Help System

function countdown
  # Count down for main rocket engines
  disp (3);
  disp (2);
  disp (1);
  disp ("Blast Off!");  # Rocket leaves pad
endfunction

function quick_countdown
  # Count down for main rocket engines
  disp (3);
 #{
  disp (2);
  disp (1);
 #}
  disp ("Blast Off!");  # Rocket leaves pad
endfunction

function xdot = f (x, t)

# usage: f (x, t)
#
# This function defines the right-hand
# side functions for a set of nonlinear
# differential equations.

  r = 0.25;
  …
endfunction

 usage: f (x, t)

 This function defines the right-hand
 side functions for a set of nonlinear
 differential equations.

3.1 Built-in Data Types

The standard built-in data types are real and complex scalars and matrices, ranges, character strings, a data structure type, and cell arrays. Additional built-in data types may be added in future versions. If you need a specialized data type that is not currently provided as a built-in type, you are encouraged to write your own user-defined data type and contribute it for distribution in a future release of Octave.

The data type of a variable can be determined and changed through the use of the following functions.

: classname = class (obj) ¶

: cls = class (s, classname) ¶

: cls = class (s, classname, parent1, …) ¶

Return the class of the object obj, or create a class with fields from structure s and name (string) classname.

Additional arguments name a list of parent classes from which the new class is derived.

See also: typeinfo, isa.

: tf = isa (obj, classname) ¶

Return true if obj is an object from the class classname.

classname may also be one of the following class categories:

"float"

Floating point value comprising classes "double" and "single".

"integer"

Integer value comprising classes (u)int8, (u)int16, (u)int32, (u)int64.

"numeric"

Numeric value comprising either a floating point or integer value.

If classname is a cell array of string, a logical array of the same size is returned, containing true for each class to which obj belongs to.

See also: class, typeinfo.

: y = cast (x, "type") ¶

: y = cast (x, "like", var) ¶

Convert x to data type type.

The input x may be a scalar, vector, or matrix of a class that is convertible to the target class (see below).

If a variable var is specified after "like", x is converted to the same data type and sparsity attribute. If var is complex, x will be complex, too.

var may be and type may name any of the following built-in numeric classes:

"double"
"single"
"logical"
"char"
"int8"
"int16"
"int32"
"int64"
"uint8"
"uint16"
"uint32"
"uint64"

The value x may be modified to fit within the range of the new type.

Examples:

cast (-5, "uint8")
   ⇒ 0
cast (300, "int8")
   ⇒ 127

Programming Note: This function relies on the object x having a conversion method named type. User-defined classes may implement only a subset of the full list of types shown above. In that case, it may be necessary to call cast twice in order to reach the desired type. For example, the conversion to double is nearly always implemented, but the conversion to uint8 might not be. In that case, the following code will work:

cast (cast (user_defined_val, "double"), "uint8")

See also: typecast, int8, uint8, int16, uint16, int32, uint32, int64, uint64, double, single, logical, char, class, typeinfo.

: y = typecast (x, "class") ¶

Return a new array y resulting from interpreting the data of x in memory as data of the numeric class class.

Both the class of x and class must be one of the built-in numeric classes:

"logical"
"char"
"int8"
"int16"
"int32"
"int64"
"uint8"
"uint16"
"uint32"
"uint64"
"double"
"single"
"double complex"
"single complex"

the last two are only used with class; they indicate that a complex-valued result is requested. Complex arrays are stored in memory as consecutive pairs of real numbers. The sizes of integer types are given by their bit counts. Both logical and char are typically one byte wide; however, this is not guaranteed by C++. If your system is IEEE conformant, single and double will be 4 bytes and 8 bytes wide, respectively. "logical" is not allowed for class.

If the input is a row vector, the return value is a row vector, otherwise it is a column vector.

If the bit length of x is not divisible by that of class, an error occurs.

An example of the use of typecast on a little-endian machine is

x = uint16 ([1, 65535]);
typecast (x, "uint8")
⇒ [   1,   0, 255, 255]

See also: cast, bitpack, bitunpack, swapbytes.

: y = swapbytes (x) ¶

Swap the byte order on values, converting from little endian to big endian and vice versa.

For example:

swapbytes (uint16 (1:4))
⇒   256   512   768  1024

See also: typecast, cast.

: y = bitpack (x, class) ¶

Return a new array y resulting from interpreting the logical array x as raw bit patterns for data of the numeric class class.

class must be one of the built-in numeric classes:

"double"
"single"
"double complex"
"single complex"
"char"
"int8"
"int16"
"int32"
"int64"
"uint8"
"uint16"
"uint32"
"uint64"

The number of elements of x should be divisible by the bit length of class. If it is not, excess bits are discarded. Bits come in increasing order of significance, i.e., x(1) is bit 0, x(2) is bit 1, etc.

The result is a row vector if x is a row vector, otherwise it is a column vector.

See also: bitunpack, typecast.

: y = bitunpack (x) ¶

Return a logical array y corresponding to the raw bit patterns of x.

x must belong to one of the built-in numeric classes:

"double"
"single"
"char"
"int8"
"int16"
"int32"
"int64"
"uint8"
"uint16"
"uint32"
"uint64"

The result is a row vector if x is a row vector; otherwise, it is a column vector.

See also: bitpack, typecast.

• Numeric Objects
• Missing Data
• String Objects
• Data Structure Objects
• Cell Array Objects

3.2 User-defined Data Types

Someday I hope to expand this to include a complete description of Octave’s mechanism for managing user-defined data types. Until this feature is documented here, you will have to make do by reading the code in the ov.h, ops.h, and related files from Octave’s src directory.

3.3 Object Sizes

The following functions allow you to determine the size of a variable or expression. These functions are defined for all objects. They return −1 when the operation doesn’t make sense. For example, Octave’s data structure type doesn’t have rows or columns, so the rows and columns functions return −1 for structure arguments.

: n = ndims (A) ¶

Return the number of dimensions of A.

For any array, the result will always be greater than or equal to 2. Trailing singleton dimensions are not counted, i.e., trailing dimensions d greater than 2 for which size (A, d) = 1.

ndims (ones (4, 1, 2, 1))
    ⇒ 3

See also: size.

: nc = columns (A) ¶

Return the number of columns of A.

This is equivalent to size (A, 2).

See also: rows, size, length, numel, isscalar, isvector, ismatrix.

: nr = rows (A) ¶

Return the number of rows of A.

This is equivalent to size (A, 1).

See also: columns, size, length, numel, isscalar, isvector, ismatrix.

: n = numel (A) ¶

: n = numel (A, idx1, idx2, …) ¶

Return the number of elements in the object A.

Optionally, if indices idx1, idx2, … are supplied, return the number of elements that would result from the indexing

A(idx1, idx2, …)

Note that the indices do not have to be scalar numbers. For example,

a = 1;
b = ones (2, 3);
numel (a, b)

will return 6, as this is the number of ways to index with b. Or the index could be the string ":" which represents the colon operator. For example,

A = ones (5, 3);
numel (A, 2, ":")

will return 3 as the second row has three column entries.

This method is also called when an object appears as lvalue with cs-list indexing, i.e., object{…} or object(…).field.

See also: size, length, ndims.

: n = length (A) ¶

Return the length of the object A.

The length is 0 for empty objects, 1 for scalars, and the number of elements for vectors. For matrix or N-dimensional objects, the length is the number of elements along the largest dimension (equivalent to max (size (A))).

See also: numel, size.

: sz = size (A) ¶

: dim_sz = size (A, dim) ¶

: dim_sz = size (A, d1, d2, …) ¶

: [rows, cols, …, dim_N_sz] = size (…) ¶

Return a row vector with the size (number of elements) of each dimension for the object A.

When given a second argument, dim, return the size of the corresponding dimension. If dim is a vector, return each of the corresponding dimensions. Multiple dimensions may also be specified as separate arguments.

With a single output argument, size returns a row vector. When called with multiple output arguments, size returns the size of dimension N in the Nth argument. The number of rows, dimension 1, is returned in the first argument, the number of columns, dimension 2, is returned in the second argument, etc. If there are more dimensions in A than there are output arguments, size returns the total number of elements in the remaining dimensions in the final output argument.

Example 1: single row vector output

size ([1, 2; 3, 4; 5, 6])
   ⇒ [ 3, 2 ]

Example 2: number of elements in 2nd dimension (columns)

size ([1, 2; 3, 4; 5, 6], 2)
    ⇒ 2

Example 3: number of output arguments == number of dimensions

[nr, nc] = size ([1, 2; 3, 4; 5, 6])
    ⇒ nr = 3
    ⇒ nc = 2

Example 4: number of output arguments < number of dimensions

[nr, remainder] = size (ones (2, 3, 4, 5))
    ⇒ nr = 2
    ⇒ remainder = 60

See also: numel, ndims, length, rows, columns, size_equal, common_size.

: tf = isempty (A) ¶

Return true if A is an empty matrix (any one of its dimensions is zero).

See also: isnull, isa.

: tf = isnull (x) ¶

Return true if x is a special null matrix, string, or single quoted string.

Indexed assignment with such a null value on the right-hand side should delete array elements. This function is used in place of isempty when overloading the indexed assignment method (subsasgn) for user-defined classes. isnull is used to distinguish between these two cases:

A(I) = []

and

X = []; A(I) = X

In the first assignment, the right-hand side is [] which is a special null value. As long as the index I is not empty, this code should delete elements from A rather than perform assignment.

In the second assignment, the right-hand side is empty (because X is []), but it is not null. This code should assign the empty value to elements in A.

An example from Octave’s built-in char class demonstrates the interpreter behavior when isnull is used correctly.

str = "Hello World";
nm = "Wally";
str(7:end) = nm                # indexed assignment
  ⇒ str = Hello Wally
str(7:end) = ""                # indexed deletion
  ⇒ str = Hello

See also: isempty, isindex.

: sz = sizeof (val) ¶

Return the size of val in bytes.

See also: whos.

: TF = size_equal (A, B) ¶

: TF = size_equal (A, B, …) ¶

Return true if the dimensions of all arguments agree.

Trailing singleton dimensions are ignored. When called with a single argument, or no argument, size_equal returns true.

See also: size, numel, ndims, common_size.

: B = squeeze (A) ¶

Remove singleton dimensions from A and return the result.

Note that for compatibility with MATLAB, all objects have a minimum of two dimensions and row vectors are left unchanged.

See also: reshape.

4.1 Matrices

It is easy to define a matrix of values in Octave. The size of the matrix is determined automatically, so it is not necessary to explicitly state the dimensions. The expression

a = [1, 2; 3, 4]

results in the matrix

        /      \
        | 1  2 |
  a  =  |      |
        | 3  4 |
        \      /

Elements of a matrix may be arbitrary expressions, provided that the dimensions all make sense when combining the various pieces. For example, given the above matrix, the expression

[ a, a ]

produces the matrix

ans =

  1  2  1  2
  3  4  3  4

but the expression

[ a, 1 ]

produces the error

error: number of rows must match (1 != 2) near line 13, column 6

(assuming that this expression was entered as the first thing on line 13, of course).

Inside the square brackets that delimit a matrix expression, Octave looks at the surrounding context to determine whether spaces and newline characters should be converted into element and row separators, or simply ignored, so an expression like

a = [ 1 2
      3 4 ]

will work. However, some possible sources of confusion remain. For example, in the expression

[ 1 - 1 ]

the ‘-’ is treated as a binary operator and the result is the scalar 0, but in the expression

[ 1 -1 ]

the ‘-’ is treated as a unary operator and the result is the vector [ 1, -1 ]. Similarly, the expression

[ sin (pi) ]

will be parsed as

[ sin, (pi) ]

and will result in an error since the sin function will be called with no arguments. To get around this, you must omit the space between sin and the opening parenthesis, or enclose the expression in a set of parentheses:

[ (sin (pi)) ]

Whitespace surrounding the single quote character (‘'’, used as a transpose operator and for delimiting character strings) can also cause confusion. Given a = 1, the expression

[ 1 a' ]

results in the single quote character being treated as a transpose operator and the result is the vector [ 1, 1 ], but the expression

[ 1 a ' ]

produces the error message

parse error:

  syntax error

>>> [ 1 a ' ]
              ^

because not doing so would cause trouble when parsing the valid expression

[ a 'foo' ]

For clarity, it is probably best to always use commas and semicolons to separate matrix elements and rows.

The maximum number of elements in a matrix is fixed when Octave is compiled. The allowable number can be queried with the function sizemax. Note that other factors, such as the amount of memory available on your machine, may limit the maximum size of matrices to something smaller.

: max_numel = sizemax () ¶

Return the largest value allowed for the size of an array.

If Octave is compiled with 64-bit indexing, the result is of class int64, otherwise it is of class int32. The maximum array size is slightly smaller than the maximum value allowable for the relevant class as reported by intmax.

See also: intmax.

When you type a matrix or the name of a variable whose value is a matrix, Octave responds by printing the matrix in with neatly aligned rows and columns. If the rows of the matrix are too large to fit on the screen, Octave splits the matrix and displays a header before each section to indicate which columns are being displayed. You can use the following variables to control the format of the output.

: val = output_precision () ¶

: old_val = output_precision (new_val) ¶

: old_val = output_precision (new_val, "local") ¶

Query or set the internal variable that specifies the minimum number of significant figures to display for numeric output.

Note that regardless of the value set for output_precision, the number of digits of precision displayed is limited to 16 for double precision values and 7 for single precision values. Also, calls to the format function that change numeric display can also change the set value for output_precision.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: format, fixed_point_format.

It is possible to achieve a wide range of output styles by using different values of output_precision. Reasonable combinations can be set using the format function. See Basic Input and Output.

: val = split_long_rows () ¶

: old_val = split_long_rows (new_val) ¶

: old_val = split_long_rows (new_val, "local") ¶

Query or set the internal variable that controls whether rows of a matrix may be split when displayed to a terminal window.

If the rows are split, Octave will display the matrix in a series of smaller pieces, each of which can fit within the limits of your terminal width and each set of rows is labeled so that you can easily see which columns are currently being displayed. For example:

octave:13> rand (2,10)
ans =

 Columns 1 through 6:

  0.75883  0.93290  0.40064  0.43818  0.94958  0.16467
  0.75697  0.51942  0.40031  0.61784  0.92309  0.40201

 Columns 7 through 10:

  0.90174  0.11854  0.72313  0.73326
  0.44672  0.94303  0.56564  0.82150

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: format.

Octave automatically switches to scientific notation when values become very large or very small. This guarantees that you will see several significant figures for every value in a matrix. If you would prefer to see all values in a matrix printed in a fixed point format, you can use the function fixed_point_format. But doing so is not recommended, because it can produce output that can easily be misinterpreted.

: val = fixed_point_format () ¶

: old_val = fixed_point_format (new_val) ¶

: old_val = fixed_point_format (new_val, "local") ¶

Query or set the internal variable that controls whether Octave will use a scaled format to print matrix values.

The scaled format prints a scaling factor on the first line of output chosen such that the largest matrix element can be written with a single leading digit. For example:

fixed_point_format (true)
logspace (1, 7, 5)'
ans =

  1.0e+07  *

  0.00000
  0.00003
  0.00100
  0.03162
  1.00000

Notice that the first value appears to be 0 when it is actually 1. Because of the possibility for confusion you should be careful about enabling fixed_point_format.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: format, output_precision.

• Empty Matrices

s * [](mxn) = [](mxn) * s = [](mxn)

    [](mxn) + [](mxn) = [](mxn)

    [](0xm) *  M(mxn) = [](0xn)

     M(mxn) * [](nx0) = [](mx0)

    [](mx0) * [](0xn) =  0(mxn)

4.2 Ranges

A range is a convenient way to write a row vector with evenly spaced elements. A range expression is defined by the value of the first element in the range, an optional value for the increment between elements, and a maximum value which the elements of the range will not exceed. The base, increment, and limit are separated by colons (the ‘:’ character) and may contain any arithmetic expressions and function calls. If the increment is omitted, it is assumed to be 1. For example, the range

1 : 5

defines the set of values [ 1, 2, 3, 4, 5 ], and the range

1 : 3 : 5

defines the set of values [ 1, 4 ].

Although a range constant specifies a row vector, Octave does not normally convert range constants to vectors unless it is necessary to do so. This allows you to write a constant like 1 : 10000 without using 80,000 bytes of storage on a typical 32-bit workstation.

A common example of when it does become necessary to convert ranges into vectors occurs when they appear within a vector (i.e., inside square brackets). For instance, whereas

x = 0 : 0.1 : 1;

defines x to be a variable of type range and occupies 24 bytes of memory, the expression

y = [ 0 : 0.1 : 1];

defines y to be of type matrix and occupies 88 bytes of memory.

This space saving optimization may be disabled using the function optimize_range.

: val = optimize_range () ¶

: old_val = optimize_range (new_val) ¶

: old_val = optimize_range (new_val, "local") ¶

Query or set whether a special space-efficient format is used for storing ranges.

The default value is true. If this option is set to false, Octave will store ranges as full matrices.

When called from inside a function with the "local" option, the setting is changed locally for the function and any subroutines it calls. The original setting is restored when exiting the function.

See also: optimize_diagonal_matrix, optimize_permutation_matrix.

Note that the upper (or lower, if the increment is negative) bound on the range is not always included in the set of values, and that ranges defined by floating point values can produce surprising results because Octave uses floating point arithmetic to compute the values in the range. If it is important to include the endpoints of a range and the number of elements is known, you should use the linspace function instead (see Special Utility Matrices).

When adding a scalar to a range, subtracting a scalar from it (or subtracting a range from a scalar) and multiplying by scalar, Octave will attempt to avoid unpacking the range and keep the result as a range, too, if it can determine that it is safe to do so. For instance, doing

a = 2*(1:1e7) - 1;

will produce the same result as 1:2:2e7-1, but without ever forming a vector with ten million elements.

Using zero as an increment in the colon notation, as 1:0:1 is not allowed, because a division by zero would occur in determining the number of range elements. However, ranges with zero increment (i.e., all elements equal) are useful, especially in indexing, and Octave allows them to be constructed using the built-in function ones. Note that because a range must be a row vector, ones (1, 10) produces a range, while ones (10, 1) does not.

When Octave parses a range expression, it examines the elements of the expression to determine whether they are all constants. If they are, it replaces the range expression with a single range constant.

4.3 Single Precision Data Types

Octave includes support for single precision data types, and most of the functions in Octave accept single precision values and return single precision answers. A single precision variable is created with the single function.

: y = single (x) ¶

Convert x to single precision type.

See also: double.

for example:

sngl = single (rand (2, 2))
     ⇒ sngl =
        0.37569   0.92982
        0.11962   0.50876
class (sngl)
    ⇒ single

Many functions can also return single precision values directly. For example

ones (2, 2, "single")
zeros (2, 2, "single")
eye (2, 2,  "single")
rand (2, 2, "single")
NaN (2, 2, "single")
NA (2, 2, "single")
Inf (2, 2, "single")

will all return single precision matrices.

4.4 Integer Data Types

Octave supports integer matrices as an alternative to using double precision. It is possible to use both signed and unsigned integers represented by 8, 16, 32, or 64 bits. It should be noted that most computations require floating point data, meaning that integers will often change type when involved in numeric computations. For this reason integers are most often used to store data, and not for calculations.

In general most integer matrices are created by casting existing matrices to integers. The following example shows how to cast a matrix into 32 bit integers.

float = rand (2, 2)
     ⇒ float = 0.37569   0.92982
                0.11962   0.50876
integer = int32 (float)
     ⇒ integer = 0  1
                  0  1

As can be seen, floating point values are rounded to the nearest integer when converted.

: tf = isinteger (x) ¶

Return true if x is an integer object (int8, uint8, int16, etc.).

Note that isinteger (14) is false because numeric constants in Octave are double precision floating point values.

See also: isfloat, ischar, islogical, isstring, isnumeric, isa.

: y = int8 (x) ¶

Convert x to 8-bit integer type.

See also: uint8, int16, uint16, int32, uint32, int64, uint64.

: y = uint8 (x) ¶

Convert x to unsigned 8-bit integer type.

See also: int8, int16, uint16, int32, uint32, int64, uint64.

: y = int16 (x) ¶

Convert x to 16-bit integer type.

See also: int8, uint8, uint16, int32, uint32, int64, uint64.

: y = uint16 (x) ¶

Convert x to unsigned 16-bit integer type.

See also: int8, uint8, int16, int32, uint32, int64, uint64.

: y = int32 (x) ¶

Convert x to 32-bit integer type.

See also: int8, uint8, int16, uint16, uint32, int64, uint64.

: y = uint32 (x) ¶

Convert x to unsigned 32-bit integer type.

See also: int8, uint8, int16, uint16, int32, int64, uint64.

: y = int64 (x) ¶

Convert x to 64-bit integer type.

See also: int8, uint8, int16, uint16, int32, uint32, uint64.

: y = uint64 (x) ¶

Convert x to unsigned 64-bit integer type.

See also: int8, uint8, int16, uint16, int32, uint32, int64.

: Imax = intmax () ¶

: Imax = intmax ("type") ¶

: Imax = intmax (var) ¶

Return the largest integer that can be represented by a specific integer type.

The input is either a string "type" specifying an integer type, or it is an existing integer variable var.

Possible values for type are

"int8"

signed 8-bit integer.

"int16"

signed 16-bit integer.

"int32"

signed 32-bit integer.

"int64"

signed 64-bit integer.

"uint8"

unsigned 8-bit integer.

"uint16"

unsigned 16-bit integer.

"uint32"

unsigned 32-bit integer.

"uint64"

unsigned 64-bit integer.

The default for type is "int32".

Example Code - query an existing variable

x = int8 (1);
intmax (x)
  ⇒ 127

See also: intmin, flintmax.

: Imin = intmin () ¶

: Imin = intmin ("type") ¶

: Imin = intmin (var) ¶

Return the smallest integer that can be represented by a specific integer type.

The input is either a string "type" specifying an integer type, or it is an existing integer variable var.

Possible values for type are

"int8"

signed 8-bit integer.

"int16"

signed 16-bit integer.

"int32"

signed 32-bit integer.

"int64"

signed 64-bit integer.

"uint8"

unsigned 8-bit integer.

"uint16"

unsigned 16-bit integer.

"uint32"

unsigned 32-bit integer.

"uint64"

unsigned 64-bit integer.

The default for type is "int32".

Example Code - query an existing variable

x = int8 (1);
intmin (x)
  ⇒ -128

See also: intmax, flintmax.

: Imax = flintmax () ¶

: Imax = flintmax ("double") ¶

: Imax = flintmax ("single") ¶

: Imax = flintmax (var) ¶

Return the largest integer that can be represented consecutively in a floating point value.

The input is either a string specifying a floating point type, or it is an existing floating point variable var.

The default type is "double", but "single" is a valid option. On IEEE 754 compatible systems, flintmax is 2^{53} for "double" and 2^{24} for "single".

Example Code - query an existing variable

x = single (1);
flintmax (x)
  ⇒ 16777216

See also: intmax, realmax, realmin.

• Integer Arithmetic

4.5 Bit Manipulations

Octave provides a number of functions for the manipulation of numeric values on a bit by bit basis. The basic functions to set and obtain the values of individual bits are bitset and bitget.

: B = bitset (A, n) ¶

: B = bitset (A, n, val) ¶

Set or reset bit(s) at position n of the unsigned integers in A.

The least significant bit is n = 1. val = 0 resets bits and val = 1 sets bits. If no val is specified it defaults to 1 (set bit). All inputs must be the same size or scalars.

Example 1: Set multiple bits

x = bitset (1, 3:5)
  ⇒ x =

   5    9   17

dec2bin (x)
  ⇒
     00101
     01001
     10001

Example 2: Reset and set bits

x = bitset ([15 14], 1, [0 1])
  ⇒ x =

   14    15

See also: bitand, bitor, bitxor, bitget, bitcmp, bitshift, intmax, flintmax.

: b = bitget (A, n) ¶

Return the bit value at position(s) n of the unsigned integers in A.

The least significant bit is n = 1.

bitget (100, 8:-1:1)
⇒ 0  1  1  0  0  1  0  0

See also: bitand, bitor, bitxor, bitset, bitcmp, bitshift, intmax, flintmax.

The arguments to all of Octave’s bitwise operations can be scalar or arrays, except for bitcmp, whose k argument must a scalar. In the case where more than one argument is an array, then all arguments must have the same shape, and the bitwise operator is applied to each of the elements of the argument individually. If at least one argument is a scalar and one an array, then the scalar argument is duplicated. Therefore

bitget (100, 8:-1:1)

is the same as

bitget (100 * ones (1, 8), 8:-1:1)

It should be noted that all values passed to the bit manipulation functions of Octave are treated as integers. Therefore, even though the example for bitset above passes the floating point value 10, it is treated as the bits [1, 0, 1, 0] rather than the bits of the native floating point format representation of 10.

As the maximum value that can be represented by a number is important for bit manipulation, particularly when forming masks, Octave supplies two utility functions: flintmax for floating point integers, and intmax for integer objects (uint8, int64, etc.).

Octave also includes the basic bitwise ’and’, ’or’, and ’exclusive or’ operators.

: z = bitand (x, y) ¶

Return the bitwise AND of non-negative integers.

x, y must be in the range [0,intmax]

See also: bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax.

: z = bitor (x, y) ¶

Return the bitwise OR of non-negative integers x and y.

See also: bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax.

: z = bitxor (x, y) ¶

Return the bitwise XOR of non-negative integers x and y.

See also: bitand, bitor, bitset, bitget, bitcmp, bitshift, intmax, flintmax.

The bitwise ’not’ operator is a unary operator that performs a logical negation of each of the bits of the value. For this to make sense, the mask against which the value is negated must be defined. Octave’s bitwise ’not’ operator is bitcmp.

: C = bitcmp (A, k) ¶

Return the k-bit complement of integers in A.

If k is omitted k = log2 (flintmax) + 1 is assumed.

bitcmp (7,4)
  ⇒ 8
dec2bin (11)
  ⇒ 1011
dec2bin (bitcmp (11, 6))
  ⇒ 110100

See also: bitand, bitor, bitxor, bitset, bitget, bitcmp, bitshift, flintmax.

Octave also includes the ability to left-shift and right-shift values bitwise.

: B = bitshift (A, k) ¶

: B = bitshift (A, k, n) ¶

Return a k bit shift of n-digit unsigned integers in A.

A positive k leads to a left shift; A negative value to a right shift.

If n is omitted it defaults to 64. n must be in the range [1,64].

bitshift (eye (3), 1)
⇒

2 0 0
0 2 0
0 0 2

bitshift (10, [-2, -1, 0, 1, 2])
⇒ 2   5  10  20  40

See also: bitand, bitor, bitxor, bitset, bitget, bitcmp, intmax, flintmax.

Bits that are shifted out of either end of the value are lost. Octave also uses arithmetic shifts, where the sign bit of the value is kept during a right shift. For example:

bitshift (-10, -1)
⇒ -5
bitshift (int8 (-1), -1)
⇒ -1

Note that bitshift (int8 (-1), -1) is -1 since the bit representation of -1 in the int8 data type is [1, 1, 1, 1, 1, 1, 1, 1].

4.6 Logical Values

Octave has built-in support for logical values, i.e., variables that are either true or false. When comparing two variables, the result will be a logical value whose value depends on whether or not the comparison is true.

The basic logical operations are &, |, and !, which correspond to “Logical And”, “Logical Or”, and “Logical Negation”. These operations all follow the usual rules of logic.

It is also possible to use logical values as part of standard numerical calculations. In this case true is converted to 1, and false to 0, both represented using double precision floating point numbers. So, the result of true*22 - false/6 is 22.

Logical values can also be used to index matrices and cell arrays. When indexing with a logical array the result will be a vector containing the values corresponding to true parts of the logical array. The following example illustrates this.

data = [ 1, 2; 3, 4 ];
idx = (data <= 2);
data(idx)
     ⇒ ans = [ 1; 2 ]

Instead of creating the idx array it is possible to replace data(idx) with data( data <= 2 ) in the above code.

Logical values can also be constructed by casting numeric objects to logical values, or by using the true or false functions.

: TF = logical (x) ¶

Convert the numeric object x to logical type.

Any nonzero values will be converted to true (1) while zero values will be converted to false (0). The non-numeric value NaN cannot be converted and will produce an error.

Compatibility Note: Octave accepts complex values as input, whereas MATLAB issues an error.

See also: double, single, char.

: val = true (x) ¶

: val = true (n, m) ¶

: val = true (n, m, k, …) ¶

: val = true (…, "like", var) ¶

Return a matrix or N-dimensional array whose elements are all logical 1.

If invoked with a single scalar integer argument, return a square matrix of the specified size.

If invoked with two or more scalar integer arguments, or a vector of integer values, return an array with given dimensions.

If a logical variable var is specified after "like", the output val will have the same sparsity as var.

See also: false.

: val = false (x) ¶

: val = false (n, m) ¶

: val = false (n, m, k, …) ¶

: val = false (…, "like", var) ¶

Return a matrix or N-dimensional array whose elements are all logical 0.

If invoked with a single scalar integer argument, return a square matrix of the specified size.

If invoked with two or more scalar integer arguments, or a vector of integer values, return an array with given dimensions.

If a logical variable var is specified after "like", the output val will have the same sparsity as var.

See also: true.

4.7 Automatic Conversion of Data Types

Many operators and functions can work with mixed data types. For example,

uint8 (1) + 1
    ⇒ 2

single (1) + 1
    ⇒ 2

min (single (1), 0)
   ⇒ 0

where the results are respectively of types uint8, single, and single respectively. This is done for MATLAB compatibility. Valid mixed operations are defined as follows:

When functions expect a double but are passed other types, automatic conversion is function-dependent:

a = det (int8 ([1 2; 3 4]))
    ⇒ a = -2
class (a)
    ⇒ double

a = eig (int8 ([1 2; 3 4]))
    ⇒ error: eig: wrong type argument 'int8 matrix'

When two operands are both integers but of different widths, then some cases convert them to the wider bitwidth, and other cases throw an error:

a = min (int8 (100), int16 (200))
    ⇒ 100
class (a)
    ⇒ int16

int8 (100) + int16 (200)
   ⇒ error: binary operator '+' not implemented
   for 'int8 scalar' by 'int16 scalar' operations

For two integer operands, they typically need to both be signed or both be unsigned. Mixing signed and unsigned usually causes an error, even if they are of the same bitwidth.

min (int16 (100), uint16 (200))
   ⇒ error: min: cannot compute min (int16 scalar, uint16 scalar)

In the case of mixed type indexed assignments, the type is not changed. For example,

x = ones (2, 2);
x(1, 1) = single (2)
   ⇒ x = 2   1
          1   1

where x remains of the double precision type.

4.8 Predicates for Numeric Objects

Since the type of a variable may change during the execution of a program, it can be necessary to do type checking at run-time. Doing this also allows you to change the behavior of a function depending on the type of the input. As an example, this naive implementation of abs returns the absolute value of the input if it is a real number, and the length of the input if it is a complex number.

function a = abs (x)
  if (isreal (x))
    a = sign (x) .* x;
  elseif (iscomplex (x))
    a = sqrt (real(x).^2 + imag(x).^2);
  endif
endfunction

The following functions are available for determining the type of a variable.

: tf = isnumeric (x) ¶

Return true if x is a numeric object, i.e., an integer, real, or complex array.

Logical and character arrays are not considered to be numeric.

See also: isinteger, isfloat, isreal, iscomplex, ischar, islogical, isstring, iscell, isstruct, isa.

: tf = islogical (x) ¶

: tf = isbool (x) ¶

Return true if x is a logical object.

See also: ischar, isfloat, isinteger, isstring, isnumeric, isa.

: tf = isfloat (x) ¶

Return true if x is a floating-point numeric object.

Objects of class double or single are floating-point objects.

See also: isinteger, ischar, islogical, isnumeric, isstring, isa.

: tf = isreal (x) ¶

Return true if x is a non-complex matrix or scalar.

For compatibility with MATLAB, this includes logical and character matrices.

See also: iscomplex, isnumeric, isa.

: tf = iscomplex (x) ¶

Return true if x is a complex-valued numeric object.

See also: isreal, isnumeric, ischar, isfloat, islogical, isstring, isa.

: tf = ismatrix (x) ¶

Return true if x is a 2-D array.

A matrix is an object with two dimensions (ndims (x) == 2) for which size (x) returns [M, N] with non-negative M and N.

See also: isscalar, isvector, iscell, isstruct, issparse, isa.

: tf = isvector (x) ¶

Return true if x is a vector.

A vector is a 2-D array where one of the dimensions is equal to 1 (either 1xN or Nx1). As a consequence of this definition, a 1x1 array (a scalar) is also a vector.

See also: isscalar, ismatrix, iscolumn, isrow, size.

: tf = isrow (x) ¶

Return true if x is a row vector.

A row vector is a 2-D array for which size (x) returns [1, N] with non-negative N.

See also: iscolumn, isscalar, isvector, ismatrix, size.

: tf = iscolumn (x) ¶

Return true if x is a column vector.

A column vector is a 2-D array for which size (x) returns [N, 1] with non-negative N.

See also: isrow, isscalar, isvector, ismatrix, size.

: tf = isscalar (x) ¶

Return true if x is a scalar.

A scalar is an object with two dimensions for which size (x) returns [1, 1].

See also: isvector, ismatrix, size.

: tf = issquare (x) ¶

Return true if x is a 2-D square array.

A square array is a 2-D object for which size (x) returns [N, N] where N is a non-negative integer.

See also: isscalar, isvector, ismatrix, size.

: tf = issymmetric (A) ¶

: tf = issymmetric (A, tol) ¶

: tf = issymmetric (A, "skew") ¶

: tf = issymmetric (A, "skew", tol) ¶

Return true if A is a symmetric or skew-symmetric matrix within the tolerance specified by tol.

The default tolerance is zero (uses faster code).

The type of symmetry to check may be specified with the additional input "nonskew" (default) for regular symmetry or "skew" for skew-symmetry.

Background: A matrix is symmetric if the transpose of the matrix is equal to the original matrix: A == A.'. If a tolerance is given then symmetry is determined by norm (A - A.', Inf) / norm (A, Inf) < tol.

A matrix is skew-symmetric if the transpose of the matrix is equal to the negative of the original matrix: A == -A.'. If a tolerance is given then skew-symmetry is determined by norm (A + A.', Inf) / norm (A, Inf) < tol.

See also: ishermitian, isdefinite.

: tf = ishermitian (A) ¶

: tf = ishermitian (A, tol) ¶

: tf = ishermitian (A, "skew") ¶

: tf = ishermitian (A, "skew", tol) ¶

Return true if A is a Hermitian or skew-Hermitian matrix within the tolerance specified by tol.

The default tolerance is zero (uses faster code).

The type of symmetry to check may be specified with the additional input "nonskew" (default) for regular Hermitian or "skew" for skew-Hermitian.

Background: A matrix is Hermitian if the complex conjugate transpose of the matrix is equal to the original matrix: A == A'. If a tolerance is given then the calculation is norm (A - A', Inf) / norm (A, Inf) < tol.

A matrix is skew-Hermitian if the complex conjugate transpose of the matrix is equal to the negative of the original matrix: A == -A'. If a tolerance is given then the calculation is norm (A + A', Inf) / norm (A, Inf) < tol.

See also: issymmetric, isdefinite.