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 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: String Functions,  Next: System Utilities,  Prev: Matrix Manipulation,  Up: Top

String Functions
****************

 - 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:  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])

     creates the string

          abc

 - 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.

 - 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.  *Note String Constants::, for a description of
     string escapes.

 - Function File:  bin2dec (S)
     Given a binary number represented as a string of zeros and ones,
     returns the corresponding decimal number.  For example,

          bin2dec ("1110")
              => 14

 - Function File:  blanks (varn)
     Returns a string of N blanks.

 - Function File:  deblank (S)
     Removes the trailing blanks from the string S.

 - Function File:  dec2bin (N)
     Given a nonnegative integer, returns the corresponding binary
     number as a string of ones and zeros.  For example,

          dec2bin (14)
            => "1110"

 - Function File:  dec2hex (N)
     Given a nonnegative integer, returns the corresponding hexadecimal
     number as a string.  For example,

          dec2hex (2748)
             => "abc"

 - Function File:  findstr (S, T, OVERLAP)
     Returns the vector of all positions in the longer of the two
     strings S and T where an occurence 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:  hex2dec (S)
     Given a hexadecimal number represented as a string, returns the
     corresponding decimal number.  For example,

          hex2dec ("12B")
             => 299
          hex2dec ("12b")
             => 299

 - Function File:  index (S, T)
     Returns the position of the first occurence of the string T in the
     string S, or 0 if no occurence is found.  For example,

          index ("Teststring", "t")
             => 4

     *Note:*  This function does not work for arrays of strings.

 - Function File:  rindex (S, T)
     Returns the position of the last occurence of the string T in the
     string S, or 0 if no occurence 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:  str2mat (S_1, ..., S_N)
     Returns 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]'.

 - Built-in Variable: string_fill_char

 - Function File:  strrep (S, X, Y)
     Replaces all occurences 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)
     Returns 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))'.

 - 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)
     Returns 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"

 - Function File:  toascii (S)
     Return ASCII representation of S in a matrix.  For example,

          toascii ("ASCII")
             => [ 65, 83, 67, 73, 73 ]


   Octave also provides the following C-type character class test
functions.  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.

 - Mapping Function:  isalnum (S)
     letter or a digit

 - Mapping Function:  isalpha (S)
     letter

 - Mapping Function:  isascii (S)
     ascii

 - Mapping Function:  iscntrl (S)
     control character

 - Mapping Function:  isdigit (S)
     digit

 - Mapping Function:  isgraph (S)
     printable (but not space character)

 - Mapping Function:  islower (S)
     lower case

 - Mapping Function:  isprint (S)
     printable (including space character)

 - Mapping Function:  ispunct (S)
     punctuation

 - Mapping Function:  isspace (S)
     whitespace

 - Mapping Function:  isupper (S)
     upper case

 - Mapping Function:  isxdigit (S)
     hexadecimal digit


File: octave,  Node: System Utilities,  Next: Command History Functions,  Prev: String Functions,  Up: Top

System Utilities
****************

   This chapter describes the functions that are available to allow you
to get information about what is happening outside of Octave, while it
is still running, and use this information in your program.  For
example, you can get information about environment variables, the
current time, and even start other programs from the Octave prompt.

* Menu:

* Timing Utilities::
* Filesystem Utilities::
* Interacting with the OS::
* Password Database Functions::
* Group Database Functions::
* System Information::
* Other Functions::


File: octave,  Node: Timing Utilities,  Next: Filesystem Utilities,  Prev: System Utilities,  Up: System Utilities

Timing Utilities
================

 - Loadable Function:  time ()
     Return the current time as the number of seconds since the epoch.
     The epoch is referenced to 00:00:00 CUT (Coordinated Universal
     Time) 1 Jan 1970.

   Several of Octave's time functions a data structure for time that
includes the following elements:

`usec'
     Microseconds after the second (0-999999).

`sec'
     Seconds after the minute (0-61).  This number can be 61 to account
     for leap seconds.

`min'
     Minutes after the hour (0-59).

`hour'
     Hours since midnight (0-23).

`mday'
     Day of the month (1-31).

`mon'
     Months since January (0-11).

`year'
     Years since 1900.

`wday'
     Days since Sunday (0-6).

`yday'
     Days since January 1 (0-365).

`isdst'
     Daylight Savings Time flag.

