home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / octa21fb.zip / octave / doc / octave.i02 (.txt) < prev    next >
GNU Info File  |  2000-01-15  |  50KB  |  1,023 lines

  1. This is Info file octave, produced by Makeinfo-1.64 from the input file
  2. octave.tex.
  3. START-INFO-DIR-ENTRY
  4. * Octave: (octave).    Interactive language for numerical computations.
  5. END-INFO-DIR-ENTRY
  6.    Copyright (C) 1996, 1997 John W. Eaton.
  7.    Permission is granted to make and distribute verbatim copies of this
  8. manual provided the copyright notice and this permission notice are
  9. preserved on all copies.
  10.    Permission is granted to copy and distribute modified versions of
  11. this manual under the conditions for verbatim copying, provided that
  12. the entire resulting derived work is distributed under the terms of a
  13. permission notice identical to this one.
  14.    Permission is granted to copy and distribute translations of this
  15. manual into another language, under the above conditions for modified
  16. versions.
  17. File: octave,  Node: Commands For Text,  Next: Commands For Completion,  Prev: Killing and Yanking,  Up: Command Line Editing
  18. Commands For Changing Text
  19. --------------------------
  20.    The following commands can be used for entering characters that would
  21. otherwise have a special meaning (e.g., `TAB', `C-q', etc.), or for
  22. quickly correcting typing mistakes.
  23. `C-q'
  24. `C-v'
  25.      Add the next character that you type to the line verbatim.  This is
  26.      how to insert things like `C-q' for example.
  27. `M-TAB'
  28.      Insert a tab character.
  29. `C-t'
  30.      Drag the character before the cursor forward over the character at
  31.      the cursor, also moving the cursor forward.  If the cursor is at
  32.      the end of the line, then transpose the two characters before it.
  33. `M-t'
  34.      Drag the word behind the cursor past the word in front of the
  35.      cursor moving the cursor over that word as well.
  36. `M-u'
  37.      Uppercase the characters following the cursor to the end of the
  38.      current (or following) word, moving the cursor to the end of the
  39.      word.
  40. `M-l'
  41.      Lowecase the characters following the cursor to the end of the
  42.      current (or following) word, moving the cursor to the end of the
  43.      word.
  44. `M-c'
  45.      Uppercase the character following the cursor (or the beginning of
  46.      the next word if the cursor is between words), moving the cursor
  47.      to the end of the word.
  48. File: octave,  Node: Commands For Completion,  Next: Commands For History,  Prev: Commands For Text,  Up: Command Line Editing
  49. Letting Readline Type For You
  50. -----------------------------
  51.    The following commands allow Octave to complete command and variable
  52. names for you.
  53. `TAB'
  54.      Attempt to do completion on the text before the cursor.  Octave can
  55.      complete the names of commands and variables.
  56. `M-?'
  57.      List the possible completions of the text before the cursor.
  58.  - Built-in Variable: completion_append_char
  59.      The value of `completion_append_char' is used as the character to
  60.      append to successful command-line completion attempts.  The default
  61.      value is `" "' (a single space).
  62.  - Built-in Function:  completion_matches (HINT)
  63.      Generate possible completions given HINT.
  64.      This function is provided for the benefit of programs like Emacs
  65.      which might be controlling Octave and handling user input.  The
  66.      current command number is not incremented when this function is
  67.      called.  This is a feature, not a bug.
  68. File: octave,  Node: Commands For History,  Next: Customizing the Prompt,  Prev: Commands For Completion,  Up: Command Line Editing
  69. Commands For Manipulating The History
  70. -------------------------------------
  71.    Octave normally keeps track of the commands you type so that you can
  72. recall previous commands to edit or execute them again.  When you exit
  73. Octave, the most recent commands you have typed, up to the number
  74. specified by the variable `history_size', are saved in a file.  When
  75. Octave starts, it loads an initial list of commands from the file named
  76. by the variable `history_file'.
  77.    Here are the commands for simple browsing and searching the history
  78. list.
  79. `LFD'
  80. `RET'
  81.      Accept the line regardless of where the cursor is.  If this line is
  82.      non-empty, add it to the history list.  If this line was a history
  83.      line, then restore the history line to its original state.
  84. `C-p'
  85.      Move `up' through the history list.
  86. `C-n'
  87.      Move `down' through the history list.
  88. `M-<'
  89.      Move to the first line in the history.
  90. `M->'
  91.      Move to the end of the input history, i.e., the line you are
  92.      entering!
  93. `C-r'
  94.      Search backward starting at the current line and moving `up'
  95.      through the history as necessary.  This is an incremental search.
  96. `C-s'
  97.      Search forward starting at the current line and moving `down'
  98.      through the history as necessary.
  99.    On most terminals, you can also use the arrow keys in place of `C-p'
  100. and `C-n' to move through the history list.
  101.    In addition to the keyboard commands for moving through the history
  102. list, Octave provides three functions for viewing, editing, and
  103. re-running chunks of commands from the history list.
  104.  - Command: history OPTIONS
  105.      If invoked with no arguments, `history' displays a list of commands
  106.      that you have executed.  Valid options are:
  107.     `-w FILE'
  108.           Write the current history to the file FILE.  If the name is
  109.           omitted, use the default history file (normally
  110.           `~/.octave_hist').
  111.     `-r FILE'
  112.           Read the file FILE, replacing the current history list with
  113.           its contents.  If the name is omitted, use the default
  114.           history file (normally `~/.octave_hist').
  115.     `N'
  116.           Only display the most recent N lines of history.
  117.     `-q'
  118.           Don't number the displayed lines of history.  This is useful
  119.           for cutting and pasting commands if you are using the X
  120.           Window System.
  121.      For example, to display the five most recent commands that you have
  122.      typed without displaying line numbers, use the command `history -q
  123.      5'.
  124.  - Command: edit_history OPTIONS
  125.      If invoked with no arguments, `edit_history' allows you to edit the
  126.      history list using the editor named by the variable `EDITOR'.  The
  127.      commands to be edited are first copied to a temporary file.  When
  128.      you exit the editor, Octave executes the commands that remain in
  129.      the file.  It is often more convenient to use `edit_history' to
  130.      define functions rather than attempting to enter them directly on
  131.      the command line.  By default, the block of commands is executed
  132.      as soon as you exit the editor.  To avoid executing any commands,
  133.      simply delete all the lines from the buffer before exiting the
  134.      editor.
  135.      The `edit_history' command takes two optional arguments specifying
  136.      the history numbers of first and last commands to edit.  For
  137.      example, the command
  138.           edit_history 13
  139.      extracts all the commands from the 13th through the last in the
  140.      history list.  The command
  141.           edit_history 13 169
  142.      only extracts commands 13 through 169.  Specifying a larger number
  143.      for the first command than the last command reverses the list of
  144.      commands before placing them in the buffer to be edited.  If both
  145.      arguments are omitted, the previous command in the history list is
  146.      used.
  147.  - Command: run_history [FIRST] [LAST]
  148.      Similar to `edit_history', except that the editor is not invoked,
  149.      and the commands are simply executed as they appear in the history
  150.      list.
  151.  - Built-in Variable: EDITOR
  152.      A string naming the editor to use with the `edit_history' command.
  153.      If the environment variable `EDITOR' is set when Octave starts, its
  154.      value is used as the default.  Otherwise, `EDITOR' is set to
  155.      `"emacs"'.
  156.  - Built-in Variable: history_file
  157.      This variable specifies the name of the file used to store command
  158.      history.  The default value is `"~/.octave_hist"', but may be
  159.      overridden by the environment variable `OCTAVE_HISTFILE'.
  160.  - Built-in Variable: history_size
  161.      This variable specifies how many entries to store in the history
  162.      file.  The default value is `1024', but may be overridden by the
  163.      environment variable `OCTAVE_HISTSIZE'.
  164.  - Built-in Variable: saving_history
  165.      If the value of `saving_history' is nonzero, command entered on
  166.      the command line are saved in the file specified by the variable
  167.      `history_file'.
  168. File: octave,  Node: Customizing the Prompt,  Next: Diary and Echo Commands,  Prev: Commands For History,  Up: Command Line Editing
  169. Customizing the Prompt
  170. ----------------------
  171.    The following variables are available for customizing the appearance
  172. of the command-line prompts.  Octave allows the prompt to be customized
  173. by inserting a number of backslash-escaped special characters that are
  174. decoded as follows:
  175.      The time.
  176.      The date.
  177.      Begins a new line by printing the equivalent of a carriage return
  178.      followed by a line feed.
  179.      The name of the program (usually just `octave').
  180.      The current working directory.
  181.      The basename of the current working directory.
  182.      The username of the current user.
  183.      The hostname, up to the first `.'.
  184.      The hostname.
  185.      The command number of this command, counting from when Octave
  186.      starts.
  187.      The history number of this command.  This differs from `\#' by the
  188.      number of commands in the history list when Octave starts.
  189.      If the effective UID is 0, a `#', otherwise a `$'.
  190. `\nnn'
  191.      The character whose character code in octal is NNN.
  192.      A backslash.
  193.  - Built-in Variable: PS1
  194.      The primary prompt string.  When executing interactively, Octave
  195.      displays the primary prompt `PS1' when it is ready to read a
  196.      command.
  197.      The default value of `PS1' is `"\s:\#> "'.  To change it, use a
  198.      command like
  199.           octave:13> PS1 = "\\u@\\H> "
  200.      which will result in the prompt `boris@kremvax> ' for the user
  201.      `boris' logged in on the host `kremvax.kgb.su'.  Note that two
  202.      backslashes are required to enter a backslash into a string.
  203.      *Note Strings::.
  204.  - Built-in Variable: PS2
  205.      The secondary prompt string, which is printed when Octave is
  206.      expecting additional input to complete a command.  For example,
  207.      when defining a function over several lines, Octave will print the
  208.      value of `PS1' at the beginning of each line after the first.  The
  209.      default value of `PS2' is `"> "'.
  210.  - Built-in Variable: PS4
  211.      If Octave is invoked with the `--echo-input' option, the value of
  212.      `PS4' is printed before each line of input that is echoed.  The
  213.      default value of `PS4' is `"+ "'.  *Note Invoking Octave::, for a
  214.      description of `--echo-input'.
  215. File: octave,  Node: Diary and Echo Commands,  Prev: Customizing the Prompt,  Up: Command Line Editing
  216. Diary and Echo Commands
  217. -----------------------
  218.    Octave's diary feature allows you to keep a log of all or part of an
  219. interactive session by recording the input you type and the output that
  220. Octave produces in a separate file.
  221.  - Command: diary OPTIONS
  222.      Create a list of all commands *and* the output they produce, mixed
  223.      together just as you see them on your terminal.  Valid options are:
  224.     `on'
  225.           Start recording your session in a file called `diary' in your
  226.           current working directory.
  227.     `off'
  228.           Stop recording your session in the diary file.
  229.     `FILE'
  230.           Record your session in the file named FILE.
  231.      Without any arguments, `diary' toggles the current diary state.
  232.    Sometimes it is useful to see the commands in a function or script as
  233. they are being evaluated.  This can be especially helpful for debugging
  234. some kinds of problems.
  235.  - Command: echo OPTIONS
  236.      Control whether commands are displayed as they are executed.  Valid
  237.      options are:
  238.     `on'
  239.           Enable echoing of commands as they are executed in script
  240.           files.
  241.     `off'
  242.           Disable echoing of commands as they are executed in script
  243.           files.
  244.     `on all'
  245.           Enable echoing of commands as they are executed in script
  246.           files and functions.
  247.     `off all'
  248.           Disable echoing of commands as they are executed in script
  249.           files and functions.
  250.      If invoked without any arguments, `echo' toggles the current echo
  251.      state.
  252.  - Built-in Variable: echo_executing_commands
  253.      This variable may also be used to control the echo state.  It may
  254.      be the sum of the following values:
  255.     1
  256.           Echo commands read from script files.
  257.     2
  258.           Echo commands from functions.
  259.     4
  260.           Echo commands read from command line.
  261.      More than one state can be active at once.  For example, a value
  262.      of 3 is equivalent to the command `echo on all'.
  263.      The value of `echo_executing_commands' is set by the `echo'
  264.      command and the command line option `--echo-input'.
  265. File: octave,  Node: Errors,  Next: Executable Octave Programs,  Prev: Command Line Editing,  Up: Getting Started
  266. How Octave Reports Errors
  267. =========================
  268.    Octave reports two kinds of errors for invalid programs.
  269.    A "parse error" occurs if Octave cannot understand something you
  270. have typed.  For example, if you misspell a keyword,
  271.      octave:13> functon y = f (x) y = x^2; endfunction
  272. Octave will respond immediately with a message like this:
  273.      parse error:
  274.      
  275.        functon y = f (x) y = x^2; endfunction
  276.                ^
  277. For most parse errors, Octave uses a caret (`^') to mark the point on
  278. the line where it was unable to make sense of your input.  In this
  279. case, Octave generated an error message because the keyword `function'
  280. was misspelled.  Instead of seeing `function f', Octave saw two
  281. consecutive variable names, which is invalid in this context.  It
  282. marked the error at `y' because the first name by itself was accepted
  283. as valid input.
  284.    Another class of error message occurs at evaluation time.  These
  285. errors are called "run-time errors", or sometimes "evaluation errors"
  286. because they occur when your program is being "run", or "evaluated".
  287. For example, if after correcting the mistake in the previous function
  288. definition, you type
  289.      octave:13> f ()
  290. Octave will respond with
  291.      error: `x' undefined near line 1 column 24
  292.      error: evaluating expression near line 1, column 24
  293.      error: evaluating assignment expression near line 1, column 22
  294.      error: called from `f'
  295.    This error message has several parts, and gives you quite a bit of
  296. information to help you locate the source of the error.  The messages
  297. are generated from the point of the innermost error, and provide a
  298. traceback of enclosing expressions and function calls.
  299.    In the example above, the first line indicates that a variable named
  300. `x' was found to be undefined near line 1 and column 24 of some
  301. function or expression.  For errors occurring within functions, lines
  302. are counted from the beginning of the file containing the function
  303. definition.  For errors occurring at the top level, the line number
  304. indicates the input line number, which is usually displayed in the
  305. prompt string.
  306.    The second and third lines in the example indicate that the error
  307. occurred within an assignment expression, and the last line of the error
  308. message indicates that the error occurred within the function `f'.  If
  309. the function `f' had been called from another function, for example,
  310. `g', the list of errors would have ended with one more line:
  311.      error: called from `g'
  312.    These lists of function calls usually make it fairly easy to trace
  313. the path your program took before the error occurred, and to correct the
  314. error before trying again.
  315. File: octave,  Node: Executable Octave Programs,  Next: Comments,  Prev: Errors,  Up: Getting Started
  316. Executable Octave Programs
  317. ==========================
  318.    Once you have learned Octave, you may want to write self-contained
  319. Octave scripts, using the `#!' script mechanism.  You can do this on
  320. GNU systems and on many Unix systems (1)
  321.    For example, you could create a text file named `hello', containing
  322. the following lines:
  323.      #! OCTAVE-INTERPRETER-NAME -qf
  324.      # a sample Octave program
  325.      printf ("Hello, world!\n");
  326. (where OCTAVE-INTERPRETER-NAME should be replaced with the full file
  327. name for your Octave binary).  After making this file executable (with
  328. the `chmod' command), you can simply type:
  329.      hello
  330. at the shell, and the system will arrange to run Octave as if you had
  331. typed:
  332.      octave hello
  333.    The line beginning with `#!' lists the full file name of an
  334. interpreter to be run, and an optional initial command line argument to
  335. pass to that interpreter.  The operating system then runs the
  336. interpreter with the given argument and the full argument list of the
  337. executed program.  The first argument in the list is the full file name
  338. of the Octave program. The rest of the argument list will either be
  339. options to Octave, or data files, or both.  The `-qf' option is usually
  340. specified in stand-alone Octave programs to prevent them from printing
  341. the normal startup message, and to keep them from behaving differently
  342. depending on the contents of a particular user's `~/.octaverc' file.
  343. *Note Invoking Octave::.  Note that some operating systems may place a
  344. limit on the number of characters that are recognized after `#!'.
  345.    Self-contained Octave scripts are useful when you want to write a
  346. program which users can invoke without knowing that the program is
  347. written in the Octave language.
  348.    If you invoke an executable Octave script with command line
  349. arguments, the arguments are available in the built-in variable `argv'.
  350. *Note Command Line Options::.  For example, the following program will
  351. reproduce the command line that is used to execute it.
  352.      #! /bin/octave -qf
  353.      printf ("%s", program_name);
  354.      for i = 1:nargin
  355.        printf (" %s", argv(i,:));
  356.      endfor
  357.      printf ("\n");
  358.    ---------- Footnotes ----------
  359.    (1)  The `#!' mechanism works on Unix systems derived from Berkeley
  360. Unix, System V Release 4, and some System V Release 3 systems.
  361. File: octave,  Node: Comments,  Prev: Executable Octave Programs,  Up: Getting Started
  362. Comments in Octave Programs
  363. ===========================
  364.    A "comment" is some text that is included in a program for the sake
  365. of human readers, and that is not really part of the program.  Comments
  366. can explain what the program does, and how it works.  Nearly all
  367. programming languages have provisions for comments, because programs are
  368. typically hard to understand without them.
  369.    In the Octave language, a comment starts with either the sharp sign
  370. character, `#', or the percent symbol `%' and continues to the end of
  371. the line.  The Octave interpreter ignores the rest of a line following
  372. a sharp sign or percent symbol.  For example, we could have put the
  373. following into the function `f':
  374.      function xdot = f (x, t)
  375.      
  376.      # usage: f (x, t)
  377.      #
  378.      # This function defines the right hand
  379.      # side functions for a set of nonlinear
  380.      # differential equations.
  381.      
  382.        r = 0.25;
  383.        ...
  384.      endfunction
  385.    The `help' command (*note Getting Help::.) is able to find the first
  386. block of comments in a function (even those that are composed directly
  387. on the command line).  This means that users of Octave can use the same
  388. commands to get help for built-in functions, and for functions that you
  389. have defined.  For example, after defining the function `f' above, the
  390. command `help f' produces the output
  391.       usage: f (x, t)
  392.      
  393.       This function defines the right hand
  394.       side functions for a set of nonlinear
  395.       differential equations.
  396.    Although it is possible to put comment lines into keyboard-composed
  397. throw-away Octave programs, it usually isn't very useful, because the
  398. purpose of a comment is to help you or another person understand the
  399. program at a later time.
  400.    % DO NOT EDIT!  Generated automatically by munge-texi.
  401. File: octave,  Node: Data Types,  Next: Numeric Data Types,  Prev: Getting Started,  Up: Top
  402. Data Types
  403. **********
  404.    All versions of Octave include a number of built-in data types,
  405. including real and complex scalars and matrices, character strings, and
  406. a data structure type.
  407.    It is also possible to define new specialized data types by writing a
  408. small amount of C++ code.  On some systems, new data types can be loaded
  409. dynamically while Octave is running, so it is not necessary to recompile
  410. all of Octave just to add a new type.  *Note Dynamically Linked
  411. Functions:: for more information about Octave's dynamic linking
  412. capabilities.  *Note User-defined Data Types:: describes what you must
  413. do to define a new data type for Octave.
  414. * Menu:
  415. * Built-in Data Types::
  416. * User-defined Data Types::
  417. * Object Sizes::
  418. File: octave,  Node: Built-in Data Types,  Next: User-defined Data Types,  Prev: Data Types,  Up: Data Types
  419. Built-in Data Types
  420. ===================
  421.    The standard built-in data types are real and complex scalars and
  422. matrices, ranges, character strings, and a data structure type.
  423. Additional built-in data types may be added in future versions.  If you
  424. need a specialized data type that is not currently provided as a
  425. built-in type, you are encouraged to write your own user-defined data
  426. type and contribute it for distribution in a future release of Octave.
  427. * Menu:
  428. * Numeric Objects::
  429. * String Objects::
  430. * Data Structure Objects::
  431. File: octave,  Node: Numeric Objects,  Next: String Objects,  Prev: Built-in Data Types,  Up: Built-in Data Types
  432. Numeric Objects
  433. ---------------
  434.    Octave's built-in numeric objects include real and complex scalars
  435. and matrices.  All built-in numeric data is currently stored as double
  436. precision numbers.  On systems that use the IEEE floating point format,
  437. values in the range of approximately  2.2251e-308 to 1.7977e+308  can
  438. be stored, and the relative precision is approximately  2.2204e-16.
  439. The exact values are given by the variables `realmin', `realmax', and
  440. `eps', respectively.
  441.    Matrix objects can be of any size, and can be dynamically reshaped
  442. and resized.  It is easy to extract individual rows, columns, or
  443. submatrices using a variety of powerful indexing features.  *Note Index
  444. Expressions::.
  445.    *Note Numeric Data Types::, for more information.
  446. File: octave,  Node: String Objects,  Next: Data Structure Objects,  Prev: Numeric Objects,  Up: Built-in Data Types
  447. String Objects
  448. --------------
  449.    A character string in Octave consists of a sequence of characters
  450. enclosed in either double-quote or single-quote marks.  Internally,
  451. Octave currently stores strings as matrices of characters.  All the
  452. indexing operations that work for matrix objects also work for strings.
  453.    *Note Strings::, for more information.
  454. File: octave,  Node: Data Structure Objects,  Prev: String Objects,  Up: Built-in Data Types
  455. Data Structure Objects
  456. ----------------------
  457.    Octave's data structure type can help you to organize related
  458. objects of different types.  The current implementation uses an
  459. associative array with indices limited to strings, but the syntax is
  460. more like C-style structures.
  461.    *Note Data Structures::, for more information.
  462. File: octave,  Node: User-defined Data Types,  Next: Object Sizes,  Prev: Built-in Data Types,  Up: Data Types
  463. User-defined Data Types
  464. =======================
  465.    Someday I hope to expand this to include a complete description of
  466. Octave's mechanism for managing user-defined data types.  Until this
  467. feature is documented here, you will have to make do by reading the code
  468. in the `ov.h', `ops.h', and related files from Octave's `src' directory.
  469. File: octave,  Node: Object Sizes,  Prev: User-defined Data Types,  Up: Data Types
  470. Object Sizes
  471. ============
  472.    The following functions allow you to determine the size of a
  473. variable or expression.  These functions are defined for all objects.
  474. They return -1 when the operation doesn't make sense.  For example,
  475. Octave's data structure type doesn't have rows or columns, so the
  476. `rows' and `columns' functions return -1 for structure arguments.
  477.  - Function File:  columns (A)
  478.      Return the number of columns of A.
  479.  - Function File:  rows (A)
  480.      Return the number of rows of A.
  481.  - Built-in Function:  length (A)
  482.      Return the `lenghth' of the object A.  For matrix objects, the
  483.      length is the number of rows or columns, whichever is greater (this
  484.      odd definition is used for compatibility with Matlab).
  485.  - Built-in Function:  size (A, N)
  486.      Return the number rows and columns of A.
  487.      With one input argument and one output argument, the result is
  488.      returned in a 2 element row vector.  If there are two output
  489.      arguments, the number of rows is assigned to the first, and the
  490.      number of columns to the second.  For example,
  491.           size ([1, 2; 3, 4; 5, 6])
  492.                => [ 3, 2 ]
  493.           
  494.           [nr, nc] = size ([1, 2; 3, 4; 5, 6])
  495.                => nr = 3
  496.                => nc = 2
  497.      If given a second argument of either 1 or 2, `size' will return
  498.      only the row or column dimension.  For example
  499.           size ([1, 2; 3, 4; 5, 6], 2)
  500.                => 2
  501.      returns the number of columns in the given matrix.
  502.  - Built-in Function:  isempty (A)
  503.      Return 1 if A is an empty matrix (either the number of rows, or
  504.      the number of columns, or both are zero).  Otherwise, return 0.
  505.    % DO NOT EDIT!  Generated automatically by munge-texi.
  506. File: octave,  Node: Numeric Data Types,  Next: Strings,  Prev: Data Types,  Up: Top
  507. Numeric Data Types
  508. ******************
  509.    A "numeric constant" may be a scalar, a vector, or a matrix, and it
  510. may contain complex values.
  511.    The simplest form of a numeric constant, a scalar, is a single number
  512. that can be an integer, a decimal fraction, a number in scientific
  513. (exponential) notation, or a complex number.  Note that all numeric
  514. constants are represented within Octave in double-precision floating
  515. point format (complex constants are stored as pairs of double-precision
  516. floating point values).  Here are some examples of real-valued numeric
  517. constants, which all have the same value:
  518.      105
  519.      1.05e+2
  520.      1050e-1
  521.    To specify complex constants, you can write an expression of the form
  522.      3 + 4i
  523.      3.0 + 4.0i
  524.      0.3e1 + 40e-1i
  525.    all of which are equivalent.  The letter `i' in the previous example
  526. stands for the pure imaginary constant, defined as   `sqrt (-1)'.
  527.    For Octave to recognize a value as the imaginary part of a complex
  528. constant, a space must not appear between the number and the `i'.  If
  529. it does, Octave will print an error message, like this:
  530.      octave:13> 3 + 4 i
  531.      
  532.      parse error:
  533.      
  534.        3 + 4 i
  535.              ^
  536.    You may also use `j', `I', or `J' in place of the `i' above.  All
  537. four forms are equivalent.
  538. * Menu:
  539. * Matrices::
  540. * Ranges::
  541. * Predicates for Numeric Objects::
  542. File: octave,  Node: Matrices,  Next: Ranges,  Prev: Numeric Data Types,  Up: Numeric Data Types
  543. Matrices
  544. ========
  545.    It is easy to define a matrix of values in Octave.  The size of the
  546. matrix is determined automatically, so it is not necessary to explicitly
  547. state the dimensions.  The expression
  548.      a = [1, 2; 3, 4]
  549. results in the matrix
  550.              /      \
  551.              | 1  2 |
  552.        a  =  |      |
  553.              | 3  4 |
  554.              \      /
  555.    Elements of a matrix may be arbitrary expressions, provided that the
  556. dimensions all make sense when combining the various pieces.  For
  557. example, given the above matrix, the expression
  558.      [ a, a ]
  559. produces the matrix
  560.      ans =
  561.      
  562.        1  2  1  2
  563.        3  4  3  4
  564. but the expression
  565.      [ a, 1 ]
  566. produces the error
  567.      error: number of rows must match near line 13, column 6
  568. (assuming that this expression was entered as the first thing on line
  569. 13, of course).
  570.    Inside the square brackets that delimit a matrix expression, Octave
  571. looks at the surrounding context to determine whether spaces and newline
  572. characters should be converted into element and row separators, or
  573. simply ignored, so commands like
  574.      [ linspace (1, 2) ]
  575.      a = [ 1 2
  576.            3 4 ]
  577. will work.  However, some possible sources of confusion remain.  For
  578. example, in the expression
  579.      [ 1 - 1 ]
  580. the `-' is treated as a binary operator and the result is the scalar 0,
  581. but in the expression
  582.      [ 1 -1 ]
  583. the `-' is treated as a unary operator and the result is the vector `[
  584. 1, -1 ]'.
  585.    Given `a = 1', the expression
  586.      [ 1 a' ]
  587. results in the single quote character `'' being treated as a transpose
  588. operator and the result is the vector `[ 1, 1 ]', but the expression
  589.      [ 1 a ' ]
  590. produces the error message
  591.      error: unterminated string constant
  592. because to not do so would make it impossible to correctly parse the
  593. valid expression
  594.      [ a 'foo' ]
  595.    For clarity, it is probably best to always use commas and semicolons
  596. to separate matrix elements and rows.  It is possible to enforce this
  597. style by setting the built-in variable `whitespace_in_literal_matrix' to
  598. `"ignore"'.
  599.    control auto-insertion of commas and semicolons in literal matrices
  600.    When you type a matrix or the name of a variable whose value is a
  601. matrix, Octave responds by printing the matrix in with neatly aligned
  602. rows and columns.  If the rows of the matrix are too large to fit on the
  603. screen, Octave splits the matrix and displays a header before each
  604. section to indicate which columns are being displayed.  You can use the
  605. following variables to control the format of the output.
  606.  - Built-in Variable: output_max_field_width
  607.      This variable specifies the maximum width of a numeric output
  608.      field.  The default value is 10.
  609.  - Built-in Variable: output_precision
  610.      This variable specifies the minimum number of significant figures
  611.      to display for numeric output.  The default value is 5.
  612.    It is possible to achieve a wide range of output styles by using
  613. different values of `output_precision' and `output_max_field_width'.
  614. Reasonable combinations can be set using the `format' function.  *Note
  615. Basic Input and Output::.
  616.  - Built-in Variable: split_long_rows
  617.      For large matrices, Octave may not be able to display all the
  618.      columns of a given row on one line of your screen.  This can
  619.      result in missing information or output that is nearly impossible
  620.      to decipher, depending on whether your terminal truncates or wraps
  621.      long lines.
  622.      If the value of `split_long_rows' is nonzero, Octave will display
  623.      the matrix in a series of smaller pieces, each of which can fit
  624.      within the limits of your terminal width.  Each set of rows is
  625.      labeled so that you can easily see which columns are currently
  626.      being displayed.  For example:
  627.           octave:13> rand (2,10)
  628.           ans =
  629.           
  630.            Columns 1 through 6:
  631.           
  632.             0.75883  0.93290  0.40064  0.43818  0.94958  0.16467
  633.             0.75697  0.51942  0.40031  0.61784  0.92309  0.40201
  634.           
  635.            Columns 7 through 10:
  636.           
  637.             0.90174  0.11854  0.72313  0.73326
  638.             0.44672  0.94303  0.56564  0.82150
  639.      The default value of `split_long_rows' is nonzero.
  640.    Octave automatically switches to scientific notation when values
  641. become very large or very small.  This guarantees that you will see
  642. several significant figures for every value in a matrix.  If you would
  643. prefer to see all values in a matrix printed in a fixed point format,
  644. you can set the built-in variable `fixed_point_format' to a nonzero
  645. value.  But doing so is not recommended, because it can produce output
  646. that can easily be misinterpreted.
  647.  - Built-in Variable: fixed_point_format
  648.      If the value of this variable is nonzero, Octave will scale all
  649.      values in a matrix so that the largest may be written with one
  650.      leading digit.  The scaling factor is printed on the first line of
  651.      output.  For example,
  652.           octave:1> logspace (1, 7, 5)'
  653.           ans =
  654.           
  655.             1.0e+07  *
  656.           
  657.             0.00000
  658.             0.00003
  659.             0.00100
  660.             0.03162
  661.             1.00000
  662.      Notice that first value appears to be zero when it is actually 1.
  663.      For this reason, you should be careful when setting
  664.      `fixed_point_format' to a nonzero value.
  665.      The default value of `fixed_point_format' is 0.
  666. * Menu:
  667. * Empty Matrices::
  668. File: octave,  Node: Empty Matrices,  Prev: Matrices,  Up: Matrices
  669. Empty Matrices
  670. --------------
  671.    A matrix may have one or both dimensions zero, and operations on
  672. empty matrices are handled as described by Carl de Boor in `An Empty
  673. Exercise', SIGNUM, Volume 25, pages 2-6, 1990 and C. N. Nett and W. M.
  674. Haddad, in `A System-Theoretic Appropriate Realization of the Empty
  675. Matrix Concept', IEEE Transactions on Automatic Control, Volume 38,
  676. Number 5, May 1993.  Briefly, given a scalar S, an M by N matrix
  677. `M(mxn)', and an M by N empty matrix `[](mxn)' (with either one or both
  678. dimensions equal to zero), the following are true:
  679.      s * [](mxn) = [](mxn) * s = [](mxn)
  680.      
  681.          [](mxn) + [](mxn) = [](mxn)
  682.      
  683.          [](0xm) *  M(mxn) = [](0xn)
  684.      
  685.           M(mxn) * [](nx0) = [](mx0)
  686.      
  687.          [](mx0) * [](0xn) =  0(mxn)
  688.    By default, dimensions of the empty matrix are printed along with the
  689. empty matrix symbol, `[]'.  The built-in variable
  690. `print_empty_dimensions' controls this behavior.
  691.  - Built-in Variable: print_empty_dimensions
  692.      If the value of `print_empty_dimensions' is nonzero, the
  693.      dimensions of empty matrices are printed along with the empty
  694.      matrix symbol, `[]'.  For example, the expression
  695.           zeros (3, 0)
  696.      will print
  697.           ans = [](3x0)
  698.    Empty matrices may also be used in assignment statements as a
  699. convenient way to delete rows or columns of matrices.  *Note Assignment
  700. Expressions: Assignment Ops.
  701.    Octave will normally issue a warning if it finds an empty matrix in
  702. the list of elements that make up another matrix.  You can use the
  703. variable `empty_list_elements_ok' to suppress the warning or to treat
  704. it as an error.
  705.  - Built-in Variable: empty_list_elements_ok
  706.      This variable controls whether Octave ignores empty matrices in a
  707.      matrix list.
  708.      For example, if the value of `empty_list_elements_ok' is nonzero,
  709.      Octave will ignore the empty matrices in the expression
  710.           a = [1, [], 3, [], 5]
  711.      and the variable `a' will be assigned the value `[ 1, 3, 5 ]'.
  712.      The default value is `"warn"'.
  713.    When Octave parses a matrix expression, it examines the elements of
  714. the list to determine whether they are all constants.  If they are, it
  715. replaces the list with a single matrix constant.
  716.  - Built-in Variable: propagate_empty_matrices
  717.      If the value of `propagate_empty_matrices' is nonzero, functions
  718.      like `inverse' and `svd' will return an empty matrix if they are
  719.      given one as an argument.  The default value is 1.
  720. File: octave,  Node: Ranges,  Next: Predicates for Numeric Objects,  Prev: Matrices,  Up: Numeric Data Types
  721. Ranges
  722. ======
  723.    A "range" is a convenient way to write a row vector with evenly
  724. spaced elements.  A range expression is defined by the value of the
  725. first element in the range, an optional value for the increment between
  726. elements, and a maximum value which the elements of the range will not
  727. exceed.  The base, increment, and limit are separated by colons (the
  728. `:' character) and may contain any arithmetic expressions and function
  729. calls.  If the increment is omitted, it is assumed to be 1.  For
  730. example, the range
  731.      1 : 5
  732. defines the set of values `[ 1, 2, 3, 4, 5 ]', and the range
  733.      1 : 3 : 5
  734. defines the set of values `[ 1, 4 ]'.
  735.    Although a range constant specifies a row vector, Octave does *not*
  736. convert range constants to vectors unless it is necessary to do so.
  737. This allows you to write a constant like `1 : 10000' without using
  738. 80,000 bytes of storage on a typical 32-bit workstation.
  739.    Note that the upper (or lower, if the increment is negative) bound on
  740. the range is not always included in the set of values, and that ranges
  741. defined by floating point values can produce surprising results because
  742. Octave uses floating point arithmetic to compute the values in the
  743. range.  If it is important to include the endpoints of a range and the
  744. number of elements is known, you should use the `linspace' function
  745. instead (*note Special Utility Matrices::.).
  746.    When Octave parses a range expression, it examines the elements of
  747. the expression to determine whether they are all constants.  If they
  748. are, it replaces the range expression with a single range constant.
  749. File: octave,  Node: Predicates for Numeric Objects,  Prev: Ranges,  Up: Numeric Data Types
  750. Predicates for Numeric Objects
  751. ==============================
  752.  - Built-in Function:  is_matrix (A)
  753.      Return 1 if A is a matrix.  Otherwise, return 0.
  754.  - Function File:  is_vector (A)
  755.      Return 1 if A is a vector.  Otherwise, return 0.
  756.  - Function File:  is_scalar (A)
  757.      Return 1 if A is a scalar.  Otherwise, return 0.
  758.  - Function File:  is_square (X)
  759.      If X is a square matrix, then return the dimension of X.
  760.      Otherwise, return 0.
  761.  - Function File:  is_symmetric (X, TOL)
  762.      If X is symmetric within the tolerance specified by TOL,  then
  763.      return the dimension of X.  Otherwise, return 0.  If TOL is
  764.      omitted, use a tolerance equal to the machine precision.
  765.    % DO NOT EDIT!  Generated automatically by munge-texi.
  766. File: octave,  Node: Strings,  Next: Data Structures,  Prev: Numeric Data Types,  Up: Top
  767. Strings
  768. *******
  769.    A "string constant" consists of a sequence of characters enclosed in
  770. either double-quote or single-quote marks.  For example, both of the
  771. following expressions
  772.      "parrot"
  773.      'parrot'
  774. represent the string whose contents are `parrot'.  Strings in Octave
  775. can be of any length.
  776.    Since the single-quote mark is also used for the transpose operator
  777. (*note Arithmetic Ops::.) but double-quote marks have no other purpose
  778. in Octave, it is best to use double-quote marks to denote strings.
  779.    Some characters cannot be included literally in a string constant.
  780. You represent them instead with "escape sequences", which are character
  781. sequences beginning with a backslash (`\').
  782.    One use of an escape sequence is to include a double-quote
  783. (single-quote) character in a string constant that has been defined
  784. using double-quote (single-quote) marks.  Since a plain double-quote
  785. would end the string, you must use `\"' to represent a single
  786. double-quote character as a part of the string.  The backslash character
  787. itself is another character that cannot be included normally.  You must
  788. write `\\' to put one backslash in the string.  Thus, the string whose
  789. contents are the two characters `"\' may be written `"\"\\"' or
  790. `'"\\''.  Similarly, the string whose contents are the two characters
  791. `'\' may be written `'\'\\'' or `"'\\"'.
  792.    Another use of backslash is to represent unprintable characters such
  793. as newline.  While there is nothing to stop you from writing most of
  794. these characters directly in a string constant, they may look ugly.
  795.    Here is a table of all the escape sequences used in Octave.  They are
  796. the same as those used in the C programming language.
  797.      Represents a literal backslash, `\'.
  798.      Represents a literal double-quote character, `"'.
  799.      Represents a literal single-quote character, `''.
  800.      Represents the "alert" character, control-g, ASCII code 7.
  801.      Represents a backspace, control-h, ASCII code 8.
  802.      Represents a formfeed, control-l, ASCII code 12.
  803.      Represents a newline, control-j, ASCII code 10.
  804.      Represents a carriage return, control-m, ASCII code 13.
  805.      Represents a horizontal tab, control-i, ASCII code 9.
  806.      Represents a vertical tab, control-k, ASCII code 11.
  807.    Strings may be concatenated using the notation for defining matrices.
  808. For example, the expression
  809.      [ "foo" , "bar" , "baz" ]
  810. produces the string whose contents are `foobarbaz'.  *Note Numeric Data
  811. Types:: for more information about creating matrices.
  812. * Menu:
  813. * Creating Strings::
  814. * Searching and Replacing::
  815. * String Conversions::
  816. * Character Class Functions::
  817. File: octave,  Node: Creating Strings,  Next: Searching and Replacing,  Prev: Strings,  Up: Strings
  818. Creating Strings
  819. ================
  820.  - Function File:  blanks (N)
  821.      Return a string of N blanks.
  822.  - Function File:  int2str (N)
  823.  - Function File:  num2str (X)
  824.      Convert a number to a string.  These functions are not very
  825.      flexible,  but are provided for compatibility with MATLAB.  For
  826.      better control  over the results, use `sprintf' (*note Formatted
  827.      Output::.).
  828.  - Built-in Function:  setstr (X)
  829.      Convert a matrix to a string.  Each element of the matrix is
  830.      converted to the corresponding ASCII character.  For example,
  831.           setstr ([97, 98, 99])
  832.                => "abc"
  833.  - Function File:  strcat (S1, S2, ...)
  834.      Return a string containing all the arguments concatenated.  For
  835.      example,
  836.            s = [ "ab"; "cde" ];
  837.            strcat (s, s, s)
  838.           => "ab ab ab "
  839.                    "cdecdecde"
  840.  - Built-in Variable: string_fill_char
  841.      The value of this variable is used to pad all strings in a string
  842.      matrix to the same length.  It should be a single character.  The
  843.      default value is `" "' (a single space).  For example,
  844.           string_fill_char = "X";
  845.           [ "these"; "are"; "strings" ]
  846.                => "theseXX"
  847.                   "areXXXX"
  848.                   "strings"
  849.  - Function File:  str2mat (S_1, ..., S_N)
  850.      Return a matrix containing the strings S_1, ..., S_N as  its rows.
  851.      Each string is padded with blanks in order to form a valid
  852.      matrix.
  853.      *Note:*  This function is modelled after MATLAB.  In Octave, you
  854.      can create  a matrix of strings by `[S_1; ...; S_N]' even if  the
  855.      strings are not all the same length.
  856.  - Built-in Function:  isstr (A)
  857.      Return 1 if A is a string.  Otherwise, return 0.
  858. File: octave,  Node: Searching and Replacing,  Next: String Conversions,  Prev: Creating Strings,  Up: Strings
  859. Searching and Replacing
  860. =======================
  861.  - Function File:  deblank (S)
  862.      Removes the trailing blanks from the string S.
  863.  - Function File:  findstr (S, T, OVERLAP)
  864.      Return the vector of all positions in the longer of the two strings
  865.      S and T where an occurrence of the shorter of the two starts.   If
  866.      the optional argument OVERLAP is nonzero, the returned vector  can
  867.      include overlapping positions (this is the default).  For example,
  868.            findstr ("ababab", "a")
  869.           => [ 1, 3, 5 ]
  870.            findstr ("abababa", "aba", 0)
  871.           => [ 1, 5 ]
  872.  - Function File:  index (S, T)
  873.      Return the position of the first occurrence of the string T in the
  874.      string S, or 0 if no occurrence is found.  For example,
  875.            index ("Teststring", "t")
  876.           => 4
  877.      *Note:*  This function does not work for arrays of strings.
  878.  - Function File:  rindex (S, T)
  879.      Return the position of the last occurrence of the string T in the
  880.      string S, or 0 if no occurrence is found.  For example,
  881.            rindex ("Teststring", "t")
  882.           => 6
  883.      *Note:*  This function does not work for arrays of strings.
  884.  - Function File:  split (S, T)
  885.      Divides the string S into pieces separated by T, returning  the
  886.      result in a string array (padded with blanks to form a valid
  887.      matrix).  For example,
  888.            split ("Test string", "t")
  889.           => "Tes "
  890.                    " s  "
  891.                    "ring"
  892.  - Function File:  strcmp (S1, S2)
  893.      Compares two strings, returning 1 if they are the same, and 0
  894.      otherwise.
  895.      *Note:*  For compatibility with MATLAB, Octave's strcmp  function
  896.      returns 1 if the strings are equal, and 0 otherwise.  This is
  897.      just the opposite of the corresponding C library function.
  898.  - Function File:  strrep (S, X, Y)
  899.      Replaces all occurrences of the substring X of the string S  with
  900.      the string Y.  For example,
  901.            strrep ("This is a test string", "is", "&%$")
  902.           => "Th&%$ &%$ a test string"
  903.  - Function File:  substr (S, BEG, LEN)
  904.      Return the substring of S which starts at character number BEG and
  905.      is LEN characters long.
  906.      If OFFSET is negative, extraction starts that far from the end of
  907.      the string.  If LEN is omitted, the substring extends to the end
  908.      of S.
  909.      For example,
  910.            substr ("This is a test string", 6, 9)
  911.           => "is a test"
  912.           *Note:*  This function is patterned after AWK.  You can get
  913.           the same result by `S (BEG : (BEG + LEN - 1))'.
  914. File: octave,  Node: String Conversions,  Next: Character Class Functions,  Prev: Searching and Replacing,  Up: Strings
  915. String Conversions
  916. ==================
  917.    usage:  bin2dec (x)
  918.    Returns the decimal number corresponding to the binary number in
  919. quotes.  For example, bin2dec ("1110") returns 14.
  920.  - Function File:  dec2bin (N)
  921.      Return a binary number corresponding the nonnegative decimal number
  922.      N, as a string of ones and zeros.  For example,
  923.            dec2bin (14)
  924.           => "1110"
  925.  - Function File:  dec2hex (N)
  926.      Return the hexadecimal number corresponding to the nonnegative
  927.      decimal  number N, as a string.  For example,
  928.            dec2hex (2748)
  929.           => "abc"
  930.  - Function File:  hex2dec (S)
  931.      Return the decimal number corresponding to the hexadecimal number
  932.      stored  in the string S.  For example,
  933.            hex2dec ("12B")
  934.           => 299
  935.            hex2dec ("12b")
  936.           => 299
  937.  - Function File:  str2num (S)
  938.      Convert the string S to a number.
  939.  - Mapping Function:  toascii (S)
  940.      Return ASCII representation of S in a matrix.  For example,
  941.           toascii ("ASCII")
  942.                => [ 65, 83, 67, 73, 73 ]
  943.  - Mapping Function:  tolower (S)
  944.      Return a copy of the string S, with each upper-case character
  945.      replaced by the corresponding lower-case one; nonalphabetic
  946.      characters are left unchanged.  For example,
  947.           tolower ("MiXeD cAsE 123")
  948.                => "mixed case 123"
  949.  - Built-in Function:  toupper (S)
  950.      Return a copy of the string S, with each  lower-case character
  951.      replaced by the corresponding upper-case one; nonalphabetic
  952.      characters are left unchanged.  For example,
  953.           toupper ("MiXeD cAsE 123")
  954.                => "MIXED CASE 123"
  955.  - Built-in Function:  undo_string_escapes (S)
  956.      Converts special characters in strings back to their escaped
  957.      forms.  For example, the expression
  958.           bell = "\a";
  959.      assigns the value of the alert character (control-g, ASCII code 7)
  960.      to the string variable `bell'.  If this string is printed, the
  961.      system will ring the terminal bell (if it is possible).  This is
  962.      normally the desired outcome.  However, sometimes it is useful to
  963.      be able to print the original representation of the string, with
  964.      the special characters replaced by their escape sequences.  For
  965.      example,
  966.           octave:13> undo_string_escapes (bell)
  967.           ans = \a
  968.      replaces the unprintable alert character with its printable
  969.      representation.
  970.  - Built-in Variable: implicit_num_to_str_ok
  971.      If the value of `implicit_num_to_str_ok' is nonzero, implicit
  972.      conversions of numbers to their ASCII character equivalents are
  973.      allowed when strings are constructed using a mixture of strings and
  974.      numbers in matrix notation.  Otherwise, an error message is
  975.      printed and control is returned to the top level. The default
  976.      value is 0.  For example,
  977.           [ "f", 111, 111 ]
  978.                => "foo"
  979.  - Built-in Variable: implicit_str_to_num_ok
  980.      If the value of `implicit_str_to_num_ok' is nonzero, implicit
  981.      conversions of strings to their numeric ASCII equivalents are
  982.      allowed.  Otherwise, an error message is printed and control is
  983.      returned to the top level.  The default value is 0.
  984. File: octave,  Node: Character Class Functions,  Prev: String Conversions,  Up: Strings
  985. Character Class Functions
  986. =========================
  987.    Octave also provides the following character class test functions
  988. patterned after the functions in the standard C library.  They all
  989. operate on string arrays and return matrices of zeros and ones.
  990. Elements that are nonzero indicate that the condition was true for the
  991. corresponding character in the string array.  For example,
  992.      isalpha ("!Q@WERT^Y&")
  993.           => [ 0, 1, 0, 1, 1, 1, 1, 0, 1, 0 ]
  994.  - Mapping Function:  isalnum (S)
  995.      Return 1 for characters that are letters or digits (`isalpha (A)'
  996.      or `isdigit (A)' is true).
  997.  - Mapping Function:  isalpha (S)
  998.      Return true for characters that are letters (`isupper (A)' or
  999.      `islower ()' is true).
  1000.  - Mapping Function:  isascii (S)
  1001.      Return 1 for characters that are ASCII (in the range 0 to 127
  1002.      decimal).
  1003.  - Mapping Function:  iscntrl (S)
  1004.      Return 1 for control characters.
  1005.  - Mapping Function:  isdigit (S)
  1006.      Return 1 for characters that are decimal digits.
  1007.  - Mapping Function:  isgraph (S)
  1008.      Return 1 for printable characters (but not the space character).
  1009.  - Mapping Function:  islower (S)
  1010.      Return 1 for characters that are lower case letters.
  1011.  - Mapping Function:  isprint (S)
  1012.      Return 1 for printable characters (including the space character).
  1013.  - Mapping Function:  ispunct (S)
  1014.      Return 1 for punctuation characters.
  1015.  - Mapping Function:  isspace (S)
  1016.      Return 1 for whitespace characters (space, formfeed, newline,
  1017.      carriage return, tab, and vertical tab).
  1018.  - Mapping Function:  isupper (S)
  1019.      Return 1 for upper case letters.
  1020.  - Mapping Function:  isxdigit (S)
  1021.      Return 1 for characters that are hexadecimal digits.
  1022.    % DO NOT EDIT!  Generated automatically by munge-texi.
  1023.