GNU Octave A high-level interactive language for numerical computations Edition 3 for Octave version 2.1.x February 1997 John W. Eaton Copyright c 1996, 1997 John W. Eaton. This is the third edition of the Octave documentation, and is consistent with version 2.1.x of Octave. 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 con- ditions 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 lan- guage, under the same conditions as for modified versions. Portions of this document have been adapted from the gawk, readline, gcc, and C library manuals, published by the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301–1307, USA. i Table of Contents Preface ....................................... 1 Acknowledgements ........................................... 1 How You Can Contribute to Octave ........................... 4 Distribution ................................................. 4 1 A Brief Introduction to Octave ............. 5 1.1 Running Octave ......................................... 5 1.2 Simple Examples ........................................ 5 Creating a Matrix ..................................... 5 Matrix Arithmetic .................................... 6 Solving Linear Equations .............................. 6 Integrating Differential Equations ...................... 6 Producing Graphical Output ........................... 7 Editing What You Have Typed......................... 7 Help and Documentation .............................. 8 1.3 Conventions ............................................ 8 1.3.1 Fonts .......................................... 8 1.3.2 Evaluation Notation ............................ 8 1.3.3 Printing Notation............................... 9 1.3.4 Error Messages ................................. 9 1.3.5 Format of Descriptions .......................... 9 1.3.5.1 A Sample Function Description ......... 9 1.3.5.2 A Sample Command Description ....... 10 1.3.5.3 A Sample Variable Description ......... 11 2 Getting Started........................... 13 2.1 Invoking Octave........................................ 13 2.1.1 Command Line Options ........................ 13 2.1.2 Startup Files .................................. 15 2.2 Quitting Octave........................................ 16 2.3 Commands for Getting Help ............................ 16 2.4 Command Line Editing ................................. 18 2.4.1 Cursor Motion ................................ 18 2.4.2 Killing and Yanking ........................... 19 2.4.3 Commands For Changing Text ................. 19 2.4.4 Letting Readline Type For You ................. 20 2.4.5 Commands For Manipulating The History ....... 20 2.4.6 Customizing readline ......................... 22 2.4.7 Customizing the Prompt ....................... 22 2.4.8 Diary and Echo Commands .................... 23 2.5 How Octave Reports Errors ............................. 24 2.6 Executable Octave Programs ............................ 25 2.7 Comments in Octave Programs .......................... 26 ii GNU Octave 3 Data Types .............................. 29 3.1 Built-in Data Types .................................... 29 3.1.1 Numeric Objects .............................. 29 3.1.2 Missing Data .................................. 29 3.1.3 String Objects................................. 30 3.1.4 Data Structure Objects ........................ 30 3.2 User-defined Data Types................................ 30 3.3 Object Sizes ........................................... 30 4 Numeric Data Types...................... 33 4.1 Matrices ............................................... 33 4.1.1 Empty Matrices ............................... 36 4.2 Ranges ................................................ 37 4.3 Logical Values ......................................... 37 4.4 Predicates for Numeric Objects.......................... 38 5 Strings ................................... 39 5.1 Creating Strings ....................................... 40 5.2 Searching and Replacing ................................ 41 5.3 String Conversions ..................................... 43 5.4 Character Class Functions .............................. 46 6 Data Structures .......................... 47 7 Containers ............................... 51 7.1 Lists .................................................. 51 7.2 Cell Arrays ............................................ 51 8 I/O Streams.............................. 53 9 Variables ................................. 55 9.1 Global Variables ....................................... 55 9.2 Persistent Variables .................................... 56 9.3 Status of Variables ..................................... 57 9.4 Summary of Built-in Variables .......................... 59 9.5 Defaults from the Environment.......................... 64 iii 10 Expressions ............................. 65 10.1 Index Expressions ..................................... 65 10.2 Calling Functions ..................................... 66 10.2.1 Call by Value ................................ 67 10.2.2 Recursion .................................... 68 10.3 Arithmetic Operators.................................. 68 10.4 Comparison Operators................................. 70 10.5 Boolean Expressions................................... 70 10.5.1 Element-by-element Boolean Operators......... 71 10.5.2 Short-circuit Boolean Operators ............... 71 10.6 Assignment Expressions ............................... 72 10.7 Increment Operators .................................. 74 10.8 Operator Precedence .................................. 75 11 Evaluation .............................. 77 12 Statements .............................. 79 12.1 The if Statement ..................................... 79 12.2 The switch Statement ................................ 81 12.3 The while Statement.................................. 82 12.4 The do-until Statement .............................. 83 12.5 The for Statement .................................... 84 12.5.1 Looping Over Structure Elements .............. 84 12.6 The break Statement.................................. 85 12.7 The continue Statement .............................. 86 12.8 The unwind_protect Statement........................ 87 12.9 The try Statement .................................... 88 12.10 Continuation Lines ................................... 88 13 Functions and Script Files................ 91 13.1 Defining Functions .................................... 91 13.2 Multiple Return Values ................................ 93 13.3 Variable-length Argument Lists ........................ 95 13.4 Variable-length Return Lists ........................... 95 13.5 Returning From a Function ............................ 95 13.6 Function Files ........................................ 96 13.7 Script Files ........................................... 98 13.8 Dynamically Linked Functions ........................ 100 13.9 Function Handles and Inline .......................... 103 13.9.1 Function Handles ............................ 103 13.9.2 Inline Functions ............................. 103 13.10 Organization of Functions Distributed with Octave .... 104 14 Error Handling ......................... 105 15 Debugging ............................. 107 iv GNU Octave 16 Input and Output ...................... 109 16.1 Basic Input and Output .............................. 110 16.1.1 Terminal Output ............................ 110 16.1.2 Terminal Input .............................. 113 16.1.3 Simple File I/O ............................. 114 16.2 C-Style I/O Functions ................................ 117 16.2.1 Opening and Closing Files ................... 118 16.2.2 Simple Output .............................. 119 16.2.3 Line-Oriented Input ......................... 119 16.2.4 Formatted Output ........................... 120 16.2.5 Output Conversion for Matrices .............. 121 16.2.6 Output Conversion Syntax ................... 121 16.2.7 Table of Output Conversions ................. 122 16.2.8 Integer Conversions .......................... 123 16.2.9 Floating-Point Conversions ................... 124 16.2.10 Other Output Conversions .................. 125 16.2.11 Formatted Input ........................... 125 16.2.12 Input Conversion Syntax .................... 126 16.2.13 Table of Input Conversions .................. 127 16.2.14 Numeric Input Conversions.................. 128 16.2.15 String Input Conversions .................... 128 16.2.16 Binary I/O ................................ 128 16.2.17 Temporary Files............................ 131 16.2.18 End of File and Errors ...................... 132 16.2.19 File Positioning ............................ 132 17 Plotting................................ 135 17.1 Two-Dimensional Plotting ............................ 135 17.2 Specialized Two-Dimensional Plots .................... 139 17.3 Three-Dimensional Plotting ........................... 142 17.4 Plot Annotations..................................... 142 17.5 Multiple Plots on One Page ........................... 143 17.6 Multiple Plot Windows ............................... 144 17.7 Low-Level plotting commands ......................... 144 17.8