`zone'
     Time zone.

 - Loadable Function:  mktime (TIME_STRUCT)
     Convert a time structure to the number of seconds since the epoch.

 - Loadable Function:  localtime (T)
     Given a value returned from time (or any nonnegative integer),
     return a time structure corresponding to the local time zone.

 - Loadable Function:  gmtime (T)
     Given a value returned from time (or any nonnegative integer),
     return a time structure corresponding to CUT.

 - Function File:  asctime (TIME_STRUCT)
     Convert a time structure to a string using the following five-field
     format: Thu Mar 28 08:40:14 1996.  The function `ctime (time)' is
     equivalent to `asctime (localtime (time))'.

 - Loadable Function:  strftime (TIME_STRUCT)
     Format a time structure in a flexible way using `%' substitutions
     similar to those in `printf'.  Except where noted, substituted
     fields have a fixed size; numeric fields are padded if necessary.
     Padding is with zeros by default; for fields that display a single
     number, padding can be changed or inhibited by following the `%'
     with one of the modifiers described below.  Unknown field
     specifiers are copied as normal characters.  All other characters
     are copied to the output without change.

     Octave's `strftime' function supports a superset of the ANSI C
     field specifiers.

     Literal character fields:

    `%'
          % character.

    `n'
          Newline character.

    `t'
          Tab character.

     Numeric modifiers (a nonstandard extension):

    `-'
          Do not pad the field.

    `_'
          Pad the field with spaces.

     Time fields:

    `%H'
          Hour (00-23).

    `%I'
          Hour (01-12).

    `%k'
          Hour (0-23).

    `%l'
          Hour (1-12).

    `%M'
          Minute (00-59).

    `%p'
          Locale's AM or PM.

    `%r'
          Time, 12-hour (hh:mm:ss [AP]M).

    `%R'
          Time, 24-hour (hh:mm).

    `%s'
          Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard
          extension).

    `%S'
          Second (00-61).

    `%T'
          Time, 24-hour (hh:mm:ss).

    `%X'
          Locale's time representation (%H:%M:%S).

    `%Z'
          Time zone (EDT), or nothing if no time zone is determinable.

     Date fields:

    `%a'
          Locale's abbreviated weekday name (Sun-Sat).

    `%A'
          Locale's full weekday name, variable length (Sunday-Saturday).

    `%b'
          Locale's abbreviated month name (Jan-Dec).

    `%B'
          Locale's full month name, variable length (January-December).

    `%c'
          Locale's date and time (Sat Nov 04 12:02:33 EST 1989).

    `%C'
          Century (00-99).

    `%d'
          Day of month (01-31).

    `%e'
          Day of month ( 1-31).

    `%D'
          Date (mm/dd/yy).

    `%h'
          Same as %b.

    `%j'
          Day of year (001-366).

    `%m'
          Month (01-12).

    `%U'
          Week number of year with Sunday as first day of week (00-53).

    `%w'
          Day of week (0-6).

    `%W'
          Week number of year with Monday as first day of week (00-53).

    `%x'
          Locale's date representation (mm/dd/yy).

    `%y'
          Last two digits of year (00-99).

    `%Y'
          Year (1970-).

 - Function File:  clock ()
     Return a vector containing the current year, month (1-12), day
     (1-31), hour (0-23), minute (0-59) and second (0-61).  For example,

          octave:13> clock
          ans =
          
            1993     8    20     4    56     1

     The function clock is more accurate on systems that have the
     `gettimeofday' function.

 - Function File:  date ()
     Returns the date as a character string in the form DD-MMM-YY.  For
     example,

          octave:13> date
          ans = 20-Aug-93

 - Function File:  tic ()
 - Function File:  toc ()
     These functions set and check a wall-clock timer.  For example,

          tic ();
          # many computations later...
          elapsed_time = toc ();

     will set the variable `elapsed_time' to the number of seconds since
     the most recent call to the function `tic'.

 - Function File:  etime (T1, T2)
     Return the difference (in seconds) between two time values
     returned from `clock'.  For example:

          t0 = clock ();
          # many computations later...
          elapsed_time = etime (clock (), t0);

     will set the variable `elapsed_time' to the number of seconds since
     the variable `t0' was set.

 - Built-in Function: [TOTAL, USER, SYSTEM] = cputime ();
     Return the CPU time used by your Octave session.  The first output
     is the total time spent executing your process and is equal to the
     sum of second and third outputs, which are the number of CPU
     seconds spent executing in user mode and the number of CPU seconds
     spent executing in system mode, respectively.  If your system does
     not have a way to report CPU time usage, `cputime' returns 0 for
     each of its output values.

 - Function File:  is_leap_year (YEAR)
     Return 1 if the given year is a leap year and 0 otherwise.  If no
     arguments are provided, `is_leap_year' will use the current year.
     For example,

          octave:13> is_leap_year (2000)
          ans = 1


