home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / octa21fb.zip / octave / doc / octave.i06 (.txt) < prev    next >
GNU Info File  |  2000-01-15  |  50KB  |  979 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: Integer Conversions,  Next: Floating-Point Conversions,  Prev: Table of Output Conversions,  Up: C-Style I/O Functions
  18. Integer Conversions
  19. -------------------
  20.    This section describes the options for the `%d', `%i', `%o', `%u',
  21. `%x', and `%X' conversion specifications.  These conversions print
  22. integers in various formats.
  23.    The `%d' and `%i' conversion specifications both print an numeric
  24. argument as a signed decimal number; while `%o', `%u', and `%x' print
  25. the argument as an unsigned octal, decimal, or hexadecimal number
  26. (respectively).  The `%X' conversion specification is just like `%x'
  27. except that it uses the characters `ABCDEF' as digits instead of
  28. `abcdef'.
  29.    The following flags are meaningful:
  30.      Left-justify the result in the field (instead of the normal
  31.      right-justification).
  32.      For the signed `%d' and `%i' conversions, print a plus sign if the
  33.      value is positive.
  34.      For the signed `%d' and `%i' conversions, if the result doesn't
  35.      start with a plus or minus sign, prefix it with a space character
  36.      instead.  Since the `+' flag ensures that the result includes a
  37.      sign, this flag is ignored if you supply both of them.
  38.      For the `%o' conversion, this forces the leading digit to be `0',
  39.      as if by increasing the precision.  For `%x' or `%X', this
  40.      prefixes a leading `0x' or `0X' (respectively) to the result.
  41.      This doesn't do anything useful for the `%d', `%i', or `%u'
  42.      conversions.
  43.      Pad the field with zeros instead of spaces.  The zeros are placed
  44.      after any indication of sign or base.  This flag is ignored if the
  45.      `-' flag is also specified, or if a precision is specified.
  46.    If a precision is supplied, it specifies the minimum number of
  47. digits to appear; leading zeros are produced if necessary.  If you
  48. don't specify a precision, the number is printed with as many digits as
  49. it needs.  If you convert a value of zero with an explicit precision of
  50. zero, then no characters at all are produced.
  51. File: octave,  Node: Floating-Point Conversions,  Next: Other Output Conversions,  Prev: Integer Conversions,  Up: C-Style I/O Functions
  52. Floating-Point Conversions
  53. --------------------------
  54.    This section discusses the conversion specifications for
  55. floating-point numbers: the `%f', `%e', `%E', `%g', and `%G'
  56. conversions.
  57.    The `%f' conversion prints its argument in fixed-point notation,
  58. producing output of the form [`-']DDD`.'DDD, where the number of digits
  59. following the decimal point is controlled by the precision you specify.
  60.    The `%e' conversion prints its argument in exponential notation,
  61. producing output of the form [`-']D`.'DDD`e'[`+'|`-']DD.  Again, the
  62. number of digits following the decimal point is controlled by the
  63. precision.  The exponent always contains at least two digits.  The `%E'
  64. conversion is similar but the exponent is marked with the letter `E'
  65. instead of `e'.
  66.    The `%g' and `%G' conversions print the argument in the style of
  67. `%e' or `%E' (respectively) if the exponent would be less than -4 or
  68. greater than or equal to the precision; otherwise they use the `%f'
  69. style.  Trailing zeros are removed from the fractional portion of the
  70. result and a decimal-point character appears only if it is followed by
  71. a digit.
  72.    The following flags can be used to modify the behavior:
  73.      Left-justify the result in the field.  Normally the result is
  74.      right-justified.
  75.      Always include a plus or minus sign in the result.
  76.      If the result doesn't start with a plus or minus sign, prefix it
  77.      with a space instead.  Since the `+' flag ensures that the result
  78.      includes a sign, this flag is ignored if you supply both of them.
  79.      Specifies that the result should always include a decimal point,
  80.      even if no digits follow it.  For the `%g' and `%G' conversions,
  81.      this also forces trailing zeros after the decimal point to be left
  82.      in place where they would otherwise be removed.
  83.      Pad the field with zeros instead of spaces; the zeros are placed
  84.      after any sign.  This flag is ignored if the `-' flag is also
  85.      specified.
  86.    The precision specifies how many digits follow the decimal-point
  87. character for the `%f', `%e', and `%E' conversions.  For these
  88. conversions, the default precision is `6'.  If the precision is
  89. explicitly `0', this suppresses the decimal point character entirely.
  90. For the `%g' and `%G' conversions, the precision specifies how many
  91. significant digits to print.  Significant digits are the first digit
  92. before the decimal point, and all the digits after it.  If the
  93. precision is `0' or not specified for `%g' or `%G', it is treated like
  94. a value of `1'.  If the value being printed cannot be expressed
  95. precisely in the specified number of digits, the value is rounded to
  96. the nearest number that fits.
  97. File: octave,  Node: Other Output Conversions,  Next: Formatted Input,  Prev: Floating-Point Conversions,  Up: C-Style I/O Functions
  98. Other Output Conversions
  99. ------------------------
  100.    This section describes miscellaneous conversions for `printf'.
  101.    The `%c' conversion prints a single character.  The `-' flag can be
  102. used to specify left-justification in the field, but no other flags are
  103. defined, and no precision or type modifier can be given.  For example:
  104.      printf ("%c%c%c%c%c", "h", "e", "l", "l", "o");
  105. prints `hello'.
  106.    The `%s' conversion prints a string.  The corresponding argument
  107. must be a string.  A precision can be specified to indicate the maximum
  108. number of characters to write; otherwise characters in the string up to
  109. but not including the terminating null character are written to the
  110. output stream.  The `-' flag can be used to specify left-justification
  111. in the field, but no other flags or type modifiers are defined for this
  112. conversion.  For example:
  113.      printf ("%3s%-6s", "no", "where");
  114. prints ` nowhere ' (note the leading and trailing spaces).
  115. File: octave,  Node: Formatted Input,  Next: Input Conversion Syntax,  Prev: Other Output Conversions,  Up: C-Style I/O Functions
  116. Formatted Input
  117. ---------------
  118.    Octave provides the `scanf', `fscanf', and `sscanf' functions to
  119. read formatted input.  There are two forms of each of these functions.
  120. One can be used to extract vectors of data from a file, and the other
  121. is more `C-like'.
  122.    DOSTRING(fscanf)
  123.  - Built-in Function: [VAL, COUNT] = sscanf (STRING, TEMPLATE, SIZE)
  124.  - Built-in Function: [V1, V2, ...] =  sscanf (STRING, TEMPLATE, "C")
  125.      This is like `fscanf', except that the characters are taken from
  126.      the string STRING instead of from a stream.  Reaching the end of
  127.      the string is treated as an end-of-file condition.
  128.    Calls to `scanf' are superficially similar to calls to `printf' in
  129. that arbitrary arguments are read under the control of a template
  130. string.  While the syntax of the conversion specifications in the
  131. template is very similar to that for `printf', the interpretation of
  132. the template is oriented more towards free-format input and simple
  133. pattern matching, rather than fixed-field formatting.  For example,
  134. most `scanf' conversions skip over any amount of "white space"
  135. (including spaces, tabs, and newlines) in the input file, and there is
  136. no concept of precision for the numeric input conversions as there is
  137. for the corresponding output conversions.  Ordinarily, non-whitespace
  138. characters in the template are expected to match characters in the
  139. input stream exactly.
  140.    When a "matching failure" occurs, `scanf' returns immediately,
  141. leaving the first non-matching character as the next character to be
  142. read from the stream, and `scanf' returns all the items that were
  143. successfully converted.
  144.    The formatted input functions are not used as frequently as the
  145. formatted output functions.  Partly, this is because it takes some care
  146. to use them properly.  Another reason is that it is difficult to recover
  147. from a matching error.
  148. File: octave,  Node: Input Conversion Syntax,  Next: Table of Input Conversions,  Prev: Formatted Input,  Up: C-Style I/O Functions
  149. Input Conversion Syntax
  150. -----------------------
  151.    A `scanf' template string is a string that contains ordinary
  152. multibyte characters interspersed with conversion specifications that
  153. start with `%'.
  154.    Any whitespace character in the template causes any number of
  155. whitespace characters in the input stream to be read and discarded.
  156. The whitespace characters that are matched need not be exactly the same
  157. whitespace characters that appear in the template string.  For example,
  158. write ` , ' in the template to recognize a comma with optional
  159. whitespace before and after.
  160.    Other characters in the template string that are not part of
  161. conversion specifications must match characters in the input stream
  162. exactly; if this is not the case, a matching failure occurs.
  163.    The conversion specifications in a `scanf' template string have the
  164. general form:
  165.      % FLAGS WIDTH TYPE CONVERSION
  166.    In more detail, an input conversion specification consists of an
  167. initial `%' character followed in sequence by:
  168.    * An optional "flag character" `*', which says to ignore the text
  169.      read for this specification.  When `scanf' finds a conversion
  170.      specification that uses this flag, it reads input as directed by
  171.      the rest of the conversion specification, but it discards this
  172.      input, does not return any value, and does not increment the count
  173.      of successful assignments.
  174.    * An optional decimal integer that specifies the "maximum field
  175.      width".  Reading of characters from the input stream stops either
  176.      when this maximum is reached or when a non-matching character is
  177.      found, whichever happens first.  Most conversions discard initial
  178.      whitespace characters, and these discarded characters don't count
  179.      towards the maximum field width.  Conversions that do not discard
  180.      initial whitespace are explicitly documented.
  181.    * An optional type modifier character.  This character is ignored by
  182.      Octave's `scanf' function, but is recognized to provide
  183.      compatibility with the C language `scanf'.
  184.    * A character that specifies the conversion to be applied.
  185.    The exact options that are permitted and how they are interpreted
  186. vary between the different conversion specifiers.  See the descriptions
  187. of the individual conversions for information about the particular
  188. options that they allow.
  189. File: octave,  Node: Table of Input Conversions,  Next: Numeric Input Conversions,  Prev: Input Conversion Syntax,  Up: C-Style I/O Functions
  190. Table of Input Conversions
  191. --------------------------
  192.    Here is a table that summarizes the various conversion
  193. specifications:
  194.      Matches an optionally signed integer written in decimal.  *Note
  195.      Numeric Input Conversions::.
  196.      Matches an optionally signed integer in any of the formats that
  197.      the C language defines for specifying an integer constant.  *Note
  198.      Numeric Input Conversions::.
  199.      Matches an unsigned integer written in octal radix.  *Note Numeric
  200.      Input Conversions::.
  201.      Matches an unsigned integer written in decimal radix.  *Note
  202.      Numeric Input Conversions::.
  203. `%x', `%X'
  204.      Matches an unsigned integer written in hexadecimal radix.  *Note
  205.      Numeric Input Conversions::.
  206. `%e', `%f', `%g', `%E', `%G'
  207.      Matches an optionally signed floating-point number.  *Note Numeric
  208.      Input Conversions::.
  209.      Matches a string containing only non-whitespace characters.  *Note
  210.      String Input Conversions::.
  211.      Matches a string of one or more characters; the number of
  212.      characters read is controlled by the maximum field width given for
  213.      the conversion.  *Note String Input Conversions::.
  214.      This matches a literal `%' character in the input stream.  No
  215.      corresponding argument is used.
  216.    If the syntax of a conversion specification is invalid, the behavior
  217. is undefined.  If there aren't enough function arguments provided to
  218. supply addresses for all the conversion specifications in the template
  219. strings that perform assignments, or if the arguments are not of the
  220. correct types, the behavior is also undefined.  On the other hand, extra
  221. arguments are simply ignored.
  222. File: octave,  Node: Numeric Input Conversions,  Next: String Input Conversions,  Prev: Table of Input Conversions,  Up: C-Style I/O Functions
  223. Numeric Input Conversions
  224. -------------------------
  225.    This section describes the `scanf' conversions for reading numeric
  226. values.
  227.    The `%d' conversion matches an optionally signed integer in decimal
  228. radix.
  229.    The `%i' conversion matches an optionally signed integer in any of
  230. the formats that the C language defines for specifying an integer
  231. constant.
  232.    For example, any of the strings `10', `0xa', or `012' could be read
  233. in as integers under the `%i' conversion.  Each of these specifies a
  234. number with decimal value `10'.
  235.    The `%o', `%u', and `%x' conversions match unsigned integers in
  236. octal, decimal, and hexadecimal radices, respectively.
  237.    The `%X' conversion is identical to the `%x' conversion.  They both
  238. permit either uppercase or lowercase letters to be used as digits.
  239.    Unlike the C language `scanf', Octave ignores the `h', `l', and `L'
  240. modifiers.
  241. File: octave,  Node: String Input Conversions,  Next: Binary I/O,  Prev: Numeric Input Conversions,  Up: C-Style I/O Functions
  242. String Input Conversions
  243. ------------------------
  244.    This section describes the `scanf' input conversions for reading
  245. string and character values: `%s' and `%c'.
  246.    The `%c' conversion is the simplest: it matches a fixed number of
  247. characters, always.  The maximum field with says how many characters to
  248. read; if you don't specify the maximum, the default is 1.  This
  249. conversion does not skip over initial whitespace characters.  It reads
  250. precisely the next N characters, and fails if it cannot get that many.
  251.    The `%s' conversion matches a string of non-whitespace characters.
  252. It skips and discards initial whitespace, but stops when it encounters
  253. more whitespace after having read something.
  254.    For example, reading the input:
  255.       hello, world
  256. with the conversion `%10c' produces `" hello, wo"', but reading the
  257. same input with the conversion `%10s' produces `"hello,"'.
  258. File: octave,  Node: Binary I/O,  Next: Temporary Files,  Prev: String Input Conversions,  Up: C-Style I/O Functions
  259. Binary I/O
  260. ----------
  261.    Octave can read and write binary data using the functions `fread'
  262. and `fwrite', which are patterned after the standard C functions with
  263. the same names.  The are able to automatically swap the byte order of
  264. integer data and convert among ths supported floating point formats as
  265. the data are read.
  266.  - Built-in Function: [VAL, COUNT] = fread (FID, SIZE, PRECISION, SKIP,
  267.           ARCH)
  268.      Read binary data of type PRECISION from the specified file ID FID.
  269.      The optional argument SIZE specifies the amount of data to read
  270.      and may be one of
  271.     `Inf'
  272.           Read as much as possible, returning a column vector.
  273.     `NR'
  274.           Read up to NR elements, returning a column vector.
  275.     `[NR, Inf]'
  276.           Read as much as possible, returning a matrix with NR rows.
  277.           If the number of elements read is not an exact multiple of
  278.           NR, the last column is padded with zeros.
  279.     `[NR, NC]'
  280.           Read up to `NR * NC' elements, returning a matrix with NR
  281.           rows.  If the number of elements read is not an exact multiple
  282.           of NR, the last column is padded with zeros.
  283.      If SIZE is omitted, a value of `Inf' is assumed.
  284.      The optional argument PRECISION is a string specifying the type of
  285.      data to read and may be one of
  286.     `"char"'
  287.     `"char*1"'
  288.     `"integer*1"'
  289.     `"int8"'
  290.           Single character.
  291.     `"signed char"'
  292.     `"schar"'
  293.           Signed character.
  294.     `"unsigned char"'
  295.     `"uchar"'
  296.           Unsigned character.
  297.     `"short"'
  298.           Short integer.
  299.     `"unsigned short"'
  300.     `"ushort"'
  301.           Unsigned short integer.
  302.     `"int"'
  303.           Integer.
  304.     `"unsigned int"'
  305.     `"uint"'
  306.           Unsigned integer.
  307.     `"long"'
  308.           Long integer.
  309.     `"unsigned long"'
  310.     `"ulong"'
  311.           Unsigned long integer.
  312.     `"float"'
  313.     `"float32"'
  314.     `"real*4"'
  315.           Single precision float.
  316.     `"double"'
  317.     `"float64"'
  318.     `"real*8"'
  319.           Double precision float.
  320.     `"integer*2"'
  321.     `"int16"'
  322.           Two byte integer.
  323.     `"integer*4"'
  324.     `"int32"'
  325.           Four byte integer.
  326.      The default precision is `"uchar"'.
  327.      The optional argument SKIP specifies the number of bytes to skip
  328.      before each element is read.  If it is not specified, a value of 0
  329.      is assumed.
  330.      The optional argument ARCH is a string specifying the data format
  331.      for the file.  Valid values are
  332.     `"native"'
  333.           The format of the current machine.
  334.     `"ieee-le"'
  335.           IEEE big endian.
  336.     `"ieee-be"'
  337.           IEEE little endian.
  338.     `"vaxd"'
  339.           VAX D floating format.
  340.     `"vaxg"'
  341.           VAX G floating format.
  342.     `"cray"'
  343.           Cray floating format.
  344.      Conversions are currently only supported for `"ieee-be"' and
  345.      `"ieee-le"' formats.
  346.      The data read from the file is returned in VAL, and the number of
  347.      values read is returned in `count'
  348.  - Built-in Function: COUNT = fwrite (FID, DATA, PRECISION, SKIP, ARCH)
  349.      Write data in binary form of type PRECISION to the specified file
  350.      ID FID, returning the number of values successfully written to the
  351.      file.
  352.      The argument DATA is a matrix of values that are to be written to
  353.      the file.  The values are extracted in column-major order.
  354.      The remaining arguments PRECISION, SKIP, and ARCH are optional,
  355.      and are interpreted as described for `fread'.
  356.      The behavior of `fwrite' is undefined if the values in DATA are
  357.      too large to fit in the specified precision.
  358. File: octave,  Node: Temporary Files,  Next: EOF and Errors,  Prev: Binary I/O,  Up: C-Style I/O Functions
  359. Temporary Files
  360. ---------------
  361.  - Built-in Function:  tmpnam ()
  362.      Return a unique temporary file name as a string.
  363.      Since the named file is not opened, by `tmpnam', it is possible
  364.      (though relatively unlikely) that it will not be available by the
  365.      time your program attempts to open it.
  366. File: octave,  Node: EOF and Errors,  Next: File Positioning,  Prev: Temporary Files,  Up: C-Style I/O Functions
  367. End of File and Errors
  368. ----------------------
  369.  - Built-in Function:  feof (FID)
  370.      Return 1 if an end-of-file condition has been encountered for a
  371.      given file and 0 otherwise.  Note that it will only return 1 if
  372.      the end of the file has already been encountered, not if the next
  373.      read operation will result in an end-of-file condition.
  374.  - Built-in Function:  ferror (FID)
  375.      Return 1 if an error condition has been encountered for a given
  376.      file and 0 otherwise.  Note that it will only return 1 if an error
  377.      has already been encountered, not if the next operation will
  378.      result in an error condition.
  379.  - Built-in Function:  freport ()
  380.      Print a list of which files have been opened, and whether they are
  381.      open for reading, writing, or both.  For example,
  382.           freport ()
  383.           
  384.                -|  number  mode  name
  385.                -|
  386.                -|       0     r  stdin
  387.                -|       1     w  stdout
  388.                -|       2     w  stderr
  389.                -|       3     r  myfile
  390. File: octave,  Node: File Positioning,  Prev: EOF and Errors,  Up: C-Style I/O Functions
  391. File Positioning
  392. ----------------
  393.    Three functions are available for setting and determining the
  394. position of the file pointer for a given file.
  395.  - Built-in Function:  ftell (FID)
  396.      Return the position of the file pointer as the number of characters
  397.      from the beginning of the file FID.
  398.  - Built-in Function:  fseek (FID, OFFSET, ORIGIN)
  399.      Set the file pointer to any location within the file FID.  The
  400.      pointer is positioned OFFSET characters from the ORIGIN, which may
  401.      be one of the predefined variables `SEEK_CUR' (current position),
  402.      `SEEK_SET' (beginning), or `SEEK_END' (end of file). If ORIGIN is
  403.      omitted, `SEEK_SET' is assumed.  The offset must be zero, or a
  404.      value returned by `ftell' (in which case ORIGIN must be `SEEK_SET'.
  405.  - Built-in Variable: SEEK_SET
  406.  - Built-in Variable: SEEK_CUR
  407.  - Built-in Variable: SEEK_END
  408.      These variables may be used as the optional third argument for the
  409.      function `fseek'.
  410.     `SEEK_SET'
  411.           Position file relative to the beginning.
  412.     `SEEK_CUR'
  413.           Position file relative to the current position.
  414.     `SEEK_END'
  415.           used with fseek to position file relative to the end.
  416.  - Built-in Function:  frewind (FID)
  417.      Move the file pointer to the beginning of the file FID, returning
  418.      1 for success, and 0 if an error was encountered.  It is
  419.      equivalent to `fseek (FID, 0, SEEK_SET)'.
  420.    The following example stores the current file position in the
  421. variable `marker', moves the pointer to the beginning of the file, reads
  422. four characters, and then returns to the original position.
  423.      marker = ftell (myfile);
  424.      frewind (myfile);
  425.      fourch = fgets (myfile, 4);
  426.      fseek (myfile, marker, SEEK_SET);
  427.    % DO NOT EDIT!  Generated automatically by munge-texi.
  428. File: octave,  Node: Plotting,  Next: Matrix Manipulation,  Prev: Input and Output,  Up: Top
  429. Plotting
  430. ********
  431.    All of Octave's plotting functions use `gnuplot' to handle the
  432. actual graphics.  There are two low-level functions, `gplot' and
  433. `gsplot', that behave almost exactly like the corresponding `gnuplot'
  434. functions `plot' and `splot'.  A number of other higher level plotting
  435. functions, patterned after the graphics functions found in MATLAB
  436. version 3.5, are also available.  These higher level functions are all
  437. implemented in terms of the two low-level plotting functions.
  438. * Menu:
  439. * Two-Dimensional Plotting::
  440. * Specialized Two-Dimensional Plots::
  441. * Three-Dimensional Plotting::
  442. * Plot Annotations::
  443. * Multiple Plots on One Page::
  444. File: octave,  Node: Two-Dimensional Plotting,  Next: Specialized Two-Dimensional Plots,  Prev: Plotting,  Up: Plotting
  445. Two-Dimensional Plotting
  446. ========================
  447.  - Command: gplot RANGES EXPRESSION USING TITLE STYLE
  448.      Generate a 2-dimensional plot.
  449.      The RANGES, USING, TITLE, and STYLE arguments are optional, and
  450.      the USING, TITLE and STYLE qualifiers may appear in any order
  451.      after the expression.  You may plot multiple expressions with a
  452.      single command by separating them with commas.  Each expression
  453.      may have its own set of qualifiers.
  454.      The optional item RANGES has the syntax
  455.           [ x_lo : x_up ] [ y_lo : y_up ]
  456.      and may be used to specify the ranges for the axes of the plot,
  457.      independent of the actual range of the data.  The range for the y
  458.      axes and any of the individual limits may be omitted.  A range
  459.      `[:]' indicates that the default limits should be used.  This
  460.      normally means that a range just large enough to include all the
  461.      data points will be used.
  462.      The expression to be plotted must not contain any literal matrices
  463.      (e.g. `[ 1, 2; 3, 4 ]') since it is nearly impossible to
  464.      distinguish a plot range from a matrix of data.
  465.      See the help for `gnuplot' for a description of the syntax for the
  466.      optional items.
  467.      By default, the `gplot' command plots the second column of a matrix
  468.      versus the first.  If the matrix only has one column, it is taken
  469.      as a vector of y-coordinates and the x-coordinate is taken as the
  470.      element index, starting with zero.  For example,
  471.           gplot rand (100,1) with linespoints
  472.      will plot 100 random values and connect them with lines.  When
  473.      `gplot' is used to plot a column vector, the indices of the
  474.      elements are taken as x values.
  475.      If there are more than two columns, you can choose which columns
  476.      to plot with the USING qualifier. For example, given the data
  477.           x = (-10:0.1:10)';
  478.           data = [x, sin(x), cos(x)];
  479.      the command
  480.           gplot [-11:11] [-1.1:1.1] \
  481.             data with lines, data using 1:3 with impulses
  482.      will plot two lines.  The first line is generated by the command
  483.      `data with lines', and is a graph of the sine function over the
  484.      range -10 to 10.  The data is taken from the first two columns of
  485.      the matrix because columns to plot were not specified with the
  486.      USING qualifier.
  487.      The clause `using 1:3' in the second part of this plot command
  488.      specifies that the first and third columns of the matrix `data'
  489.      should be taken as the values to plot.
  490.      In this example, the ranges have been explicitly specified to be a
  491.      bit larger than the actual range of the data so that the curves do
  492.      not touch the border of the plot.
  493.  - Command: gset OPTIONS
  494.  - Command: gshow OPTIONS
  495.  - Command: replot OPTIONS
  496.      In addition to the basic plotting commands, the whole range of
  497.      `gset' and `gshow' commands from `gnuplot' are available, as is
  498.      `replot'.
  499.      Note that in Octave 2.0, the `set' and `show' commands were
  500.      renamed to `gset' and `gshow' in order to allow for compatibility
  501.      with the MATLAB graphics and GUI commands in a future version of
  502.      Octave.  (For now, the old `set' and `show' commands do work, but
  503.      they print an annoying warning message to try to get people to
  504.      switch to using `gset' and `gshow'.)
  505.      The `gset' and `gshow' commands allow you to set and show
  506.      `gnuplot' parameters.  For more information about the `gset' and
  507.      `gshow' commands, see the documentation for `set' and `show' in
  508.      the `gnuplot' user's guide (also available on line if you run
  509.      `gnuplot' directly, instead of running it from Octave).
  510.      The `replot' command allows you to force the plot to be
  511.      redisplayed.  This is useful if you have changed something about
  512.      the plot, such as the title or axis labels.  The `replot' command
  513.      also accepts the same arguments as `gplot' or `gsplot' (except for
  514.      data ranges) so you can add additional lines to existing plots.
  515.      For example,
  516.           gset term tek40
  517.           gset output "/dev/plotter"
  518.           gset title "sine with lines and cosine with impulses"
  519.           replot "sin (x) w l"
  520.      will change the terminal type for plotting, add a title to the
  521.      current plot, add a graph of sin (x) to the plot, and force the
  522.      new plot to be sent to the plot device.  This last step is
  523.      normally required in order to update the plot.  This default is
  524.      reasonable for slow terminals or hardcopy output devices because
  525.      even when you are adding additional lines with a replot command,
  526.      gnuplot always redraws the entire plot, and you probably don't
  527.      want to have a completely new plot generated every time something
  528.      as minor as an axis label changes.
  529.      The command `shg' is equivalent to executing `replot' without any
  530.      arguments.
  531.  - Built-in Variable: automatic_replot
  532.      You can tell Octave to redisplay the plot each time anything about
  533.      it changes by setting the value of the builtin variable
  534.      `automatic_replot' to a nonzero value.  Since this is fairly
  535.      inefficient, the default value is 0.
  536.    Note that NaN values in the plot data are automatically omitted, and
  537. Inf values are converted to a very large value before calling gnuplot.
  538.    The MATLAB-style two-dimensional plotting commands are:
  539.  - Function File:  plot (ARGS)
  540.      This function produces two-dimensional plots.  Many different
  541.      combinations of arguments are possible.  The simplest form is
  542.            plot (Y)
  543.      where the argument is taken as the set of Y coordinates and the X
  544.      coordinates are taken to be the indices of the elements,  starting
  545.      with 1.
  546.      If more than one argument is given, they are interpreted as
  547.            plot (X, Y, FMT ...)
  548.      where Y and FMT are optional, and any number of argument  sets may
  549.      appear.  The X and Y values are  interpreted as follows:
  550.         *  If a single data argument is supplied, it is taken as the
  551.           set of Y  coordinates and the X coordinates are taken to be
  552.           the indices of  the elements, starting with 1.
  553.         *  If the first argument is a vector and the second is a
  554.           matrix, the  the vector is plotted versus the columns (or
  555.           rows) of the matrix.   (using whichever combination matches,
  556.           with columns tried first.)
  557.         *  If the first argument is a matrix and the second is a
  558.           vector, the  the columns (or rows) of the matrix are plotted
  559.           versus the vector.   (using whichever combination matches,
  560.           with columns tried first.)
  561.         *  If both arguments are vectors, the elements of Y are plotted
  562.           versus  the elements of X.
  563.         *  If both arguments are matrices, the columns of Y are plotted
  564.           versus the columns of X.  In this case, both matrices must
  565.           have  the same number of rows and columns and no attempt is
  566.           made to transpose  the arguments to make the number of rows
  567.           match.
  568.           If both arguments are scalars, a single point is plotted.
  569.      If the FMT argument is supplied, it is interpreted as  follows.
  570.      If FMT is missing, the default gnuplot line style  is assumed.
  571.     `-'
  572.           Set lines plot style (default).
  573.     `.'
  574.           Set dots plot style.
  575.     `@'
  576.           Set points plot style.
  577.     `-@'
  578.           Set linespoints plot style.
  579.     `^'
  580.           Set impulses plot style.
  581.     `L'
  582.           Set steps plot style.
  583.     `#'
  584.           Set boxes plot style.
  585.     `~'
  586.           Set errorbars plot style.
  587.     `#~'
  588.           Set boxerrorbars plot style.
  589.     `N'
  590.           Interpreted as the plot color if N is an integer in the range
  591.           1 to  6.
  592.     `NM'
  593.           If NM is a two digit integer and M is an integer in the
  594.           range 1 to 6, M is interpreted as the point style.  This is
  595.           only  valid in combination with the `@' or `-@' specifiers.
  596.     `C'
  597.           If C is one of `"r"', `"g"', `"b"', `"m"', `"c"', or `"w"',
  598.           it is interpreted as the plot color (red,  green, blue,
  599.           magenta, cyan, or white).
  600.     `+'
  601.     `*'
  602.     `o'
  603.     `x'
  604.           Used in combination with the points or linespoints styles,
  605.           set the point  style.
  606.      The color line styles have the following meanings on terminals that
  607.      support color.
  608.            Number  Gnuplot colors  (lines)points style
  609.              1       red                   *
  610.              2       green                 +
  611.              3       blue                  o
  612.              4       magenta               x
  613.              5       cyan                house
  614.              6       brown            there exists
  615.      Here are some plot examples:
  616.            plot (x, y, "@12", x, y2, x, y3, "4", x, y4, "+")
  617.      This command will plot `y' with points of type 2 (displayed as
  618.      `+') and color 1 (red), `y2' with lines, `y3' with lines of  color
  619.      4 (magenta) and `y4' with points displayed as `+'.
  620.            plot (b, "*")
  621.      This command will plot the data in the variable `b' will be plotted
  622.      with points displayed as `*'.
  623.  - Built-in Function:  hold ARGS
  624.      Tell Octave to `hold' the current data on the plot when executing
  625.      subsequent plotting commands.  This allows you to execute a series
  626.      of plot commands and have all the lines end up on the same figure.
  627.      The default is for each new plot command to clear the plot device
  628.      first.  For example, the command
  629.           hold on
  630.      turns the hold state on.  An argument of `off' turns the hold state
  631.      off, and `hold' with no arguments toggles the current hold state.
  632.  - Built-in Function:  ishold
  633.      Return 1 if the next line will be added to the current plot, or 0
  634.      if the plot device will be cleared before drawing the next line.
  635.  - Built-in Function:  clearplot
  636.  - Built-in Function:  clg
  637.      Clear the plot window and any titles or axis labels.  The name
  638.      `clg' is aliased to `clearplot' for compatibility with MATLAB.
  639.      The commands `gplot clear', `gsplot clear', and `replot clear' are
  640.      equivalent to `clearplot'.  (Previously, commands like `gplot
  641.      clear' would evaluate `clear' as an ordinary expression and clear
  642.      all the visible variables.)
  643.  - Built-in Function:  closeplot
  644.      Close stream to the `gnuplot' subprocess.  If you are using X11,
  645.      this will close the plot window.
  646.  - Built-in Function:  purge_tmp_files
  647.      Delete the temporary files created by the plotting commands.
  648.      Octave creates temporary data files for `gnuplot' and then sends
  649.      commands to `gnuplot' through a pipe.  Octave will delete the
  650.      temporary files on exit, but if you are doing a lot of plotting
  651.      you may want to clean up in the middle of a session.
  652.      A future version of Octave will eliminate the need to use temporary
  653.      files to hold the plot data.
  654.  - Function File:  axis (LIMITS)
  655.      Sets the axis limits for plots.
  656.      The argument LIMITS should be a 2, 4, or 6 element vector.  The
  657.      first and second elements specify the lower and upper limits for
  658.      the x  axis.  The third and fourth specify the limits for the y
  659.      axis, and the  fifth and sixth specify the limits for the z axis.
  660.      With no arguments, `axis' turns autoscaling on.
  661.      If your plot is already drawn, then you need to use `replot' before
  662.      the new axis limits will take effect.  You can get this to happen
  663.      automatically by setting the built-in variable `automatic_replot'
  664.      to a nonzero value.
  665. File: octave,  Node: Specialized Two-Dimensional Plots,  Next: Three-Dimensional Plotting,  Prev: Two-Dimensional Plotting,  Up: Plotting
  666. Specialized Two-Dimensional Plots
  667. =================================
  668.  - Function File:  bar (X, Y)
  669.      Given two vectors of x-y data, `bar' produces a bar graph.
  670.      If only one argument is given, it is taken as a vector of y-values
  671.      and the x coordinates are taken to be the indices of the elements.
  672.      If two output arguments are specified, the data are generated but
  673.      not plotted.  For example,
  674.            bar (x, y);
  675.      and
  676.            [xb, yb] = bar (x, y);
  677.            plot (xb, yb);
  678.      are equivalent.
  679.  - Function File:  contour (Z, N, X, Y)
  680.      Make a contour plot of the three-dimensional surface described by
  681.      Z.  Someone needs to improve `gnuplot''s contour routines  before
  682.      this will be very useful.
  683.  - Function File:  hist (Y, X)
  684.      Produce histogram counts or plots.
  685.      With one vector input argument, plot a histogram of the values with
  686.      10 bins.  The range of the histogram bins is determined by the
  687.      range  of the data.
  688.      Given a second scalar argument, use that as the number of bins.
  689.      Given a second vector argument, use that as the centers of the
  690.      bins,  with the width of the bins determined from the adjacent
  691.      values in  the vector.
  692.      Extreme values are lumped in the first and last bins.
  693.      With two output arguments, produce the values NN and XX such  that
  694.      `bar (XX, NN)' will plot the histogram.
  695.  - Function File:  loglog (ARGS)
  696.      Make a two-dimensional plot using log scales for both axes.  See
  697.      the  description of `plot' for a description of the arguments that
  698.      `loglog' will accept.
  699.  - Function File:  polar (THETA, RHO, FMT)
  700.      Make a two-dimensional plot given polar the coordinates THETA and
  701.      RHO.
  702.      The optional third argument specifies the line type.
  703.  - Function File:  semilogx (ARGS)
  704.      Make a two-dimensional plot using a log scale for the X axis.  See
  705.      the description of `plot' for a description of the arguments
  706.      that `semilogx' will accept.
  707.  - Function File:  semilogy (ARGS)
  708.      Make a two-dimensional plot using a log scale for the Y axis.  See
  709.      the description of `plot' for a description of the arguments
  710.      that `semilogy' will accept.
  711.  - Function File:  stairs (X, Y)
  712.      Given two vectors of x-y data, bar produces a `stairstep' plot.
  713.      If only one argument is given, it is taken as a vector of y-values
  714.      and the x coordinates are taken to be the indices of the elements.
  715.      If two output arguments are specified, the data are generated but
  716.      not plotted.  For example,
  717.            stairs (x, y);
  718.      and
  719.            [xs, ys] = stairs (x, y);
  720.            plot (xs, ys);
  721.      are equivalent.
  722. File: octave,  Node: Three-Dimensional Plotting,  Next: Plot Annotations,  Prev: Specialized Two-Dimensional Plots,  Up: Plotting
  723. Three-Dimensional Plotting
  724. ==========================
  725.  - Command: gsplot RANGES EXPRESSION USING TITLE STYLE
  726.      Generate a 3-dimensional plot.
  727.      The RANGES, USING, TITLE, and STYLE arguments are optional, and
  728.      the USING, TITLE and STYLE qualifiers may appear in any order
  729.      after the expression.  You may plot multiple expressions with a
  730.      single command by separating them with commas.  Each expression
  731.      may have its own set of qualifiers.
  732.      The optional item RANGES has the syntax
  733.           [ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ]
  734.      and may be used to specify the ranges for the axes of the plot,
  735.      independent of the actual range of the data.  The range for the y
  736.      and z axes and any of the individual limits may be omitted.  A
  737.      range `[:]' indicates that the default limits should be used.  This
  738.      normally means that a range just large enough to include all the
  739.      data points will be used.
  740.      The expression to be plotted must not contain any literal matrices
  741.      (e.g.  `[ 1, 2; 3, 4 ]') since it is nearly impossible to
  742.      distinguish a plot range from a matrix of data.
  743.      See the help for `gnuplot' for a description of the syntax for the
  744.      optional items.
  745.      By default, the `gsplot' command plots each column of the
  746.      expression as the z value, using the row index as the x value, and
  747.      the column index as the y value.  The indices are counted from
  748.      zero, not one.  For example,
  749.           gsplot rand (5, 2)
  750.      will plot a random surface, with the x and y values taken from the
  751.      row and column indices of the matrix.
  752.      If parametric plotting mode is set (using the command `gset
  753.      parametric', then `gsplot' takes the columns of the matrix three
  754.      at a time as the x, y and z values that define a line in three
  755.      space.  Any extra columns are ignored, and the x and y values are
  756.      expected to be sorted.  For example, with `parametric' set, it
  757.      makes sense to plot a matrix like
  758.           1 1 3 2 1 6 3 1 9
  759.           1 2 2 2 2 5 3 2 8
  760.           1 3 1 2 3 4 3 3 7
  761.      but not `rand (5, 30)'.
  762.    The MATLAB-style three-dimensional plotting commands are:
  763.  - Function File:  mesh (X, Y, Z)
  764.      Plot a mesh given matrices `x', and Y from `meshdom' and  a matrix
  765.      Z corresponding to the X and Y coordinates of  the mesh.  If X and
  766.      Y are vectors, then a typical vertex  is (X(j), Y(i), Z(i,j)).
  767.      Thus, columns of Z  correspond to different X values and rows of Z
  768.      correspond  to different Y values.
  769.  - Function File:  meshdom (X, Y)
  770.      Given vectors of X and Y coordinates, return two matrices
  771.      corresponding to the X and Y coordinates of the mesh.
  772.      See the file `sombrero.m' for an example of using `mesh' and
  773.      `meshdom'.
  774.      Note: this function is provided for compatibility with older
  775.      versions  of MATLAB.  You should use `meshgrid' instead.
  776.  - Built-in Variable: gnuplot_binary
  777.      The name of the program invoked by the plot command.  The default
  778.      value is `"gnuplot"'.  *Note Installation::.
  779.  - Built-in Variable: gnuplot_has_frames
  780.      If the value of this variable is nonzero, Octave assumes that your
  781.      copy of gnuplot has support for multiple frames that is included
  782.      in recent 3.6beta releases.  It's initial value is determined by
  783.      configure, but it can be changed in your startup script or at the
  784.      command line in case configure got it wrong, or if you upgrade
  785.      your gnuplot installation.
  786.  - Function File:  figure (N)
  787.      Set the current plot window to plot window N.  This function
  788.      currently requires X11 and a version of gnuplot that supports
  789.      multiple  frames.
  790.  - Built-in Variable: gnuplot_has_multiplot
  791.      If the value of this variable is nonzero, Octave assumes that your
  792.      copy of gnuplot has the multiplot support that is included in
  793.      recent 3.6beta releases.  It's initial value is determined by
  794.      configure, but it can be changed in your startup script or at the
  795.      command line in case configure got it wrong, or if you upgrade
  796.      your gnuplot installation.
  797. File: octave,  Node: Plot Annotations,  Next: Multiple Plots on One Page,  Prev: Three-Dimensional Plotting,  Up: Plotting
  798. Plot Annotations
  799. ================
  800.  - Function File:  grid (ARG)
  801.      For two-dimensional plotting, force the display of a grid on the
  802.      plot.   The argument may be either `"on"' or `"off"'.  If it is
  803.      omitted, `"on"' is assumed.
  804.  - Function File:  title (STRING)
  805.      Specify a title for a plot.  If you already have a plot displayed,
  806.      use  the command `replot' to redisplay it with the new title.
  807.  - Function File:  xlabel (STRING)
  808.  - Function File:  ylabel (STRING)
  809.  - Function File:  zlabel (STRING)
  810.      Specify x, y, and z axis labels for the plot.  If you already have
  811.      a plot  displayed, use the command `replot' to redisplay it with
  812.      the new  labels.
  813. File: octave,  Node: Multiple Plots on One Page,  Prev: Plot Annotations,  Up: Plotting
  814. Multiple Plots on One Page
  815. ==========================
  816.    The following functions all require a version of `gnuplot' that
  817. supports the multiplot feature.
  818.  - Function File:  mplot (X, Y)
  819.  - Function File:  mplot (X, Y, FMT)
  820.  - Function File:  mplot (X1, Y1, X2, Y2)
  821.      This is a modified version of the `plot' function that works with
  822.      the multiplot version of `gnuplot' to plot multiple plots per page.
  823.      This plot version automatically advances to the next subplot
  824.      position  after each set of arguments are processed.
  825.      See the description of the PLOT function for the various options.
  826.  - Function File:  multiplot (XN, YN)
  827.      Sets and resets multiplot mode.
  828.      If the arguments are non-zero, `multiplot' will set up multiplot
  829.      mode with XN, YN subplots along the X and Y  axes.  If both
  830.      arguments are zero, `multiplot' closes multiplot  mode.
  831.  - Function File:  oneplot ()
  832.      If in multiplot mode, switches to single plot mode.
  833.  - Function File:  plot_border (...)
  834.      Multiple arguments allowed to specify the sides on which the border
  835.      is shown.  Allowed arguments include:
  836.     `"blank"'
  837.           No borders displayed.
  838.     `"all"'
  839.           All borders displayed
  840.     `"north"'
  841.           North Border
  842.     `"south"'
  843.           South Border
  844.     `"east"'
  845.           East Border
  846.     `"west"'
  847.           West Border
  848.      The arguments may be abbreviated to single characters.  Without any
  849.      arguments, `plot_border' turns borders off.
  850.  - Function File:  subplot (ROWS, COLS, INDEX)
  851.  - Function File:  subplot (RCN)
  852.      Sets `gnuplot' in multiplot mode and plots in location  given by
  853.      index (there are COLS by ROWS subwindows).
  854.      Input:
  855.     ROWS
  856.           Number of rows in subplot grid.
  857.     COLUMNS
  858.           Number of columns in subplot grid.
  859.     INDEX
  860.           Index of subplot where to make the next plot.
  861.      If only one argument is supplied, then it must be a three digit
  862.      value  specifying the location in digits 1 (rows) and 2 (columns)
  863.      and the plot  index in digit 3.
  864.      The plot index runs row-wise.  First all the columns in a row are
  865.      filled  and then the next row is filled.
  866.      For example, a plot with 4 by 2 grid will have plot indices
  867.      running as  follows:
  868.           +-----+-----+-----+-----+
  869.            |  1  |  2  |  3  |  4  |
  870.            +-----+-----+-----+-----+
  871.            |  5  |  6  |  7  |  8  |
  872.            +-----+-----+-----+-----+
  873.  - Function File:  subwindow (XN, YN)
  874.      Sets the subwindow position in multiplot mode for the next plot.
  875.      The  multiplot mode has to be previously initialized using the
  876.      `multiplot' function, otherwise this command just becomes an alias
  877.      to `multiplot'
  878.  - Function File:  top_title (STRING)
  879.  - Function File:  bottom_title (STRING)
  880.      Makes a title with text STRING at the top (bottom) of the plot.
  881.    % DO NOT EDIT!  Generated automatically by munge-texi.
  882. File: octave,  Node: Matrix Manipulation,  Next: Arithmetic,  Prev: Plotting,  Up: Top
  883. Matrix Manipulation
  884. *******************
  885.    There are a number of functions available for checking to see if the
  886. elements of a matrix meet some condition, and for rearranging the
  887. elements of a matrix.  For example, Octave can easily tell you if all
  888. the elements of a matrix are finite, or are less than some specified
  889. value.  Octave can also rotate the elements, extract the upper- or
  890. lower-triangular parts, or sort the columns of a matrix.
  891. * Menu:
  892. * Finding Elements and Checking Conditions::
  893. * Rearranging Matrices::
  894. * Special Utility Matrices::
  895. * Famous Matrices::
  896. File: octave,  Node: Finding Elements and Checking Conditions,  Next: Rearranging Matrices,  Prev: Matrix Manipulation,  Up: Matrix Manipulation
  897. Finding Elements and Checking Conditions
  898. ========================================
  899.    The functions `any' and `all' are useful for determining whether any
  900. or all of the elements of a matrix satisfy some condition.  The `find'
  901. function is also useful in determining which elements of a matrix meet
  902. a specified condition.
  903.  - Built-in Function:  any (X)
  904.      For a vector argument, return 1 if any element of the vector is
  905.      nonzero.
  906.      For a matrix argument, return a row vector of ones and zeros with
  907.      each element indicating whether any of the elements of the
  908.      corresponding column of the matrix are nonzero.  For example,
  909.           any (eye (2, 4))
  910.                => [ 1, 1, 0, 0 ]
  911.      To see if any of the elements of a matrix are nonzero, you can use
  912.      a statement like
  913.           any (any (a))
  914.  - Built-in Function:  all (X)
  915.      The function `all' behaves like the function `any', except that it
  916.      returns true only if all the elements of a vector, or all the
  917.      elements in a column of a matrix, are nonzero.
  918.    Since the comparison operators (*note Comparison Ops::.) return
  919. matrices of ones and zeros, it is easy to test a matrix for many
  920. things, not just whether the elements are nonzero.  For example,
  921.      all (all (rand (5) < 0.9))
  922.           => 0
  923. tests a random 5 by 5 matrix to see if all of its elements are less
  924. than 0.9.
  925.    Note that in conditional contexts (like the test clause of `if' and
  926. `while' statements) Octave treats the test as if you had typed `all
  927. (all (condition))'.
  928.  - Function File: [ERR, Y1, ...] = common_size (X1, ...)
  929.      Determine if all input arguments are either scalar or of common
  930.      size.  If so, ERR is zero, and YI is a matrix of the  common size
  931.      with all entries equal to XI if this is a scalar or XI otherwise.
  932.      If the inputs cannot be brought to a common size,  errorcode is 1,
  933.      and YI is XI.  For example,
  934.            [errorcode, a, b] = common_size ([1 2; 3 4], 5)
  935.           => errorcode = 0
  936.           => a = [ 1, 2; 3, 4 ]
  937.           => b = [ 5, 5; 5, 5 ]
  938.      This is useful for implementing functions where arguments can
  939.      either  be scalars or of common size.
  940.  - Function File:  diff (X, K)
  941.      If X is a vector of length N, `diff (X)' is the  vector of first
  942.      differences X(2) - X(1), ..., X(n) - X(n-1).
  943.      If X is a matrix, `diff (X)' is the matrix of column  differences.
  944.      The second argument is optional.  If supplied, `diff (X, K)',
  945.      where K is a nonnegative integer, returns the K-th differences.
  946.  - Mapping Function:  isinf (X)
  947.      Return 1 for elements of X that are infinite and zero otherwise.
  948.      For example,
  949.           isinf ([13, Inf, NaN])
  950.                => [ 0, 1, 0 ]
  951.  - Mapping Function:  isnan (X)
  952.      Return 1 for elements of X that are NaN values and zero otherwise.
  953.      For example,
  954.           isnan ([13, Inf, NaN])
  955.                => [ 0, 0, 1 ]
  956.  - Mapping Function:  finite (X)
  957.      Return 1 for elements of X that are NaN values and zero otherwise.
  958.      For example,
  959.           finite ([13, Inf, NaN])
  960.                => [ 1, 0, 0 ]
  961.  - Loadable Function:  find (X)
  962.      Return a vector of indices of nonzero elements of a matrix.  To
  963.      obtain a single index for each matrix element, Octave pretends
  964.      that the columns of a matrix form one long vector (like Fortran
  965.      arrays are stored).  For example,
  966.           find (eye (2))
  967.                => [ 1; 4 ]
  968.      If two outputs are requested, `find' returns the row and column
  969.      indices of nonzero elements of a matrix.  For example,
  970.           [i, j] = find (2 * eye (2))
  971.                => i = [ 1; 2 ]
  972.                => j = [ 1; 2 ]
  973.      If three outputs are requested, `find' also returns a vector
  974.      containing the nonzero values.  For example,
  975.           [i, j, v] = find (3 * eye (2))
  976.                => i = [ 1; 2 ]
  977.                => j = [ 1; 2 ]
  978.                => v = [ 3; 3 ]
  979.