OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / octa21eb.zip / octave / doc / octave.i02 < prev next >

Wrap

GNU Info File | 1999-05-13 | 48.3 KB | 1,450 lines

This is Info file octave, produced by Makeinfo-1.64 from the input file octave.tex. START-INFO-DIR-ENTRY * Octave: (octave). Interactive language for numerical computations. END-INFO-DIR-ENTRY Copyright (C) 1996, 1997 John W. Eaton. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. File: octave, Node: Commands For Completion, Next: Commands For History, Prev: Commands For Text, Up: Command Line Editing Letting Readline Type For You ----------------------------- The following commands allow Octave to complete command and variable names for you. `TAB' Attempt to do completion on the text before the cursor. Octave can complete the names of commands and variables. `M-?' List the possible completions of the text before the cursor. - Built-in Variable: completion_append_char The value of `completion_append_char' is used as the character to append to successful command-line completion attempts. The default value is `" "' (a single space). - Built-in Function: completion_matches (HINT) Generate possible completions given HINT. This function is provided for the benefit of programs like Emacs which might be controlling Octave and handling user input. The current command number is not incremented when this function is called. This is a feature, not a bug. File: octave, Node: Commands For History, Next: Customizing the Prompt, Prev: Commands For Completion, Up: Command Line Editing Commands For Manipulating The History ------------------------------------- Octave normally keeps track of the commands you type so that you can recall previous commands to edit or execute them again. When you exit Octave, the most recent commands you have typed, up to the number specified by the variable `history_size', are saved in a file. When Octave starts, it loads an initial list of commands from the file named by the variable `history_file'. Here are the commands for simple browsing and searching the history list. `LFD' `RET' Accept the line regardless of where the cursor is. If this line is non-empty, add it to the history list. If this line was a history line, then restore the history line to its original state. `C-p' Move `up' through the history list. `C-n' Move `down' through the history list. `M-<' Move to the first line in the history. `M->' Move to the end of the input history, i.e., the line you are entering! `C-r' Search backward starting at the current line and moving `up' through the history as necessary. This is an incremental search. `C-s' Search forward starting at the current line and moving `down' through the history as necessary. On most terminals, you can also use the arrow keys in place of `C-p' and `C-n' to move through the history list. In addition to the keyboard commands for moving through the history list, Octave provides three functions for viewing, editing, and re-running chunks of commands from the history list. - Command: history OPTIONS If invoked with no arguments, `history' displays a list of commands that you have executed. Valid options are: `-w FILE' Write the current history to the file FILE. If the name is omitted, use the default history file (normally `~/.octave_hist'). `-r FILE' Read the file FILE, replacing the current history list with its contents. If the name is omitted, use the default history file (normally `~/.octave_hist'). `N' Only display the most recent N lines of history. `-q' Don't number the displayed lines of history. This is useful for cutting and pasting commands if you are using the X Window System. For example, to display the five most recent commands that you have typed without displaying line numbers, use the command `history -q 5'. - Command: edit_history OPTIONS If invoked with no arguments, `edit_history' allows you to edit the history list using the editor named by the variable `EDITOR'. The commands to be edited are first copied to a temporary file. When you exit the editor, Octave executes the commands that remain in the file. It is often more convenient to use `edit_history' to define functions rather than attempting to enter them directly on the command line. By default, the block of commands is executed as soon as you exit the editor. To avoid executing any commands, simply delete all the lines from the buffer before exiting the editor. The `edit_history' command takes two optional arguments specifying the history numbers of first and last commands to edit. For example, the command edit_history 13 extracts all the commands from the 13th through the last in the history list. The command edit_history 13 169 only extracts commands 13 through 169. Specifying a larger number for the first command than the last command reverses the list of commands before placing them in the buffer to be edited. If both arguments are omitted, the previous command in the history list is used. - Command: run_history Similar to `edit_history', except that the editor is not invoked, and the commands are simply executed as they appear in the history list. - Built-in Variable: EDITOR A string naming the editor to use with the `edit_history' command. If the environment variable `EDITOR' is set when Octave starts, its value is used as the default. Otherwise, `EDITOR' is set to `"emacs"'. - Built-in Variable: history_file This variable specifies the name of the file used to store command history. The default value is `"~/.octave_hist"', but may be overridden by the environment variable `OCTAVE_HISTFILE'. - Built-in Variable: history_size This variable specifies how many entries to store in the history file. The default value is `1024', but may be overridden by the environment variable `OCTAVE_HISTSIZE'. - Built-in Variable: saving_history If the value of `saving_history' is nonzero, command entered on the command line are saved in the file specified by the variable `history_file'. File: octave, Node: Customizing the Prompt, Next: Diary and Echo Commands, Prev: Commands For History, Up: Command Line Editing Customizing the Prompt ---------------------- The following variables are available for customizing the appearance of the command-line prompts. Octave allows the prompt to be customized by inserting a number of backslash-escaped special characters that are decoded as follows: `\t' The time. `\d' The date. `\n' Begins a new line by printing the equivalent of a carriage return followed by a line feed. `\s' The name of the program (usually just `octave'). `\w' The current working directory. `\W' The basename of the current working directory. `\u' The username of the current user. `\h' The hostname, up to the first `.'. `\H' The hostname. `\#' The command number of this command, counting from when Octave starts. `\!' The history number of this command. This differs from `\#' by the number of commands in the history list when Octave starts. `\$' If the effective UID is 0, a `#', otherwise a `$'. `\nnn' The character whose character code in octal is NNN. `\\' A backslash. - Built-in Variable: PS1 The primary prompt string. When executing interactively, Octave displays the primary prompt `PS1' when it is ready to read a command. The default value of `PS1' is `"\s:\#> "'. To change it, use a command like octave:13> PS1 = "\\u@\\H> " which will result in the prompt `boris@kremvax> ' for the user `boris' logged in on the host `kremvax.kgb.su'. Note that two backslashes are required to enter a backslash into a string. *Note Strings::. - Built-in Variable: PS2 The secondary prompt string, which is printed when Octave is expecting additional input to complete a command. For example, when defining a function over several lines, Octave will print the value of `PS1' at the beginning of each line after the first. The default value of `PS2' is `"> "'. - Built-in Variable: PS4 If Octave is invoked with the `--echo-input' option, the value of `PS4' is printed before each line of input that is echoed. The default value of `PS4' is `"+ "'. *Note Invoking Octave::, for a description of `--echo-input'. File: octave, Node: Diary and Echo Commands, Prev: Customizing the Prompt, Up: Command Line Editing Diary and Echo Commands ----------------------- Octave's diary feature allows you to keep a log of all or part of an interactive session by recording the input you type and the output that Octave produces in a separate file. - Command: diary OPTIONS Create a list of all commands *and* the output they produce, mixed together just as you see them on your terminal. Valid options are: `on' Start recording your session in a file called `diary' in your current working directory. `off' Stop recording your session in the diary file. `FILE' Record your session in the file named FILE. Without any arguments, `diary' toggles the current diary state. Sometimes it is useful to see the commands in a function or script as they are being evaluated. This can be especially helpful for debugging some kinds of problems. - Command: echo OPTIONS Control whether commands are displayed as they are executed. Valid options are: `on' Enable echoing of commands as they are executed in script files. `off' Disable echoing of commands as they are executed in script files. `on all' Enable echoing of commands as they are executed in script files and functions. `off all' Disable echoing of commands as they are executed in script files and functions. If invoked without any arguments, `echo' toggles the current echo state. - Built-in Variable: echo_executing_commands This variable is may also be used to control the echo state. It may be the sum of the following values: 1 Echo commands read from script files. 2 Echo commands from functions. 4 Echo commands read from command line. More than one state can be active at once. For example, a value of 3 is equivalent to the command `echo on all'. The value of `echo_executing_commands' is set by the `echo' command and the command line option `--echo-input'. File: octave, Node: Errors, Next: Executable Octave Programs, Prev: Command Line Editing, Up: Getting Started 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> functon y = f (x) y = x^2; endfunction Octave will respond immediately with a message like this: parse error: functon y = f (x) y = x^2; 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 `function' was misspelled. Instead of seeing `function f', Octave saw two consecutive variable names, which is invalid in this context. It marked the error at the `y' because the first name by itself was accepted as valid input. 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: evaluating expression near line 1, column 24 error: evaluating assignment expression near line 1, column 22 error: called from `f' This error message has several parts, and gives you 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 from the beginning of the file containing the function definition. For errors occurring at the top level, the line number indicates the input line number, which is usually displayed in the prompt string. The second and third lines in the example indicate that the error occurred within an assignment expression, and the last line of the error message indicates that the error occurred within the function `f'. If the function `f' had been called from another function, for example, `g', the list of errors would have ended with one more line: error: called from `g' These lists of function calls usually make it fairly easy to trace the path your program took before the error occurred, and to correct the error before trying again. File: octave, Node: Executable Octave Programs, Next: Comments, Prev: Errors, Up: Getting Started 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 (1) For example, you could 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 file name for your Octave binary). After making this file executable (with the `chmod' command), 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 file name 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 file name of the Octave program. The rest of the argument list will either be options to Octave, or data files, or both. The `-qf' option is 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. *Note Invoking Octave::. Note that some operating systems may place a limit on the number of characters that are recognized after `#!'. 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. If you invoke an executable Octave script with command line arguments, the arguments are available in the built-in variable `argv'. *Note Command Line Options::. For example, the following program will reproduce the command line that is used to execute it. #! /bin/octave -qf printf ("%s", program_name); for i = 1:nargin printf (" %s", argv(i,:)); endfor printf ("\n"); ---------- Footnotes ---------- (1) The `#!' mechanism works on Unix systems derived from Berkeley Unix, System V Release 4, and some System V Release 3 systems. File: octave, Node: Comments, Prev: Executable Octave Programs, Up: Getting Started Comments in Octave Programs =========================== A "comment" is some text that is included in a program for the sake of human readers, and that is not really 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. In the Octave language, a comment starts with either the sharp sign character, `#', or the percent symbol `%' and continues to the end of the line. The Octave interpreter ignores the rest of a line following a sharp sign or percent symbol. For example, we could have put the following into the function `f': 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 The `help' command (*note Getting Help::.) is able to find the first block of comments in a function (even those that are composed directly on the command line). This means that users of Octave can use the same commands to get help for built-in functions, and for functions that you have defined. For example, after defining the function `f' above, the command `help f' produces the output usage: f (x, t) This function defines the right hand side functions for a set of nonlinear differential equations. Although it is possible to put comment lines into keyboard-composed throw-away Octave programs, it usually isn't very useful, because the purpose of a comment is to help you or another person understand the program at a later time. File: octave, Node: Data Types, Next: Numeric Data Types, Prev: Getting Started, Up: Top Data Types ********** All versions of Octave include a number of built-in data types, including real and complex scalars and matrices, character strings, and a data structure type. It is also possible to define new specialized data types by writing a small amount of C++ code. On some systems, new data types can be loaded dynamically while Octave is running, so it is not necessary to recompile all of Octave just to add a new type. *Note Dynamically Linked Functions:: for more information about Octave's dynamic linking capabilities. *Note User-defined Data Types:: describes what you must do to define a new data type for Octave. * Menu: * Built-in Data Types:: * User-defined Data Types:: * Object Sizes:: File: octave, Node: Built-in Data Types, Next: User-defined Data Types, Prev: Data Types, Up: Data Types Built-in Data Types =================== The standard built-in data types are real and complex scalars and matrices, ranges, character strings, and a data structure type. 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. * Menu: * Numeric Objects:: * String Objects:: * Data Structure Objects:: File: octave, Node: Numeric Objects, Next: String Objects, Prev: Built-in Data Types, Up: Built-in Data Types Numeric Objects --------------- Octave's built-in numeric objects include real and complex scalars and matrices. All built-in numeric data is currently stored as double precision numbers. On systems that use the IEEE floating point format, values in the range of approximately 2.2251e-308 to 1.7977e+308 can be stored, and the relative precision is approximately 2.2204e-16. The exact values are given by the variables `realmin', `realmax', and `eps', respectively. Matrix objects can be of any size, and can be dynamically reshaped and resized. It is easy to extract individual rows, columns, or submatrices is using a variety of powerful indexing features. *Note Index Expressions::. *Note Numeric Data Types::, for more information. File: octave, Node: String Objects, Next: Data Structure Objects, Prev: Numeric Objects, Up: Built-in Data Types String Objects -------------- A character string in Octave consists of a sequence of characters enclosed in either double-quote or single-quote marks. Internally, Octave currently stores strings as matrices of characters. All the indexing operations that work for matrix objects also work for strings. *Note Strings::, for more information. File: octave, Node: Data Structure Objects, Prev: String Objects, Up: Built-in Data Types Data Structure Objects ---------------------- Octave's data structure type can help you to organize related objects of different types. The current implementation uses an associative array with indices limited to strings, but the syntax is more like C-style structures. *Note Data Structures::, for more information. File: octave, Node: User-defined Data Types, Next: Object Sizes, Prev: Built-in Data Types, Up: Data Types 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. File: octave, Node: Object Sizes, Prev: User-defined Data Types, Up: Data Types 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. - Function File: columns (A) Return the number of columns of A. - Function File: rows (A) Return the number of rows of A. - Function File: length (A) Return the number of rows of A or the number of columns of A, whichever is larger. - Function File: size (A, N) Return the number rows and columns of A. With one input argument and one output argument, the result is returned in a 2 element row vector. If there are two output arguments, the number of rows is assigned to the first, and the number of columns to the second. For example, size ([1, 2; 3, 4; 5, 6]) => [ 3, 2 ] [nr, nc] = size ([1, 2; 3, 4; 5, 6]) => nr = 3 => nc = 2 If given a second argument of either 1 or 2, `size' will return only the row or column dimension. For example size ([1, 2; 3, 4; 5, 6], 2) => 2 returns the number of columns in the given matrix. - Function File: isempty (A) Return 1 if A is an empty matrix (either the number of rows, or the number of columns, or both are zero). Otherwise, return 0. File: octave, Node: Numeric Data Types, Next: Strings, Prev: Data Types, Up: Top Numeric Data Types ****************** A "numeric constant" may be a scalar, a vector, or a matrix, and it may contain complex values. The simplest form of a numeric constant, a scalar, is a single number that can be an integer, a decimal fraction, a number in scientific (exponential) notation, or a complex number. Note that all numeric constants are represented within Octave in double-precision floating point format (complex constants are stored as pairs of double-precision floating point values). Here are some examples of real-valued numeric constants, which all have the same value: 105 1.05e+2 1050e-1 To specify complex constants, you can write an expression of the form 3 + 4i 3.0 + 4.0i 0.3e1 + 40e-1i all of which are equivalent. The letter `i' in the previous example stands for the pure imaginary constant, defined as `sqrt (-1)'. For Octave to recognize a value as the imaginary part of a complex constant, a space must not appear between the number and the `i'. If it does, Octave will print an error message, like this: octave:13> 3 + 4 i parse error: 3 + 4 i ^ You may also use `j', `I', or `J' in place of the `i' above. All four forms are equivalent. * Menu: * Matrices:: * Ranges:: * Predicates for Numeric Objects:: File: octave, Node: Matrices, Next: Ranges, Prev: Numeric Data Types, Up: Numeric Data Types 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 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 commands like [ linspace (1, 2) ] and 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 ]'. 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 error: unterminated string constant because to not do so would make it impossible to correctly parse the valid expression [ a 'foo' ] For clarity, it is probably best to always use commas and semicolons to separate matrix elements and rows. It is possible to enforce this style by setting the built-in variable `whitespace_in_literal_matrix' to `"ignore"'. - Built-in Variable: whitespace_in_literal_matrix This variable allows some control over how Octave decides to convert spaces to commas and semicolons in matrix expressions like `[m (1)]' or [ 1, 2, 3, 4 ] If the value of `whitespace_in_literal_matrix' is `"ignore"', Octave will never insert a comma or a semicolon in a literal matrix list. For example, the expression `[1 2]' will result in an error instead of being treated the same as `[1, 2]', and the expression [ 1, 2, 3, 4 ] will result in the vector `[ 1, 2, 3, 4 ]' instead of a matrix. If the value of `whitespace_in_literal_matrix' is `"traditional"', Octave will convert spaces to a comma between identifiers and `('. For example, given the matrix m = [3 2] the expression [m (1)] will be parsed as [m, (1)] and will result in [3 2 1] and the expression [ 1, 2, 3, 4 ] will result in a matrix because the newline character is converted to a semicolon (row separator) even though there is a comma at the end of the first line (trailing commas or semicolons are ignored). This is apparently how MATLAB behaves. Any other value for `whitespace_in_literal_matrix' results in behavior that is the same as traditional, except that Octave does not convert spaces to a comma between identifiers and `('. For example, the expression [m (1)] will produce `3'. This is the way Octave has always behaved. 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. - Built-in Variable: output_max_field_width This variable specifies the maximum width of a numeric output field. The default value is 10. - Built-in Variable: output_precision This variable specifies the minimum number of significant figures to display for numeric output. The default value is 5. It is possible to achieve a wide range of output styles by using different values of `output_precision' and `output_max_field_width'. Reasonable combinations can be set using the `format' function. *Note Basic Input and Output::. - Built-in Variable: split_long_rows For large matrices, Octave may not be able to display all the columns of a given row on one line of your screen. This can result in missing information or output that is nearly impossible to decipher, depending on whether your terminal truncates or wraps long lines. If the value of `split_long_rows' is nonzero, Octave will display the matrix in a series of smaller pieces, each of which can fit within the limits of your terminal width. 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 The default value of `split_long_rows' is nonzero. 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 set the built-in variable `fixed_point_format' to a nonzero value. But doing so is not recommended, because it can produce output that can easily be misinterpreted. - Built-in Variable: fixed_point_format If the value of this variable is nonzero, Octave will scale all values in a matrix so that the largest may be written with one leading digit. The scaling factor is printed on the first line of output. For example, octave:1> logspace (1, 7, 5)' ans = 1.0e+07 * 0.00000 0.00003 0.00100 0.03162 1.00000 Notice that first value appears to be zero when it is actually 1. For this reason, you should be careful when setting `fixed_point_format' to a nonzero value. The default value of `fixed_point_format' is 0. * Menu: * Empty Matrices:: File: octave, Node: Empty Matrices, Prev: Matrices, Up: Matrices Empty Matrices -------------- A matrix may have one or both dimensions zero, and operations on empty matrices are handled as described by Carl de Boor in `An Empty Exercise', SIGNUM, Volume 25, pages 2-6, 1990 and C. N. Nett and W. M. Haddad, in `A System-Theoretic Appropriate Realization of the Empty Matrix Concept', IEEE Transactions on Automatic Control, Volume 38, Number 5, May 1993. Briefly, given a scalar S, an M by N matrix `M(mxn)', and an M by N empty matrix `[](mxn)' (with either one or both dimensions equal to zero), the following are true: s * [](mxn) = [](mxn) * s = [](mxn) [](mxn) + [](mxn) = [](mxn) [](0xm) * M(mxn) = [](0xn) M(mxn) * [](nx0) = [](mx0) [](mx0) * [](0xn) = 0(mxn) By default, dimensions of the empty matrix are printed along with the empty matrix symbol, `[]'. The built-in variable `print_empty_dimensions' controls this behavior. - Built-in Variable: print_empty_dimensions If the value of `print_empty_dimensions' is nonzero, the dimensions of empty matrices are printed along with the empty matrix symbol, `[]'. For example, the expression zeros (3, 0) will print ans = [](3x0) Empty matrices may also be used in assignment statements as a convenient way to delete rows or columns of matrices. *Note Assignment Expressions: Assignment Ops. Octave will normally issue a warning if it finds an empty matrix in the list of elements that make up another matrix. You can use the variable `empty_list_elements_ok' to suppress the warning or to treat it as an error. - Built-in Variable: empty_list_elements_ok This variable controls whether Octave ignores empty matrices in a matrix list. For example, if the value of `empty_list_elements_ok' is nonzero, Octave will ignore the empty matrices in the expression a = [1, [], 3, [], 5] and the variable `a' will be assigned the value `[ 1, 3, 5 ]'. The default value is `"warn"'. When Octave parses a matrix expression, it examines the elements of the list to determine whether they are all constants. If they are, it replaces the list with a single matrix constant. - Built-in Variable: propagate_empty_matrices If the value of `propagate_empty_matrices' is nonzero, functions like `inverse' and `svd' will return an empty matrix if they are given one as an argument. The default value is 1. File: octave, Node: Ranges, Next: Predicates for Numeric Objects, Prev: Matrices, Up: Numeric Data Types 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* 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. 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 (*note Special Utility Matrices::.). 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. File: octave, Node: Predicates for Numeric Objects, Prev: Ranges, Up: Numeric Data Types Predicates for Numeric Objects ============================== - Function File: is_matrix (A) Return 1 if A is a matrix. Otherwise, return 0. - Function File: is_vector (A) Return 1 if A is a vector. Otherwise, return 0. - Function File: is_scalar (A) Return 1 if A is a scalar. Otherwise, return 0. - Function File: is_square (X) If X is a square matrix, then return the dimension of X. Otherwise, return 0. - Function File: is_symmetric (X, TOL) If X is symmetric within the tolerance specified by TOL, then return the dimension of X. Otherwise, return 0. If TOL is omitted, use a tolerance equal to the machine precision. File: octave, Node: Strings, Next: Data Structures, Prev: Numeric Data Types, Up: Top Strings ******* A "string constant" consists of a sequence of characters enclosed in either double-quote or single-quote marks. For example, both of the following expressions "parrot" 'parrot' represent the string whose contents are `parrot'. Strings in Octave can be of any length. Since the single-quote mark is also used for the transpose operator (*note Arithmetic Ops::.) but double-quote marks have no other purpose in Octave, it is best to use double-quote marks to denote strings. Some characters cannot be included literally in a string constant. You represent them instead with "escape sequences", which are character sequences beginning with a backslash (`\'). One use of an escape sequence is to include a double-quote (single-quote) character in a string constant that has been defined using double-quote (single-quote) marks. Since a plain double-quote would end the string, you must use `\"' to represent a single double-quote character as a part of the string. The backslash character itself is another character that cannot be included normally. You must write `\\' to put one backslash in the string. Thus, the string whose contents are the two characters `"\' may be written `"\"\\"' or `'"\\''. Similarly, the string whose contents are the two characters `'\' may be written `'\'\\'' or `"'\\"'. Another use of backslash is to represent unprintable characters such as newline. While there is nothing to stop you from writing most of these characters directly in a string constant, they may look ugly. Here is a table of all the escape sequences used in Octave. They are the same as those used in the C programming language. `\\' Represents a literal backslash, `\'. `\"' Represents a literal double-quote character, `"'. `\'' Represents a literal single-quote character, `''. `\a' Represents the "alert" character, control-g, ASCII code 7. `\b' Represents a backspace, control-h, ASCII code 8. `\f' Represents a formfeed, control-l, ASCII code 12. `\n' Represents a newline, control-j, ASCII code 10. `\r' Represents a carriage return, control-m, ASCII code 13. `\t' Represents a horizontal tab, control-i, ASCII code 9. `\v' Represents a vertical tab, control-k, ASCII code 11. Strings may be concatenated using the notation for defining matrices. For example, the expression [ "foo" , "bar" , "baz" ] produces the string whose contents are `foobarbaz'. *Note Numeric Data Types:: for more information about creating matrices. * Menu: * Creating Strings:: * Searching and Replacing:: * String Conversions:: * Character Class Functions:: File: octave, Node: Creating Strings, Next: Searching and Replacing, Prev: Strings, Up: Strings Creating Strings ================ - Function File: blanks (N) Return a string of N blanks. - Function File: int2str (N) - Function File: num2str (X) Convert a number to a string. These functions are not very flexible, but are provided for compatibility with MATLAB. For better control over the results, use `sprintf' (*note Formatted Output::.). - Built-in Function: setstr (X) Convert a matrix to a string. Each element of the matrix is converted to the corresponding ASCII character. For example, setstr ([97, 98, 99]) => "abc" - Function File: strcat (S1, S2, ...) Return a string containing all the arguments concatenated. For example, s = [ "ab"; "cde" ]; strcat (s, s, s) => "ab ab ab " "cdecdecde" - Built-in Variable: string_fill_char The value of this variable is used to pad all strings in a string matrix to the same length. It should be a single character. The default value is `" "' (a single space). For example, string_fill_char = "X"; [ "these"; "are"; "strings" ] => "theseXX" "areXXXX" "strings" - Function File: str2mat (S_1, ..., S_N) Return a matrix containing the strings S_1, ..., S_N as its rows. Each string is padded with blanks in order to form a valid matrix. *Note:* This function is modelled after MATLAB. In Octave, you can create a matrix of strings by `[S_1; ...; S_N]' even if the strings are not all the same length. - Built-in Function: isstr (A) Return 1 if A is a string. Otherwise, return 0. File: octave, Node: Searching and Replacing, Next: String Conversions, Prev: Creating Strings, Up: Strings Searching and Replacing ======================= - Function File: deblank (S) Removes the trailing blanks from the string S. - Function File: findstr (S, T, OVERLAP) Return the vector of all positions in the longer of the two strings S and T where an occurrence of the shorter of the two starts. If the optional argument OVERLAP is nonzero, the returned vector can include overlapping positions (this is the default). For example, findstr ("ababab", "a") => [ 1, 3, 5 ] findstr ("abababa", "aba", 0) => [ 1, 5 ] - Function File: index (S, T) Return the position of the first occurrence of the string T in the string S, or 0 if no occurrence is found. For example, index ("Teststring", "t") => 4 *Note:* This function does not work for arrays of strings. - Function File: rindex (S, T) Return the position of the last occurrence of the string T in the string S, or 0 if no occurrence is found. For example, rindex ("Teststring", "t") => 6 *Note:* This function does not work for arrays of strings. - Function File: split (S, T) Divides the string S into pieces separated by T, returning the result in a string array (padded with blanks to form a valid matrix). For example, split ("Test string", "t") => "Tes " " s " "ring" - Function File: strcmp (S1, S2) Compares two strings, returning 1 if they are the same, and 0 otherwise. *Note:* For compatibility with MATLAB, Octave's strcmp function returns 1 if the strings are equal, and 0 otherwise. This is just the opposite of the corresponding C library function. - Function File: strrep (S, X, Y) Replaces all occurrences of the substring X of the string S with the string Y. For example, strrep ("This is a test string", "is", "&%$") => "Th&%$ &%$ a test string" - Function File: substr (S, BEG, LEN) Return the substring of S which starts at character number BEG and is LEN characters long. For example, substr ("This is a test string", 6, 9) => "is a test" *Note:* This function is patterned after AWK. You can get the same result by `S (BEG : (BEG + LEN - 1))'. File: octave, Node: String Conversions, Next: Character Class Functions, Prev: Searching and Replacing, Up: Strings String Conversions ================== - Function File: bin2dec (S) Return a decimal number corresponding to the binary number represented as a string of zeros and ones. For example, bin2dec ("1110") => 14 - Function File: dec2bin (N) Return a binary number corresponding the nonnegative decimal number N, as a string of ones and zeros. For example, dec2bin (14) => "1110" - Function File: dec2hex (N) Return the hexadecimal number corresponding to the nonnegative decimal number N, as a string. For example, dec2hex (2748) => "abc" - Function File: hex2dec (S) Return the decimal number corresponding to the hexadecimal number stored in the string S. For example, hex2dec ("12B") => 299 hex2dec ("12b") => 299 - Function File: str2num (S) Convert the string S to a number. - Function File: toascii (S) Return ASCII representation of S in a matrix. For example, toascii ("ASCII") => [ 65, 83, 67, 73, 73 ] - Function File: tolower (S) Return a copy of the string S, with each upper-case character replaced by the corresponding lower-case one; nonalphabetic characters are left unchanged. For example, tolower ("MiXeD cAsE 123") => "mixed case 123" - Function File: toupper (S) Return a copy of the string S, with each lower-case character replaced by the corresponding upper-case one; nonalphabetic characters are left unchanged. For example, toupper ("MiXeD cAsE 123") => "MIXED CASE 123" - Built-in Function: undo_string_escapes (S) Converts special characters in strings back to their escaped forms. For example, the expression bell = "\a"; assigns the value of the alert character (control-g, ASCII code 7) to the string variable `bell'. If this string is printed, the system will ring the terminal bell (if it is possible). This is normally the desired outcome. However, sometimes it is useful to be able to print the original representation of the string, with the special characters replaced by their escape sequences. For example, octave:13> undo_string_escapes (bell) ans = \a replaces the unprintable alert character with its printable representation. - Built-in Variable: implicit_num_to_str_ok If the value of `implicit_num_to_str_ok' is nonzero, implicit conversions of numbers to their ASCII character equivalents are allowed when strings are constructed using a mixture of strings and numbers in matrix notation. Otherwise, an error message is printed and control is returned to the top level. The default value is 0. For example, [ "f", 111, 111 ] => "foo" - Built-in Variable: implicit_str_to_num_ok If the value of `implicit_str_to_num_ok' is nonzero, implicit conversions of strings to their numeric ASCII equivalents are allowed. Otherwise, an error message is printed and control is returned to the top level. The default value is 0. File: octave, Node: Character Class Functions, Prev: String Conversions, Up: Strings Character Class Functions ========================= Octave also provides the following character class test functions patterned after the functions in the standard C library. They all operate on string arrays and return matrices of zeros and ones. Elements that are nonzero indicate that the condition was true for the corresponding character in the string array. For example, isalpha ("!Q@WERT^Y&") => [ 0, 1, 0, 1, 1, 1, 1, 0, 1, 0 ] - Mapping Function: isalnum (S) Return 1 for characters that are letters or digits (`isalpha (A)' or `isdigit ()' is true). - Mapping Function: isalpha (S) Return true for characters that are letters (`isupper (A)' or `islower ()' is true). - Mapping Function: isascii (S) Return 1 for characters that are ASCII (in the range 0 to 127 decimal). - Mapping Function: iscntrl (S) Return 1 for control characters. - Mapping Function: isdigit (S) Return 1 for characters that are decimal digits. - Mapping Function: isgraph (S) Return 1 for printable characters (but not the space character). - Mapping Function: islower (S) Return 1 for characters that are lower case letters. - Mapping Function: isprint (S) Return 1 for printable characters (including the space character). - Mapping Function: ispunct (S) Return 1 for punctuation characters. - Mapping Function: isspace (S) Return 1 for whitespace characters (space, formfeed, newline, carriage return, tab, and vertical tab). - Mapping Function: isupper (S) Return 1 for upper case letters. - Mapping Function: isxdigit (S) Return 1 for characters that are hexadecimal digits.