File: octave,  Node: Filesystem Utilities,  Next: Interacting with the OS,  Prev: Timing Utilities,  Up: System Utilities

Filesystem Utilities
====================

   Octave includes the following functions for renaming and deleting
files, creating, deleting, and reading directories, and for getting
information about the status of files.

 - Built-in Function:  rename (FROM, TO)
     Rename a file.

 - Built-in Function:  unlink (FILE)
     Delete a file.

 - Built-in Function:  readdir (DIR)
     Returns names of files in the directory DIR as an array of strings.

 - Built-in Function:  mkdir (DIR)
     Create a directory

 - Built-in Function:  rmdir (DIR)
     Remove a directory.

 - Built-in Function:  umask (MASK)
     Set permission mask for file creation.

 - Built-in Function:  stat (FILE)
     Get information about a file.  If FILE is a symbolic link, `stat'
     returns information about the file that the symbolic link
     references.

 - Built-in Function:  lstat (FILE)
     Get information about a symbolic link.  If FILE is not a symbolic
     link, `lstat' is equivalent to `stat'.


File: octave,  Node: Interacting with the OS,  Next: Password Database Functions,  Prev: Filesystem Utilities,  Up: System Utilities

Interacting with the OS
=======================

 - Built-in Function:  fork ()
     Create a copy of the current process.

 - Built-in Function:  exec (FILE, ARGS)
     Replace current process with a new process.

 - Built-in Function: fid = dup2 (OLD, NEW)
     Duplicate a file descriptor.

 - Built-in Function: [FILE_IDS, STATUS] = pipe ()
     Create an interprocess channel.

 - Built-in Function:  fcntl (FID, REQUEST, ARGUMENT)
     Control open file descriptors.

    `F_DUPFD'
    `F_GETFD'
    `F_GETFL'
    `F_SETFD'
    `F_SETFL'
    `O_APPEND'
    `O_CREAT'
    `O_EXCL'
    `O_NONBLOCK'
    `O_RDONLY'
    `O_RDWR'
    `O_TRUNC'
    `O_WRONLY'

 - Built-in Function:  getpgrp ()
     Return the process group id of the current process.

 - Built-in Function:  getpid ()
     Return the process id of the current process.

 - Built-in Function:  getppid ()
     Return the process id of the parent process.

 - Built-in Function:  geteuid ()
     Return the effective user id of the current process.

 - Built-in Function:  getuid ()
     Return the real user id of the current process.

 - Built-in Function:  getegid ()
     Return the effective group id of the current process.

 - Built-in Function:  getgid ()
     Return the real group id of the current process.

 - Built-in Function:  mkfifo
     Create a FIFO special file.

 - Built-in Function:  waitpid
     Check the status of or wait for subprocesses.

 - Built-in Function:  atexit (FCN)
     Register function to be called when Octave exits.

 - Built-in Function:  system (STRING, RETURN_OUTPUT, TYPE)
     Execute a shell command specified by STRING.  The second argument
     is optional.  If TYPE is `"async"', the process is started in the
     background and the process id of the child proces is returned
     immediately.  Otherwise, the process is started, and Octave waits
     until it exits.  If TYPE argument is omitted, a value of `"sync"'
     is assumed.

     If two input arguments are given (the actual value of
     RETURN_OUTPUT is irrelevant) and the subprocess is started
     synchronously, or if SYSTEM is called with one input argument and
     one or more output arguments, the output from the command is
     returned.  Otherwise, if the subprocess is executed synchronously,
     it's output is sent to the standard output.  To send the output of
     a command executed with SYSTEM through the pager, use a command
     like

          disp (system (cmd, 1));

     or

          printf ("%s\n", system (cmd, 1));

     The `system' function can return two values.  The first is any
     output from the command that was written to the standard output
     stream, and the second is the output status of the command.  For
     example,

          [output, status] = system ("echo foo; exit 2");

     will set the variable `output' to the string `foo', and the
     variable `status' to the integer `2'.

 - Built-in Variable: EXEC_PATH
     The variable `EXEC_PATH' is a colon separated list of directories
     to search when executing subprograms.  Its initial value is taken
     from the environment variable `OCTAVE_EXEC_PATH' (if it exists) or
     `PATH', but that value can be overridden by the the command line
     argument `--exec-path PATH', or by setting the value of
     `EXEC_PATH' in a startup script.  If the value of `EXEC_PATH'
     begins (ends) with a colon, the directories
     `OCTAVE_HOME/libexec/octave/site/exec/ARCH',
     `OCTAVE_HOME/libexec/octave/VERSION/exec/ARCH' and
     `OCTAVE_HOME/bin' are prepended (appended) to `EXEC_PATH', where
     `OCTAVE_HOME' is the top-level directory where all of Octave is
     installed (`/usr/local' by default).  If you don't specify a value
     for `EXEC_PATH' explicitly, these special directories are
     prepended to your shell path.

 - Built-in Function:  getenv (VAR)
     Returns the value of the environment variable VAR.  For example,

          getenv ("PATH")

     returns a string containing the value of your path.

 - Built-in Function:  putenv (VAR, VALUE)
     Set the value of the environment variable VAR to VALUE.

 - Built-in Function:  clc ()
 - Built-in Function:  home ()
     Clear the terminal screen and move the cursor to the upper left
     corner.

 - Command: cd DIR
 - Command: chdir DIR
     Change the current working directory to DIR.  For example,

          cd ~/octave

     Changes the current working directory to `~/octave'.  If the
     directory does not exist, an error message is printed and the
     working directory is not changed.

 - Built-in Function:  pwd ()
     Returns the current working directory.

 - Built-in Variable: PWD
     The current working directory.  The value of `PWD' is updated each
     time the current working directory is changed with the `cd'
     command.

 - Command: ls
 - Command: dir
     List directory contents.  For example,

          octave:13> ls -l
          total 12
          -rw-r--r--   1 jwe      users        4488 Aug 19 04:02 foo.m
          -rw-r--r--   1 jwe      users        1315 Aug 17 23:14 bar.m

     The `dir' and `ls' commands are implemented by calling your
     system's directory listing command, so the available options may
     vary from system to system.


File: octave,  Node: Password Database Functions,  Next: Group Database Functions,  Prev: Interacting with the OS,  Up: System Utilities

Password Database Functions
===========================

   Octave's password database functions return information in a
structure with the following fields.

`name'
     The user name.

`passwd'
     The encrypted password, if available.

`uid'
     The numeric user id.

`gid'
     The numeric group id.

`gecos'
     The GECOS field.

`dir'
     The home directory.

`shell'
     The initial shell.

 - Loadable Function: passwd_struct = getpwent ()
     Return an entry from the password database, opening it if
     necessary.  Once the end of the data has been reached, `getpwent'
     returns 0.

 - Loadable Function: passwd_struct = getpwuid (UID).
     Return the first entry from the password database with the user ID
     UID.  If the user ID does not exist in the database, `getpwuid'
     returns 0.

 - Loadable Function: passwd_struct = getpwnam (NAME)
     Return the first entry from the password database with the user
     name NAME.  If the user name does not exist in the database,
     `getpwname' returns 0.

 - Loadable Function:  setpwent ()
     Return the internal pointer to the beginning of the password
     database.

 - Loadable Function:  endpwent ()
     Close the password database.


File: octave,  Node: Group Database Functions,  Next: System Information,  Prev: Password Database Functions,  Up: System Utilities

Group Database Functions
========================

   Octave's group database functions return information in a structure
with the following fields.

`name'
     The user name.

`passwd'
     The encrypted password, if available.

`gid'
     The numeric group id.

`mem'
     The members of the group.

 - Loadable Function: group_struct = getgrent ()
     Return an entry from the group database, opening it if necessary.
     Once the end of the data has been reached, `getgrent' returns 0.

 - Loadable Function: group_struct = getgrgid (GID).
     Return the first entry from the group database with the group ID
     GID.  If the group ID does not exist in the database, `getgrgid'
     returns 0.

 - Loadable Function: group_struct = getgrnam (NAME)
     Return the first entry from the group database with the group name
     NAME.  If the group name does not exist in the database,
     `getgrname' returns 0.

 - Loadable Function:  setgrent ()
     Return the internal pointer to the beginning of the group database.

 - Loadable Function:  endgrent ()
     Close the group database.


File: octave,  Node: System Information,  Next: Other Functions,  Prev: Group Database Functions,  Up: System Utilities

System Information
==================

 - Built-in Function:  computer ()
     Returns a string of the form CPU-VENDOR-OS that identifies the
     kind of computer Octave is running on.  For example,

          octave:13> computer
          sparc-sun-sunos4.1.2

 - Built-in Function:  isieee ()
     Return 1 if your computer claims to conform to the IEEE standard
     for floating point calculations.

 - Built-in Function:  version ()
     Returns Octave's version number as a string.  This is also the
     value of the built-in variable `OCTAVE_VERSION'.  *Note Built-in
     Variables::.

 - Loadable Function:  getrusage ()
     Return a structure containing a number of statistics about the
     current Octave process.  Not all fields are available on all
     systems.  If it is not possible to get CPU time statistics, the
     CPU time slots are set to zero.  Other missing data are replaced
     by NaN.  Here is a list of all the possible fields that can be
     present in the structure returned by `getrusage':

    `'
    `idrss'
          Unshared data size.

    `inblock'
          Number of block input operations.

    `isrss'
          Unshared stack size.

    `ixrss'
          Shared memory size.

    `majflt'
          Number of major page faults.

    `maxrss'
          Maximum data size.

    `minflt'
          Number of minor page faults.

    `msgrcv'
          Number of messages received.

    `msgsnd'
          Number of messages sent.

    `nivcsw'
          Number of involuntary context switches.

    `nsignals'
          Number of signals received.

    `nswap'
          Number of swaps.

    `nvcsw'
          Number of voluntary context switches.

    `oublock'
          Number of block output operations.

    `stime'
          A structure containing the system CPU time used.  The
          structure has the elements `sec' (seconds) `usec'
          (microseconds).

    `utime'
          A structure containing the user CPU time used.  The structure
          has the elements `sec' (seconds) `usec' (microseconds).


File: octave,  Node: Other Functions,  Prev: System Information,  Up: System Utilities

Other Functions
===============

 - Built-in Function:  tilde_expand (STRING)
     Performs tilde expansion on STRING.

 - Built-in Function:  pause (SECONDS)
     Suspend the execution of the program.  If invoked without any
     arguments, Octave waits until you type a character.  With a
     numeric argument, it pauses for the given number of seconds.  For
     example, the following statement prints a message and then waits 5
     seconds before clearing the screen.

          fprintf (stderr, "wait please...\n");
          pause (5);
          clc;


File: octave,  Node: Command History Functions,  Next: Help,  Prev: System Utilities,  Up: Top

Command History Functions
*************************

   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 named file.  If the name is
          omitted, use the default history file (normally
          `~/.octave_hist').

    `-r file'
          Read the named 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.

 - 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
     `"vi"'.

 - 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: 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 `"true"', command entered on
     the command line are saved in the file specified by the variable
     `history_file'.

 - Command: diary
     The `diary' command allows you to create a list of all commands
     *and* the output they produce, mixed together just as you see them
     on your terminal.

     For example, the command

          diary on

     tells Octave to start recording your session in a file called
     `diary' in your current working directory.  To give Octave the name
     of the file write to, use the a command like

          diary my-diary.txt

     Then Octave will write all of your commands to the file
     `my-diary.txt'.

     To stop recording your session, use the command

          diary off

     Without any arguments, `diary' toggles the current diary state.

 - 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


File: octave,  Node: Help,  Next: Programming Utilities,  Prev: Command History Functions,  Up: Top

Help
****

 - Command: help
     Octave's `help' command can be used to print brief usage-style
     messages, or to display information directly from an on-line
     version of the printed manual, using the GNU Info browser.  If
     invoked without any arguments, `help' prints a list of all the
     available operators, functions, and built-in variables.  If the
     first argument is `-i', the `help' command searches the index of
     the on-line version of this manual for the given topics.

     For example, the command

          help help

     prints a short message describing the `help' command, and

          help -i help

     starts the GNU Info browser at this node in the on-line version of
     the manual.

     *Note Using Info::, for complete details about how to use the GNU
     Info browser to read the on-line version of the manual.

 - Built-in Variable: INFO_FILE
     The variable `INFO_FILE' names the location of the Octave info
     file.  The default value is
     `"i:/apps/octave-1.90/info/octave.info"'.

 - Built-in Variable: INFO_PROGRAM
     The variable `INFO_PROGRAM' names the info program to run.  Its
     initial value is
     `i:/apps/octave-1.90/libexec/octave/VERSION/exec/ARCH/info', but
     that value can be overridden by the environment variable
     `OCTAVE_INFO_PROGRAM', or the command line argument
     `--info-program NAME', or by setting the value of `INFO_PROGRAM'
     in a startup script.

 - Built-in Variable: suppress_verbose_help_message
     If the value of `suppress_verbose_help_message' is nonzero, Octave
     will not add additional help information to the end of the output
     from the `help' command and usage messages for built-in commands.


File: octave,  Node: Programming Utilities,  Next: Amusements,  Prev: Help,  Up: Top

Programming Utilities
*********************

* Menu:

* Evaluating Strings as Commands::
* Miscellaneous Utilities::


File: octave,  Node: Evaluating Strings as Commands,  Next: Miscellaneous Utilities,  Prev: Programming Utilities,  Up: Programming Utilities

Evaluating Strings as Commands
==============================

   It is often useful to evaluate a string as if it were an Octave
program, or use a string as the name of a function to call.  These
functions are necessary in order to evaluate commands that are not
known until run time, or to write functions that will need to call
user-supplied functions.

 - Built-in Function:  eval (COMMAND)
     Parse the string COMMAND and evaluate it as if it were an Octave
     program, returning the last value computed.  The COMMAND is
     evaluated in the current context, so any results remain available
     after `eval' returns.  For example,

          octave:13> a
          error: `a' undefined
          octave:14> eval ("a = 13")
          a = 13
          ans = 13
          octave:15> a
          a = 13

     In this case, two values are printed:  one for the expression that
     was evaluated, and one for the value returned from `eval'.  Just as
     with any other expression, you can turn printing off by ending the
     expression in a semicolon.  For example,

          octave:13> a
          error: `a' undefined
          octave:14> eval ("a = 13;")
          ans = 13
          octave:15> a
          a = 13

 - Built-in Function:  feval (NAME, ...)
     Evaluate the function named NAME.  Any arguments after the first
     are passed on to the named function.  For example,

          octave:12> feval ("acos", -1)
          ans = 3.1416

     calls the function `acos' with the argument `-1'.

     The function `feval' is necessary in order to be able to write
     functions that call user-supplied functions, because Octave does
     not have a way to declare a pointer to a function (like C) or to
     declare a special kind of variable that can be used to hold the
     name of a function (like `EXTERNAL' in Fortran).  Instead, you
     must refer to functions by name, and use `feval' to call them.

   Here is a simple-minded function using `feval' that finds the root
of a user-supplied function of one variable.

     function result = newtroot (fname, x)
     
     # usage: newtroot (fname, x)
     #
     #   fname : a string naming a function f(x).
     #   x     : initial guess
     
       delta = tol = sqrt (eps);
       maxit = 200;
       fx = feval (fname, x);
       for i = 1:maxit
         if (abs (fx) < tol)
           result = x;
           return;
         else
           fx_new = feval (fname, x + delta);
           deriv = (fx_new - fx) / delta;
           x = x - fx / deriv;
           fx = fx_new;
         endif
       endfor
     
       result = x;
     
     endfunction

   Note that this is only meant to be an example of calling
user-supplied functions and should not be taken too seriously.  In
addition to using a more robust algorithm, any serious code would check
the number and type of all the arguments, ensure that the supplied
function really was a function, etc.


File: octave,  Node: Miscellaneous Utilities,  Prev: Evaluating Strings as Commands,  Up: Programming Utilities

Miscellaneous Utilities
=======================

   The following functions allow you to determine the size of a
variable or expression, find out whether a variable exists, print error
messages, or delete variable names from the symbol table.

 - 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,

          octave:13> size ([1, 2; 3, 4; 5, 6])
          ans =
          
            3  2
          
          octave:14> [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

          octave:15> size ([1, 2; 3, 4; 5, 6], 2)
          ans = 2

     returns the number of columns in the given matrix.

 - Built-in Function:  is_global (A)
     Return 1 if A is globally visible.  Otherwise, return 0.

 - 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.

 - Built-in Function:  isstr (A)
     Return 1 if A is a string.  Otherwise, return 0.

 - 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.

 - Command: clear PATTERN ...
     Delete the names matching the given patterns from the symbol
     table.  The pattern may contain the following special characters:
    `?'
          Match any single character.

    `*'
          Match zero or more characters.

    `[ LIST ]'
          Match the list of characters specified by LIST.  If the first
          character is `!' or `^', match all characters except those
          specified by LIST.  For example, the pattern `[a-zA-Z]' will
          match all lower and upper case alphabetic characters.

     For example, the command

          clear foo b*r

     clears the name `foo' and all names that begin with the letter `b'
     and end with the letter `r'.

     If `clear' is called without any arguments, all user-defined
     variables (local and global) are cleared from the symbol table.  If
     `clear' is called with at least one argument, only the visible
     names matching the arguments are cleared.  For example, suppose
     you have defined a function `foo', and then hidden it by
     performing the assignment `foo = 2'.  Executing the command `clear
     foo' once will clear the variable definition and restore the
     definition of `foo' as a function.  Executing `clear foo' a second
     time will clear the function definition.

     This command may not be used within a function body.

 - Command: who OPTIONS PATTERN ...
 - Command: whos OPTIONS PATTERN ...
     List currently defined symbols matching the given patterns.  The
     following are valid options.  They may be shortened to one
     character but may not be combined.

    `-all'
          List all currently defined symbols.

    `-builtins'
          List built-in variables and functions.  This includes all
          currently compiled function files, but does not include all
          function files that are in the `LOADPATH'.

    `-functions'
          List user-defined functions.

    `-long'
          Print a long listing including the type and dimensions of any
          symbols.  The symbols in the first column of output indicate
          whether it is possible to redefine the symbol, and whether it
          is possible for it to be cleared.

    `-variables'
          List user-defined variables.

     Valid patterns are the same as described for the `clear' command
     above.  If no patterns are supplied, all symbols from the given
     category are listed.  By default, only user defined functions and
     variables visible in the local scope are displayed.

     The command `whos' is equivalent to `who -long'.

 - Built-in Function:  exist (NAME)
     Return 1 if the name exists as a variable, and 2 if the name (after
     appending `.m') is a function file in the path.  Otherwise, return
     0.

 - Built-in Function:  error (MSG)
     Print the message MSG, prefixed by the string `error: ', and set
     Octave's internal error state such that control will return to the
     top level without evaluating any more commands.  This is useful for
     aborting from functions.

     If MSG does not end with a new line character, Octave will print a
     traceback of all the function calls leading to the error.  For
     example,

          function f () g () end
          function g () h () end
          function h () nargin == 1 || error ("nargin != 1"); end
          f ()
          error: nargin != 1
          error: evaluating index expression near line 1, column 30
          error: evaluating binary operator `||' near line 1, column 27
          error: called from `h'
          error: called from `g'
          error: called from `f'

     produces a list of messages that can help you to quickly locate the
     exact location of the error.

     If MSG ends in a new line character, Octave will only print MSG
     and will not display any traceback messages as it returns control
     to the top level.  For example, modifying the error message in the
     previous example to end in a new line causes Octave to only print
     a single message:

          function h () nargin == 1 || error ("nargin != 1\n"); end
          f ()
          error: nargin != 1

 - Built-in Variable: error_text

 - Built-in Variable: beep_on_error
     If the value of `beep_on_error' is nonzero, Octave will try to
     ring your terminal's bell before printing an error message.  The
     default value is 0.

 - Built-in Function:  warning (MSG)
     Print the message MSG prefixed by the string `warning: '.

 - Built-in Function:  usage (MSG)
     Print the message MSG, prefixed by the string `usage: ', and set
     Octave's internal error state such that control will return to the
     top level without evaluating any more commands.  This is useful for
     aborting from functions.

     After `usage' is evaluated, Octave will print a traceback of all
     the function calls leading to the usage message.

 - Function File:  perror (NAME, NUM)
     Print the error message for function NAME corresponding to the
     error number NUM.  This function is intended to be used to print
     useful error messages for those functions that return numeric error
     codes.

 - Function File:  menu (TITLE, OPT1, ...)
     Print a title string followed by a series of options.  Each option
     will be printed along with a number.  The return value is the
     number of the option selected by the user.  This function is
     useful for interactive programs.  There is no limit to the number
     of options that may be passed in, but it may be confusing to
     present more than will fit easily on one screen.

 - Built-in Function:  document (SYMBOL, TEXT)
     Set the documentation string for SYMBOL to TEXT.

 - Built-in Function:  file_in_path (PATH, FILE)
     Return the absolute name name of FILE if it can be found in PATH.
     The value of PATH should be a colon-separated list of directories
     in the format described for the built-in variable `LOADPATH'.

     If the file cannot be found in the path, an empty matrix is
     returned.  For example,

          octave:13> file_in_path (LOADPATH, "nargchk.m")
          ans = "i:/apps/octave-1.90/share/octave/2.0/m/general/nargchk.m"

 - 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.

 - Function File:  nargchk (NARGIN_MIN, NARGIN_MAX, N)
     If N is in the range NARGIN_MIN through NARGIN_MAX inclusive,
     return the empty matrix.  Otherwise, return a message indicating
     whether N is too large or too small.

     This is useful for checking to see that the number of arguments
     supplied to a function is within an acceptable range.

 - Built-in Function:  octave_tmp_file_name ()
     Return a unique temporary file name.

     Since the named file is not opened, by `octave_tmp_file_name', it
     is possible (though relatively unlikely) that it will not be
     available by the time your program attempts to open it.

 - Command: type NAME ...
 - Command: type [-Q] NAME ...
     Display the definition of each NAME that refers to a function.

     Normally also displays if each NAME is user-defined or builtin;
     the `-q' option suppresses this behaviour.

     Currently, Octave can only display functions that can be compiled
     cleanly, because it uses its internal representation of the
     function to recreate the program text.

     Comments are not displayed because Octave's parser currently
     discards them as it converts the text of a function file to its
     internal representation.  This problem may be fixed in a future
     release.

 - Command: which NAME ...
     Display the type of each NAME.  If NAME is defined from a function
     file, the full name of the file is also displayed.

 - Built-in Function: octave_config_info ()
     Return a structure containing configuration and installation
     information.


File: octave,  Node: Amusements,  Next: Emacs,  Prev: Programming Utilities,  Up: Top

Amusements
**********

 - Function File:  texas_lotto ()
     Octave cannot promise that you will actually win the lotto, but it
     can pick your numbers for you.  The function `texas_lotto' will
     select six numbers between 1 and 50.

 - Function File:  list_primes (N)
     Computes the first N primes using a brute-force algorithm.

   Other amusing functions include `casesen', `flops', `sombrero',
`exit', `quit', and `warranty'.


File: octave,  Node: Emacs,  Next: Installation,  Prev: Amusements,  Up: Top

Using Emacs With Octave
***********************

   The development of Octave code can greatly be facilitated using Emacs
with Octave mode, a major mode for editing Octave files which can e.g.
automatically indent the code, do some of the typing (with Abbrev mode)
and show keywords, comments, strings, etc. in different faces (with
Font-lock mode on devices that support it).

   It is also possible to run Octave from within Emacs, either by
directly entering commands at the prompt in a buffer in Inferior Octave
mode, or by interacting with Octave from within a file with Octave
code.  This is useful in particular for debugging Octave code.

   Finally, you can convince Octave to use the Emacs info reader for
`help -i'.

   All functionality is provided by the Emacs Lisp package `octave'.
This chapter describes how to set up and use this package.

   Please contact <Kurt.Hornik@ci.tuwien.ac.at> if you have any
questions or suggestions on using Emacs with Octave.

* Menu:

* Setting Up Octave Mode::
* Using Octave Mode::
* Running Octave From Within Emacs::
* Using the Emacs Info Reader for Octave::


File: octave,  Node: Setting Up Octave Mode,  Next: Using Octave Mode,  Prev: Emacs,  Up: Emacs

Setting Up Octave Mode
======================

   If you are lucky, your sysadmins have already arranged everything so
that Emacs automatically goes into Octave mode whenever you visit an
Octave code file as characterized by its extension `.m'.  If not,
proceed as follows.

  1. Make sure that the file `octave.el' (or even better, its
     byte-compiled version `octave.elc') from the Octave distribution is
     somewhere in your load-path.

          *Note:* The current version of `octave.el' was developed,
          tested and byte-compiled under GNU Emacs 19.31.  It may not
          work under other Emacs versions, in particular under XEmacs.

  2. To begin using Octave mode for all `.m' files you visit, add the
     following lines to a file loaded by Emacs at startup time,
     typically your `~/.emacs' file:

          (autoload 'octave-mode "octave" nil t)
          (setq auto-mode-alist
                (cons '(\"\\\\.m$\" . octave-mode) auto-mode-alist))

  3. Finally, to turn on the abbrevs, auto-fill and font-lock features
     automatically, also add the following lines to one of the Emacs
     startup files:
          (add-hook 'octave-mode-hook
                    (lambda ()
                      (abbrev-mode 1)
                      (auto-fill-mode 1)
                      (if (eq window-system 'x)
                          (font-lock-mode 1))))
     See the Emacs manual for more information about how to customize
     Font-lock mode.

