home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / octa21eb.zip / octave / doc / octave.i03 < prev    next >
Encoding:
GNU Info File  |  1999-05-13  |  48.9 KB  |  1,642 lines
  1. This is Info file octave, produced by Makeinfo-1.64 from the input file
  2. octave.tex.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Octave: (octave).    Interactive language for numerical computations.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    Copyright (C) 1996, 1997 John W. Eaton.
  9.  
  10.    Permission is granted to make and distribute verbatim copies of this
  11. manual provided the copyright notice and this permission notice are
  12. preserved on all copies.
  13.  
  14.    Permission is granted to copy and distribute modified versions of
  15. this manual under the conditions for verbatim copying, provided that
  16. the entire resulting derived work is distributed under the terms of a
  17. permission notice identical to this one.
  18.  
  19.    Permission is granted to copy and distribute translations of this
  20. manual into another language, under the above conditions for modified
  21. versions.
  22.  
  23. 
  24. File: octave,  Node: Data Structures,  Next: Variables,  Prev: Strings,  Up: Top
  25.  
  26. Data Structures
  27. ***************
  28.  
  29.    Octave includes support for organizing data in structures.  The
  30. current implementation uses an associative array with indices limited to
  31. strings, but the syntax is more like C-style structures.  Here are some
  32. examples of using data structures in Octave.
  33.  
  34.    Elements of structures can be of any value type.  For example, the
  35. three expressions
  36.  
  37.      x.a = 1
  38.      x.b = [1, 2; 3, 4]
  39.      x.c = "string"
  40.  
  41. create a structure with three elements.  To print the value of the
  42. structure, you can type its name, just as for any other variable:
  43.  
  44.      octave:2> x
  45.      x =
  46.      {
  47.        a = 1
  48.        b =
  49.      
  50.          1  2
  51.          3  4
  52.      
  53.        c = string
  54.      }
  55.  
  56. Note that Octave may print the elements in any order.
  57.  
  58.    Structures may be copied.
  59.  
  60.      octave:1> y = x
  61.      y =
  62.      {
  63.        a = 1
  64.        b =
  65.      
  66.          1  2
  67.          3  4
  68.      
  69.        c = string
  70.      }
  71.  
  72.    Since structures are themselves values, structure elements may
  73. reference other structures.  The following statements change the value
  74. of the element `b' of the structure `x' to be a data structure
  75. containing the single element `d', which has a value of 3.
  76.  
  77.      octave:1> x.b.d = 3
  78.      x.b.d = 3
  79.      octave:2> x.b
  80.      ans =
  81.      {
  82.        d = 3
  83.      }
  84.      octave:3> x
  85.      x =
  86.      {
  87.        a = 1
  88.        b =
  89.        {
  90.          d = 3
  91.        }
  92.      
  93.        c = string
  94.      }
  95.  
  96.    Note that when Octave prints the value of a structure that contains
  97. other structures, only a few levels are displayed.  For example,
  98.  
  99.      octave:1> a.b.c.d.e = 1;
  100.      octave:2> a
  101.      a =
  102.      {
  103.        b =
  104.        {
  105.          c = <structure>
  106.        }
  107.      }
  108.  
  109. This prevents long and confusing output from large deeply nested
  110. structures.
  111.  
  112.  - Built-in Variable: struct_levels_to_print
  113.      You can tell Octave how many structure levels to display by
  114.      setting the built-in variable `struct_levels_to_print'.  The
  115.      default value is 2.
  116.  
  117.    Functions can return structures.  For example, the following function
  118. separates the real and complex parts of a matrix and stores them in two
  119. elements of the same structure variable.
  120.  
  121.      octave:1> function y = f (x)
  122.      > y.re = real (x);
  123.      > y.im = imag (x);
  124.      > endfunction
  125.  
  126.    When called with a complex-valued argument, `f' returns the data
  127. structure containing the real and imaginary parts of the original
  128. function argument.
  129.  
  130.      octave:2> f (rand (2) + rand (2) * I);
  131.      ans =
  132.      {
  133.        im =
  134.      
  135.          0.26475  0.14828
  136.          0.18436  0.83669
  137.      
  138.        re =
  139.      
  140.          0.040239  0.242160
  141.          0.238081  0.402523
  142.      }
  143.  
  144.    Function return lists can include structure elements, and they may be
  145. indexed like any other variable.  For example,
  146.  
  147.      octave:1> [ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4])
  148.      x.u =
  149.      
  150.        -0.40455  -0.91451
  151.        -0.91451   0.40455
  152.      
  153.      x.s =
  154.      
  155.        0.00000  0.00000  0.00000
  156.        0.00000  5.46499  0.00000
  157.        0.00000  0.00000  0.36597
  158.      
  159.      x.v =
  160.      
  161.        -0.57605   0.81742
  162.        -0.81742  -0.57605
  163.  
  164.    It is also possible to cycle through all the elements of a structure
  165. in a loop, using a special form of the `for' statement (*note The for
  166. Statement::.)
  167.  
  168.    The following functions are available to give you information about
  169. structures.
  170.  
  171.  - Built-in Function:  is_struct (EXPR)
  172.      Return 1 if the value of the expression EXPR is a structure.
  173.  
  174.  - Built-in Function:  struct_contains (EXPR, NAME)
  175.      Return 1 if the expression EXPR is a structure and it includes an
  176.      element named NAME.  The first argument must be a structure and
  177.      the second must be a string.
  178.  
  179.  - Built-in Function:  struct_elements (STRUCT)
  180.      Return a list of strings naming the elements of the structure
  181.      STRUCT.  It is an error to call `struct_elements' with an argument
  182.      that is not a structure.
  183.  
  184. 
  185. File: octave,  Node: Variables,  Next: Expressions,  Prev: Data Structures,  Up: Top
  186.  
  187. Variables
  188. *********
  189.  
  190.    Variables let you give names to values and refer to them later.  You
  191. have already seen variables in many of the examples.  The name of a
  192. variable must be a sequence of letters, digits and underscores, but it
  193. may not begin with a digit.  Octave does not enforce a limit on the
  194. length of variable names, but it is seldom useful to have variables
  195. with names longer than about 30 characters.  The following are all
  196. valid variable names
  197.  
  198.      x
  199.      x15
  200.      __foo_bar_baz__
  201.      fucnrdthsucngtagdjb
  202.  
  203. However, names like `__foo_bar_baz__' that begin and end with two
  204. underscores are understood to be reserved for internal use by Octave.
  205. You should not use them in code you write, except to access Octave's
  206. documented internal variables and built-in symbolic constants.
  207.  
  208.    Case is significant in variable names.  The symbols `a' and `A' are
  209. distinct variables.
  210.  
  211.    A variable name is a valid expression by itself.  It represents the
  212. variable's current value.  Variables are given new values with
  213. "assignment operators" and "increment operators".  *Note Assignment
  214. Expressions: Assignment Ops.
  215.  
  216.    A number of variables have special built-in meanings.  For example,
  217. `ans' holds the current working directory, and `pi' names the ratio of
  218. the circumference of a circle to its diameter. *Note Summary of
  219. Built-in Variables::, for a list of all the predefined variables.  Some
  220. of these built-in symbols are constants and may not be changed.  Others
  221. can be used and assigned just like all other variables, but their values
  222. are also used or changed automatically by Octave.
  223.  
  224.    Variables in Octave do not have fixed types, so it is possible to
  225. first store a numeric value in a variable and then to later use the
  226. same name to hold a string value in the same program.  Variables may
  227. not be used before they have been given a value.  Doing so results in
  228. an error.
  229.  
  230. * Menu:
  231.  
  232. * Global Variables::
  233. * Status of Variables::
  234. * Summary of Built-in Variables::
  235. * Defaults from the Environment::
  236.  
  237. 
  238. File: octave,  Node: Global Variables,  Next: Status of Variables,  Prev: Variables,  Up: Variables
  239.  
  240. Global Variables
  241. ================
  242.  
  243.    A variable that has been declared "global" may be accessed from
  244. within a function body without having to pass it as a formal parameter.
  245.  
  246.    A variable may be declared global using a `global' declaration
  247. statement.  The following statements are all global declarations.
  248.  
  249.      global a
  250.      global b = 2
  251.      global c = 3, d, e = 5
  252.  
  253.    It is necessary declare a variable as global within a function body
  254. in order to access it.  For example,
  255.  
  256.      global x
  257.      function f ()
  258.        x = 1;
  259.      endfunction
  260.      f ()
  261.  
  262. does *not* set the value of the global variable `x' to 1.  In order to
  263. change the value of the global variable `x', you must also declare it
  264. to be global within the function body, like this
  265.  
  266.      function f ()
  267.        global x;
  268.        x = 1;
  269.      endfunction
  270.  
  271.    Passing a global variable in a function parameter list will make a
  272. local copy and not modify the global value.  For example, given the
  273. function
  274.  
  275.      function f (x)
  276.        x = 0
  277.      endfunction
  278.  
  279. and the definition of `x' as a global variable at the top level,
  280.  
  281.      global x = 13
  282.  
  283. the expression
  284.  
  285.      f (x)
  286.  
  287. will display the value of `x' from inside the function as 0, but the
  288. value of `x' at the top level remains unchanged, because the function
  289. works with a *copy* of its argument.
  290.  
  291.  - Built-in Variable: warn_comma_in_global_decl
  292.      If the value of `warn_comma_in_global_decl' is nonzero, a warning
  293.      is issued for statements like
  294.  
  295.           global a = 1, b
  296.  
  297.      which makes the variables `a' and `b' global and assigns the value
  298.      1 to the variable `a', because in this context, the comma is not
  299.      interpreted as a statement separator.
  300.  
  301.      The default value of `warn_comma_in_global_decl' is nonzero.
  302.  
  303.  - default_global_variable_value:
  304.      if `initialize_global_variables' is nonzero, the value of
  305.      `default_glbaol_variable_value' is used as the initial value of
  306.      global variables that are not explicitly initialized.  for example,
  307.  
  308.           initialize_global_variables = 1;
  309.           default_global_variable_value = 13;
  310.           global foo;
  311.           foo
  312.                => 13
  313.  
  314.      the variable `default_global_variable_value' is initially
  315.      undefined.
  316.  
  317.  - Built-in Function:  is_global (NAME)
  318.      Return 1 if NAME is globally visible.  Otherwise, return 0.  For
  319.      example,
  320.  
  321.           global x
  322.           is_global ("x")
  323.                => 1
  324.  
  325. 
  326. File: octave,  Node: Status of Variables,  Next: Summary of Built-in Variables,  Prev: Global Variables,  Up: Variables
  327.  
  328. Status of Variables
  329. ===================
  330.  
  331.  - Command: clear OPTIONS PATTERN ...
  332.      Delete the names matching the given patterns from the symbol
  333.      table.  The pattern may contain the following special characters:
  334.     `?'
  335.           Match any single character.
  336.  
  337.     `*'
  338.           Match zero or more characters.
  339.  
  340.     `[ LIST ]'
  341.           Match the list of characters specified by LIST.  If the first
  342.           character is `!' or `^', match all characters except those
  343.           specified by LIST.  For example, the pattern `[a-zA-Z]' will
  344.           match all lower and upper case alphabetic characters.
  345.  
  346.      For example, the command
  347.  
  348.           clear foo b*r
  349.  
  350.      clears the name `foo' and all names that begin with the letter `b'
  351.      and end with the letter `r'.
  352.  
  353.      If `clear' is called without any arguments, all user-defined
  354.      variables (local and global) are cleared from the symbol table.  If
  355.      `clear' is called with at least one argument, only the visible
  356.      names matching the arguments are cleared.  For example, suppose
  357.      you have defined a function `foo', and then hidden it by
  358.      performing the assignment `foo = 2'.  Executing the command `clear
  359.      foo' once will clear the variable definition and restore the
  360.      definition of `foo' as a function.  Executing `clear foo' a second
  361.      time will clear the function definition.
  362.  
  363.      This command may not be used within a function body.
  364.  
  365.  - Command: who OPTIONS PATTERN ...
  366.  - Command: whos OPTIONS PATTERN ...
  367.      List currently defined symbols matching the given patterns.  The
  368.      following are valid options.  They may be shortened to one
  369.      character but may not be combined.
  370.  
  371.     `-all'
  372.           List all currently defined symbols.
  373.  
  374.     `-builtins'
  375.           List built-in variables and functions.  This includes all
  376.           currently compiled function files, but does not include all
  377.           function files that are in the `LOADPATH'.
  378.  
  379.     `-functions'
  380.           List user-defined functions.
  381.  
  382.     `-long'
  383.           Print a long listing including the type and dimensions of any
  384.           symbols.  The symbols in the first column of output indicate
  385.           whether it is possible to redefine the symbol, and whether it
  386.           is possible for it to be cleared.
  387.  
  388.     `-variables'
  389.           List user-defined variables.
  390.  
  391.      Valid patterns are the same as described for the `clear' command
  392.      above.  If no patterns are supplied, all symbols from the given
  393.      category are listed.  By default, only user defined functions and
  394.      variables visible in the local scope are displayed.
  395.  
  396.      The command `whos' is equivalent to `who -long'.
  397.  
  398.  - Built-in Function:  exist (NAME)
  399.      Return 1 if the name exists as a variable, 2 if the name (after
  400.      appending `.m') is a function file in the path, 3 if the name is a
  401.      `.oct' file in the path, or 5 if the name is a built-in function.
  402.      Otherwise, return 0.
  403.  
  404.  - Built-in Function:  document (SYMBOL, TEXT)
  405.      Set the documentation string for SYMBOL to TEXT.
  406.  
  407.  - Command: type OPTIONS NAME ...
  408.      Display the definition of each NAME that refers to a function.
  409.  
  410.      Normally also displays if each NAME is user-defined or builtin;
  411.      the `-q' option suppresses this behaviour.
  412.  
  413.      Currently, Octave can only display functions that can be compiled
  414.      cleanly, because it uses its internal representation of the
  415.      function to recreate the program text.
  416.  
  417.      Comments are not displayed because Octave's parser currently
  418.      discards them as it converts the text of a function file to its
  419.      internal representation.  This problem may be fixed in a future
  420.      release.
  421.  
  422.  - Command: which NAME ...
  423.      Display the type of each NAME.  If NAME is defined from a function
  424.      file, the full name of the file is also displayed.
  425.  
  426. 
  427. File: octave,  Node: Summary of Built-in Variables,  Next: Defaults from the Environment,  Prev: Status of Variables,  Up: Variables
  428.  
  429. Summary of Built-in Variables
  430. =============================
  431.  
  432.    Here is a summary of all of Octave's built-in variables along with
  433. cross references to additional information and their default values.  In
  434. the following table OCTAVE-HOME stands for the root directory where all
  435. of Octave is installed (the default is `', VERSION stands for the
  436. Octave version number (for example, 2.1.14) and ARCH stands for the
  437. type of system for which Octave was compiled (for example,
  438. `i486-pc-os/2').
  439.  
  440. `DEFAULT_LOADPATH'
  441.      *Note Function Files::.
  442.  
  443.      Default value: `".:OCTAVE-HOME/lib/VERSION"'.
  444.  
  445. `EDITOR'
  446.      *Note Commands For History::.
  447.  
  448.      Default value: `"emacs"'.
  449.  
  450. `EXEC_PATH'
  451.      *Note Controlling Subprocesses::.
  452.  
  453.      Default value: `":$PATH"'.
  454.  
  455. `INFO_FILE'
  456.      *Note Getting Help::.
  457.  
  458.      Default value: `"OCTAVE-HOME/info/octave.info"'.
  459.  
  460. `INFO_PROGRAM'
  461.      *Note Getting Help::.
  462.  
  463.      Default value:
  464.      `"OCTAVE-HOME/libexec/octave/VERSION/exec/ARCH/info"'.
  465.  
  466. `LOADPATH'
  467.      *Note Function Files::.
  468.  
  469.      Default value: `":"', which tells Octave to use the directories
  470.      specified by the built-in variable `DEFAULT_LOADPATH'.
  471.  
  472. `OCTAVE_HOME'
  473.      Default value: `""'.
  474.  
  475. `PAGER'
  476.      *Note Input and Output::.
  477.  
  478.      Default value: `"less", or "more"'.
  479.  
  480. `PS1'
  481.      *Note Customizing the Prompt::.
  482.  
  483.      Default value: `"\s:\#> "'.
  484.  
  485. `PS2'
  486.      *Note Customizing the Prompt::.
  487.  
  488.      Default value: `"> "'.
  489.  
  490. `PS4'
  491.      *Note Customizing the Prompt::.
  492.  
  493.      Default value: `"+ "'.
  494.  
  495. `auto_unload_dot_oct_files'
  496.      *Note Dynamically Linked Functions::.
  497.  
  498.      Default value: 0.
  499.  
  500. `automatic_replot'
  501.      *Note Two-Dimensional Plotting::.
  502.  
  503.      Default value: 0.
  504.  
  505. `beep_on_error'
  506.      *Note Error Handling::.
  507.  
  508.      Default value: 0.
  509.  
  510. `completion_append_char'
  511.      *Note Commands For Completion::.
  512.  
  513.      Default value: `" "'.
  514.  
  515. `default_eval_print_flag'
  516.      *Note Evaluation::.
  517.  
  518.      Default value: 1.
  519.  
  520. `default_return_value'
  521.      *Note Multiple Return Values::.
  522.  
  523.      Default value: `[]'.
  524.  
  525. `default_save_format'
  526.      *Note Simple File I/O::.
  527.  
  528.      Default value: `"ascii"'.
  529.  
  530. `do_fortran_indexing'
  531.      *Note Index Expressions::.
  532.  
  533.      Default value: 0.
  534.  
  535. `crash_dumps_octave_core'
  536.      *Note Simple File I/O::.
  537.  
  538.      Default value: 1.
  539.  
  540. `define_all_return_values'
  541.      *Note Multiple Return Values::.
  542.  
  543.      Default value: 0.
  544.  
  545. `empty_list_elements_ok'
  546.      *Note Empty Matrices::.
  547.  
  548.      Default value: `"warn"'.
  549.  
  550. `fixed_point_format'
  551.      *Note Matrices::.
  552.  
  553.      Default value: 0.
  554.  
  555. `gnuplot_binary'
  556.      *Note Three-Dimensional Plotting::.
  557.  
  558.      Default value: `"gnuplot"'.
  559.  
  560. `history_file'
  561.      *Note Commands For History::.
  562.  
  563.      Default value: `"~/.octave_hist"'.
  564.  
  565. `history_size'
  566.      *Note Commands For History::.
  567.  
  568.      Default value: 1024.
  569.  
  570. `ignore_function_time_stamp'
  571.      *Note Function Files::.
  572.  
  573.      Default value: `"system"'.
  574.  
  575. `implicit_num_to_str_ok'
  576.      *Note String Conversions::.
  577.  
  578.      Default value: 0.
  579.  
  580. `implicit_str_to_num_ok'
  581.      *Note String Conversions::.
  582.  
  583.      Default value: 0.
  584.  
  585. `max_recursion_depth'
  586.      *Note Recursion::.
  587.  
  588.      Default value: 256.
  589.  
  590. `ok_to_lose_imaginary_part'
  591.      *Note Special Utility Matrices::.
  592.  
  593.      Default value: `"warn"'.
  594.  
  595. `output_max_field_width'
  596.      *Note Matrices::.
  597.  
  598.      Default value: 10.
  599.  
  600. `output_precision'
  601.      *Note Matrices::.
  602.  
  603.      Default value: 5.
  604.  
  605. `page_screen_output'
  606.      *Note Input and Output::.
  607.  
  608.      Default value: 1.
  609.  
  610. `prefer_column_vectors'
  611.      *Note Index Expressions::.
  612.  
  613.      Default value: 1.
  614.  
  615. `print_answer_id_name'
  616.      *Note Terminal Output::.
  617.  
  618.      Default value: 1.
  619.  
  620. `print_empty_dimensions'
  621.      *Note Empty Matrices::.
  622.  
  623.      Default value: 1.
  624.  
  625. `resize_on_range_error'
  626.      *Note Index Expressions::.
  627.  
  628.      Default value: 1.
  629.  
  630. `return_last_computed_value'
  631.      *Note Returning From a Function::.
  632.  
  633.      Default value: 0.
  634.  
  635. `save_precision'
  636.      *Note Simple File I/O::.
  637.  
  638.      Default value: 17.
  639.  
  640. `saving_history'
  641.      *Note Commands For History::.
  642.  
  643.      Default value: 1.
  644.  
  645. `silent_functions'
  646.      *Note Defining Functions::.
  647.  
  648.      Default value: 0.
  649.  
  650. `split_long_rows'
  651.      *Note Matrices::.
  652.  
  653.      Default value: 1.
  654.  
  655. `struct_levels_to_print'
  656.      *Note Data Structures::.
  657.  
  658.      Default value: 2.
  659.  
  660. `suppress_verbose_help_message'
  661.      *Note Getting Help::.
  662.  
  663.      Default value: 1.
  664.  
  665. `treat_neg_dim_as_zero'
  666.      *Note Special Utility Matrices::.
  667.  
  668.      Default value: 0.
  669.  
  670. `warn_assign_as_truth_value'
  671.      *Note The if Statement::.
  672.  
  673.      Default value: 1.
  674.  
  675. `warn_comma_in_global_decl'
  676.      *Note Global Variables::.
  677.  
  678.      Default value: 1.
  679.  
  680. `warn_divide_by_zero'
  681.      *Note Arithmetic Ops::.
  682.  
  683.      Default value: 1.
  684.  
  685. `warn_function_name_clash'
  686.      *Note Function Files::.
  687.  
  688.      Default value: 1.
  689.  
  690. `warn_reload_forces_clear'
  691.      *Note Dynamically Linked Functions::.
  692.  
  693.      Default value: 1.
  694.  
  695. `warn_variable_switch_label'
  696.      *Note The switch Statement::.
  697.  
  698.      Default value: 0.
  699.  
  700. `whitespace_in_literal_matrix'
  701.      *Note Matrices::.
  702.  
  703.      Default value: `""'.
  704.  
  705. 
  706. File: octave,  Node: Defaults from the Environment,  Prev: Summary of Built-in Variables,  Up: Variables
  707.  
  708. Defaults from the Environment
  709. =============================
  710.  
  711.    Octave uses the values of the following environment variables to set
  712. the default values for the corresponding built-in variables.  In
  713. addition, the values from the environment may be overridden by
  714. command-line arguments.  *Note Command Line Options::.
  715.  
  716. `EDITOR'
  717.      *Note Commands For History::.
  718.  
  719.      Built-in variable: `EDITOR'.
  720.  
  721. `OCTAVE_EXEC_PATH'
  722.      *Note Controlling Subprocesses::.
  723.  
  724.      Built-in variable: `EXEC_PATH'.  Command-line argument:
  725.      `--exec-path'.
  726.  
  727. `OCTAVE_PATH'
  728.      *Note Function Files::.
  729.  
  730.      Built-in variable: `LOADPATH'.  Command-line argument: `--path'.
  731.  
  732. `OCTAVE_INFO_FILE'
  733.      *Note Getting Help::.
  734.  
  735.      Built-in variable: `INFO_FILE'.  Command-line argument:
  736.      `--info-file'.
  737.  
  738. `OCTAVE_INFO_PROGRAM'
  739.      *Note Getting Help::.
  740.  
  741.      Built-in variable: `INFO_PROGRAM'.  Command-line argument:
  742.      `--info-program'.
  743.  
  744. `OCTAVE_HISTSIZE'
  745.      *Note Commands For History::.
  746.  
  747.      Built-in variable: `history_size'.
  748.  
  749. `OCTAVE_HISTFILE'
  750.      *Note Commands For History::.
  751.  
  752.      Built-in variable: `history_file'.
  753.  
  754. 
  755. File: octave,  Node: Expressions,  Next: Evaluation,  Prev: Variables,  Up: Top
  756.  
  757. Expressions
  758. ***********
  759.  
  760.    Expressions are the basic building block of statements in Octave.  An
  761. expression evaluates to a value, which you can print, test, store in a
  762. variable, pass to a function, or assign a new value to a variable with
  763. an assignment operator.
  764.  
  765.    An expression can serve as a statement on its own.  Most other kinds
  766. of statements contain one or more expressions which specify data to be
  767. operated on.  As in other languages, expressions in Octave include
  768. variables, array references, constants, and function calls, as well as
  769. combinations of these with various operators.
  770.  
  771. * Menu:
  772.  
  773. * Index Expressions::
  774. * Calling Functions::
  775. * Arithmetic Ops::
  776. * Comparison Ops::
  777. * Boolean Expressions::
  778. * Assignment Ops::
  779. * Increment Ops::
  780. * Operator Precedence::
  781.  
  782. 
  783. File: octave,  Node: Index Expressions,  Next: Calling Functions,  Prev: Expressions,  Up: Expressions
  784.  
  785. Index Expressions
  786. =================
  787.  
  788.    An "index expression" allows you to reference or extract selected
  789. elements of a matrix or vector.
  790.  
  791.    Indices may be scalars, vectors, ranges, or the special operator
  792. `:', which may be used to select entire rows or columns.
  793.  
  794.    Vectors are indexed using a single expression.  Matrices require two
  795. indices unless the value of the built-in variable `do_fortran_indexing'
  796. is nonzero, in which case matrices may also be indexed by a single
  797. expression.
  798.  
  799.  - Built-in Variable: do_fortran_indexing
  800.      If the value of `do_fortran_indexing' is nonzero, Octave allows
  801.      you to select elements of a two-dimensional matrix using a single
  802.      index by treating the matrix as a single vector created from the
  803.      columns of the matrix.  The default value is 0.
  804.  
  805.    Given the matrix
  806.  
  807.      a = [1, 2; 3, 4]
  808.  
  809. all of the following expressions are equivalent
  810.  
  811.      a (1, [1, 2])
  812.      a (1, 1:2)
  813.      a (1, :)
  814.  
  815. and select the first row of the matrix.
  816.  
  817.    A special form of indexing may be used to select elements of a
  818. matrix or vector.  If the indices are vectors made up of only ones and
  819. zeros, the result is a new matrix whose elements correspond to the
  820. elements of the index vector that are equal to one.  For example,
  821.  
  822.      a = [1, 2; 3, 4];
  823.      a ([1, 0], :)
  824.  
  825. selects the first row of the matrix `a'.
  826.  
  827.    This operation can be useful for selecting elements of a matrix
  828. based on some condition, since the comparison operators return matrices
  829. of ones and zeros.
  830.  
  831.    This special zero-one form of indexing leads to a conflict with the
  832. standard indexing operation.  For example, should the following
  833. statements
  834.  
  835.      a = [1, 2; 3, 4];
  836.      a ([1, 1], :)
  837.  
  838. return the original matrix, or the matrix formed by selecting the first
  839. row twice?  Although this conflict is not likely to arise very often in
  840. practice, you may select the behavior you prefer by setting the built-in
  841. variable `prefer_zero_one_indexing'.
  842.  
  843.  - Built-in Variable: prefer_zero_one_indexing
  844.      If the value of `prefer_zero_one_indexing' is nonzero, Octave will
  845.      perform zero-one style indexing when there is a conflict with the
  846.      normal indexing rules.  *Note Index Expressions::.  For example,
  847.      given a matrix
  848.  
  849.           a = [1, 2, 3, 4]
  850.  
  851.      with `prefer_zero_one_indexing' is set to nonzero, the expression
  852.  
  853.           a ([1, 1, 1, 1])
  854.  
  855.      results in the matrix `[ 1, 2, 3, 4 ]'.  If the value of
  856.      `prefer_zero_one_indexing' set to 0, the result would be the
  857.      matrix `[ 1, 1, 1, 1 ]'.
  858.  
  859.      In the first case, Octave is selecting each element corresponding
  860.      to a `1' in the index vector.  In the second, Octave is selecting
  861.      the first element multiple times.
  862.  
  863.      The default value for `prefer_zero_one_indexing' is 0.
  864.  
  865.    Finally, indexing a scalar with a vector of ones can be used to
  866. create a vector the same size as the index vector, with each element
  867. equal to the value of the original scalar.  For example, the following
  868. statements
  869.  
  870.      a = 13;
  871.      a ([1, 1, 1, 1])
  872.  
  873. produce a vector whose four elements are all equal to 13.
  874.  
  875.    Similarly, indexing a scalar with two vectors of ones can be used to
  876. create a matrix.  For example the following statements
  877.  
  878.      a = 13;
  879.      a ([1, 1], [1, 1, 1])
  880.  
  881. create a 2 by 3 matrix with all elements equal to 13.
  882.  
  883.    This is an obscure notation and should be avoided.  It is better to
  884. use the function `ones' to generate a matrix of the appropriate size
  885. whose elements are all one, and then to scale it to produce the desired
  886. result.  *Note Special Utility Matrices::.
  887.  
  888.  - Built-in Variable: prefer_column_vectors
  889.      If `prefer_column_vectors' is nonzero, operations like
  890.  
  891.           for i = 1:10
  892.             a (i) = i;
  893.           endfor
  894.  
  895.      (for `a' previously  undefined) produce column vectors.
  896.      Otherwise, row vectors are preferred.  The default value is 1.
  897.  
  898.      If a variable is already defined to be a vector (a matrix with a
  899.      single row or column), the original orientation is respected,
  900.      regardless of the value of `prefer_column_vectors'.
  901.  
  902.  - Built-in Variable: resize_on_range_error
  903.      If the value of `resize_on_range_error' is nonzero, expressions
  904.      like
  905.  
  906.           for i = 1:10
  907.             a (i) = sqrt (i);
  908.           endfor
  909.  
  910.      (for `a' previously undefined) result in the variable `a' being
  911.      resized to be just large enough to hold the new value.  New
  912.      elements that have not been given a value are set to zero.  If the
  913.      value of `resize_on_range_error' is 0, an error message is printed
  914.      and control is returned to the top level.  The default value is 1.
  915.  
  916.    Note that it is quite inefficient to create a vector using a loop
  917. like the one shown in the example above.  In this particular case, it
  918. would have been much more efficient to use the expression
  919.  
  920.      a = sqrt (1:10);
  921.  
  922. thus avoiding the loop entirely.  In cases where a loop is still
  923. required, or a number of values must be combined to form a larger
  924. matrix, it is generally much faster to set the size of the matrix first,
  925. and then insert elements using indexing commands.  For example, given a
  926. matrix `a',
  927.  
  928.      [nr, nc] = size (a);
  929.      x = zeros (nr, n * nc);
  930.      for i = 1:n
  931.        x(:,(i-1)*n+1:i*n) = a;
  932.      endfor
  933.  
  934. is considerably faster than
  935.  
  936.      x = a;
  937.      for i = 1:n-1
  938.        x = [x, a];
  939.      endfor
  940.  
  941. particularly for large matrices because Octave does not have to
  942. repeatedly resize the result.
  943.  
  944. 
  945. File: octave,  Node: Calling Functions,  Next: Arithmetic Ops,  Prev: Index Expressions,  Up: Expressions
  946.  
  947. Calling Functions
  948. =================
  949.  
  950.    A "function" is a name for a particular calculation.  Because it has
  951. a name, you can ask for it by name at any point in the program.  For
  952. example, the function `sqrt' computes the square root of a number.
  953.  
  954.    A fixed set of functions are "built-in", which means they are
  955. available in every Octave program.  The `sqrt' function is one of
  956. these.  In addition, you can define your own functions.  *Note
  957. Functions and Scripts::, for information about how to do this.
  958.  
  959.    The way to use a function is with a "function call" expression,
  960. which consists of the function name followed by a list of "arguments"
  961. in parentheses. The arguments are expressions which give the raw
  962. materials for the calculation that the function will do.  When there is
  963. more than one argument, they are separated by commas.  If there are no
  964. arguments, you can omit the parentheses, but it is a good idea to
  965. include them anyway, to clearly indicate that a function call was
  966. intended.  Here are some examples:
  967.  
  968.      sqrt (x^2 + y^2)      # One argument
  969.      ones (n, m)           # Two arguments
  970.      rand ()               # No arguments
  971.  
  972.    Each function expects a particular number of arguments.  For
  973. example, the `sqrt' function must be called with a single argument, the
  974. number to take the square root of:
  975.  
  976.      sqrt (ARGUMENT)
  977.  
  978.    Some of the built-in functions take a variable number of arguments,
  979. depending on the particular usage, and their behavior is different
  980. depending on the number of arguments supplied.
  981.  
  982.    Like every other expression, the function call has a value, which is
  983. computed by the function based on the arguments you give it.  In this
  984. example, the value of `sqrt (ARGUMENT)' is the square root of the
  985. argument.  A function can also have side effects, such as assigning the
  986. values of certain variables or doing input or output operations.
  987.  
  988.    Unlike most languages, functions in Octave may return multiple
  989. values.  For example, the following statement
  990.  
  991.      [u, s, v] = svd (a)
  992.  
  993. computes the singular value decomposition of the matrix `a' and assigns
  994. the three result matrices to `u', `s', and `v'.
  995.  
  996.    The left side of a multiple assignment expression is itself a list of
  997. expressions, and is allowed to be a list of variable names or index
  998. expressions.  See also *Note Index Expressions::, and *Note Assignment
  999. Ops::.
  1000.  
  1001. * Menu:
  1002.  
  1003. * Call by Value::
  1004. * Recursion::
  1005.  
  1006. 
  1007. File: octave,  Node: Call by Value,  Next: Recursion,  Prev: Calling Functions,  Up: Calling Functions
  1008.  
  1009. Call by Value
  1010. -------------
  1011.  
  1012.    In Octave, unlike Fortran, function arguments are passed by value,
  1013. which means that each argument in a function call is evaluated and
  1014. assigned to a temporary location in memory before being passed to the
  1015. function.  There is currently no way to specify that a function
  1016. parameter should be passed by reference instead of by value.  This
  1017. means that it is impossible to directly alter the value of function
  1018. parameter in the calling function.  It can only change the local copy
  1019. within the function body.  For example, the function
  1020.  
  1021.      function f (x, n)
  1022.        while (n-- > 0)
  1023.          disp (x);
  1024.        endwhile
  1025.      endfunction
  1026.  
  1027. displays the value of the first argument N times.  In this function,
  1028. the variable N is used as a temporary variable without having to worry
  1029. that its value might also change in the calling function.  Call by
  1030. value is also useful because it is always possible to pass constants
  1031. for any function parameter without first having to determine that the
  1032. function will not attempt to modify the parameter.
  1033.  
  1034.    The caller may use a variable as the expression for the argument, but
  1035. the called function does not know this: it only knows what value the
  1036. argument had.  For example, given a function called as
  1037.  
  1038.      foo = "bar";
  1039.      fcn (foo)
  1040.  
  1041. you should not think of the argument as being "the variable `foo'."
  1042. Instead, think of the argument as the string value, `"bar"'.
  1043.  
  1044.    Even though Octave uses pass-by-value semantics for function
  1045. arguments, values are not copied unnecessarily.  For example,
  1046.  
  1047.      x = rand (1000);
  1048.      f (x);
  1049.  
  1050. does not actually force two 1000 by 1000 element matrices to exist
  1051. *unless* the function `f' modifies the value of its argument.  Then
  1052. Octave must create a copy to avoid changing the value outside the scope
  1053. of the function `f', or attempting (and probably failing!) to modify
  1054. the value of a constant or the value of a temporary result.
  1055.  
  1056. 
  1057. File: octave,  Node: Recursion,  Prev: Call by Value,  Up: Calling Functions
  1058.  
  1059. Recursion
  1060. ---------
  1061.  
  1062.    With some restrictions(1), recursive function calls are allowed.  A
  1063. "recursive function" is one which calls itself, either directly or
  1064. indirectly.  For example, here is an inefficient(2) way to compute the
  1065. factorial of a given integer:
  1066.  
  1067.      function retval = fact (n)
  1068.        if (n > 0)
  1069.          retval = n * fact (n-1);
  1070.        else
  1071.          retval = 1;
  1072.        endif
  1073.      endfunction
  1074.  
  1075.    This function is recursive because it calls itself directly.  It
  1076. eventually terminates because each time it calls itself, it uses an
  1077. argument that is one less than was used for the previous call.  Once the
  1078. argument is no longer greater than zero, it does not call itself, and
  1079. the recursion ends.
  1080.  
  1081.    The built-in variable `max_recursion_depth' specifies a limit to the
  1082. recursion depth and prevents Octave from recursing infinitely.
  1083.  
  1084.  - max_recursion_depth:
  1085.      Limit the number of times a function may be called recursively.
  1086.      If the limit is exceeded, an error message is printed and control
  1087.      returns to the top level.
  1088.  
  1089.      The default value is 256.
  1090.  
  1091.    ---------- Footnotes ----------
  1092.  
  1093.    (1)  Some of Octave's function are implemented in terms of functions
  1094. that cannot be called recursively.  For example, the ODE solver `lsode'
  1095. is ultimately implemented in a Fortran subroutine that cannot be called
  1096. recursively, so `lsode' should not be called either directly or
  1097. indirectly from within the user-supplied function that `lsode'
  1098. requires.  Doing so will result in undefined behavior.
  1099.  
  1100.    (2)  It would be much better to use `prod (1:n)', or `gamma (n+1)'
  1101. instead, after first checking to ensure that the value `n' is actually a
  1102. positive integer.
  1103.  
  1104. 
  1105. File: octave,  Node: Arithmetic Ops,  Next: Comparison Ops,  Prev: Calling Functions,  Up: Expressions
  1106.  
  1107. Arithmetic Operators
  1108. ====================
  1109.  
  1110.    The following arithmetic operators are available, and work on scalars
  1111. and matrices.
  1112.  
  1113. `X + Y'
  1114.      Addition.  If both operands are matrices, the number of rows and
  1115.      columns must both agree.  If one operand is a scalar, its value is
  1116.      added to all the elements of the other operand.
  1117.  
  1118. `X .+ Y'
  1119.      Element by element addition.  This operator is equivalent to `+'.
  1120.  
  1121. `X - Y'
  1122.      Subtraction.  If both operands are matrices, the number of rows and
  1123.      columns of both must agree.
  1124.  
  1125. `X .- Y'
  1126.      Element by element subtraction.  This operator is equivalent to
  1127.      `-'.
  1128.  
  1129. `X * Y'
  1130.      Matrix multiplication.  The number of columns of X must agree with
  1131.      the number of rows of Y.
  1132.  
  1133. `X .* Y'
  1134.      Element by element multiplication.  If both operands are matrices,
  1135.      the number of rows and columns must both agree.
  1136.  
  1137. `X / Y'
  1138.      Right division.  This is conceptually equivalent to the expression
  1139.  
  1140.           (inverse (y') * x')'
  1141.  
  1142.      but it is computed without forming the inverse of Y'.
  1143.  
  1144.      If the system is not square, or if the coefficient matrix is
  1145.      singular, a minimum norm solution is computed.
  1146.  
  1147. `X ./ Y'
  1148.      Element by element right division.
  1149.  
  1150. `X \ Y'
  1151.      Left division.  This is conceptually equivalent to the expression
  1152.  
  1153.           inverse (x) * y
  1154.  
  1155.      but it is computed without forming the inverse of X.
  1156.  
  1157.      If the system is not square, or if the coefficient matrix is
  1158.      singular, a minimum norm solution is computed.
  1159.  
  1160. `X .\ Y'
  1161.      Element by element left division.  Each element of Y is divided by
  1162.      each corresponding element of X.
  1163.  
  1164. `X ^ Y'
  1165. `X ** Y'
  1166.      Power operator.  If X and Y are both scalars, this operator
  1167.      returns X raised to the power Y.  If X is a scalar and Y is a
  1168.      square matrix, the result is computed using an eigenvalue
  1169.      expansion.  If X is a square matrix. the result is computed by
  1170.      repeated multiplication if Y is an integer, and by an eigenvalue
  1171.      expansion if Y is not an integer.  An error results if both X and
  1172.      Y are matrices.
  1173.  
  1174.      The implementation of this operator needs to be improved.
  1175.  
  1176. `X .^ Y'
  1177. `X .** Y'
  1178.      Element by element power operator.  If both operands are matrices,
  1179.      the number of rows and columns must both agree.
  1180.  
  1181. `-X'
  1182.      Negation.
  1183.  
  1184. `+X'
  1185.      Unary plus.  This operator has no effect on the operand.
  1186.  
  1187. `X''
  1188.      Complex conjugate transpose.  For real arguments, this operator is
  1189.      the same as the transpose operator.  For complex arguments, this
  1190.      operator is equivalent to the expression
  1191.  
  1192.           conj (x.')
  1193.  
  1194. `X.''
  1195.      Transpose.
  1196.  
  1197.    Note that because Octave's element by element operators begin with a
  1198. `.', there is a possible ambiguity for statements like
  1199.  
  1200.      1./m
  1201.  
  1202. because the period could be interpreted either as part of the constant
  1203. or as part of the operator.  To resolve this conflict, Octave treats the
  1204. expression as if you had typed
  1205.  
  1206.      (1) ./ m
  1207.  
  1208. and not
  1209.  
  1210.      (1.) / m
  1211.  
  1212. Although this is inconsistent with the normal behavior of Octave's
  1213. lexer, which usually prefers to break the input into tokens by
  1214. preferring the longest possible match at any given point, it is more
  1215. useful in this case.
  1216.  
  1217.  - Built-in Variable: warn_divide_by_zero
  1218.      If the value of `warn_divide_by_zero' is nonzero, a warning is
  1219.      issued when Octave encounters a division by zero.  If the value is
  1220.      0, the warning is omitted.  The default value is 1.
  1221.  
  1222. 
  1223. File: octave,  Node: Comparison Ops,  Next: Boolean Expressions,  Prev: Arithmetic Ops,  Up: Expressions
  1224.  
  1225. Comparison Operators
  1226. ====================
  1227.  
  1228.    "Comparison operators" compare numeric values for relationships such
  1229. as equality.  They are written using *relational operators*.
  1230.  
  1231.    All of Octave's comparison operators return a value of 1 if the
  1232. comparison is true, or 0 if it is false.  For matrix values, they all
  1233. work on an element-by-element basis.  For example,
  1234.  
  1235.      [1, 2; 3, 4] == [1, 3; 2, 4]
  1236.           =>  1  0
  1237.               0  1
  1238.  
  1239.    If one operand is a scalar and the other is a matrix, the scalar is
  1240. compared to each element of the matrix in turn, and the result is the
  1241. same size as the matrix.
  1242.  
  1243. `X < Y'
  1244.      True if X is less than Y.
  1245.  
  1246. `X <= Y'
  1247.      True if X is less than or equal to Y.
  1248.  
  1249. `X == Y'
  1250.      True if X is equal to Y.
  1251.  
  1252. `X >= Y'
  1253.      True if X is greater than or equal to Y.
  1254.  
  1255. `X > Y'
  1256.      True if X is greater than Y.
  1257.  
  1258. `X != Y'
  1259. `X ~= Y'
  1260. `X <> Y'
  1261.      True if X is not equal to Y.
  1262.  
  1263.    String comparisons may also be performed with the `strcmp' function,
  1264. not with the comparison operators listed above.  *Note Strings::.
  1265.  
  1266. 
  1267. File: octave,  Node: Boolean Expressions,  Next: Assignment Ops,  Prev: Comparison Ops,  Up: Expressions
  1268.  
  1269. Boolean Expressions
  1270. ===================
  1271.  
  1272. * Menu:
  1273.  
  1274. * Element-by-element Boolean Operators::
  1275. * Short-circuit Boolean Operators::
  1276.  
  1277. 
  1278. File: octave,  Node: Element-by-element Boolean Operators,  Next: Short-circuit Boolean Operators,  Prev: Boolean Expressions,  Up: Boolean Expressions
  1279.  
  1280. Element-by-element Boolean Operators
  1281. ------------------------------------
  1282.  
  1283.    An "element-by-element boolean expression" is a combination of
  1284. comparison expressions using the boolean operators "or" (`|'), "and"
  1285. (`&'), and "not" (`!'), along with parentheses to control nesting.  The
  1286. truth of the boolean expression is computed by combining the truth
  1287. values of the corresponding elements of the component expressions.  A
  1288. value is considered to be false if it is zero, and true otherwise.
  1289.  
  1290.    Element-by-element boolean expressions can be used wherever
  1291. comparison expressions can be used.  They can be used in `if' and
  1292. `while' statements.  However, if a matrix value used as the condition
  1293. in an `if' or `while' statement is only true if *all* of its elements
  1294. are nonzero.
  1295.  
  1296.    Like comparison operations, each element of an element-by-element
  1297. boolean expression also has a numeric value (1 if true, 0 if false) that
  1298. comes into play if the result of the boolean expression is stored in a
  1299. variable, or used in arithmetic.
  1300.  
  1301.    Here are descriptions of the three element-by-element boolean
  1302. operators.
  1303.  
  1304. `BOOLEAN1 & BOOLEAN2'
  1305.      Elements of the result are true if both corresponding elements of
  1306.      BOOLEAN1 and BOOLEAN2 are true.
  1307.  
  1308. `BOOLEAN1 | BOOLEAN2'
  1309.      Elements of the result are true if either of the corresponding
  1310.      elements of BOOLEAN1 or BOOLEAN2 is true.
  1311.  
  1312. `! BOOLEAN'
  1313. `~ BOOLEAN'
  1314.      Each element of the result is true if the corresponding element of
  1315.      BOOLEAN is false.
  1316.  
  1317.    For matrix operands, these operators work on an element-by-element
  1318. basis.  For example, the expression
  1319.  
  1320.      [1, 0; 0, 1] & [1, 0; 2, 3]
  1321.  
  1322. returns a two by two identity matrix.
  1323.  
  1324.    For the binary operators, the dimensions of the operands must
  1325. conform if both are matrices.  If one of the operands is a scalar and
  1326. the other a matrix, the operator is applied to the scalar and each
  1327. element of the matrix.
  1328.  
  1329.    For the binary element-by-element boolean operators, both
  1330. subexpressions BOOLEAN1 and BOOLEAN2 are evaluated before computing the
  1331. result.  This can make a difference when the expressions have side
  1332. effects.  For example, in the expression
  1333.  
  1334.      a & b++
  1335.  
  1336. the value of the variable B is incremented even if the variable A is
  1337. zero.
  1338.  
  1339.    This behavior is necessary for the boolean operators to work as
  1340. described for matrix-valued operands.
  1341.  
  1342. 
  1343. File: octave,  Node: Short-circuit Boolean Operators,  Prev: Element-by-element Boolean Operators,  Up: Boolean Expressions
  1344.  
  1345. Short-circuit Boolean Operators
  1346. -------------------------------
  1347.  
  1348.    Combined with the implicit conversion to scalar values in `if' and
  1349. `while' conditions, Octave's element-by-element boolean operators are
  1350. often sufficient for performing most logical operations.  However, it
  1351. is sometimes desirable to stop evaluating a boolean expression as soon
  1352. as the overall truth value can be determined.  Octave's "short-circuit"
  1353. boolean operators work this way.
  1354.  
  1355. `BOOLEAN1 && BOOLEAN2'
  1356.      The expression BOOLEAN1 is evaluated and converted to a scalar
  1357.      using the equivalent of the operation `all (all (BOOLEAN1))'.  If
  1358.      it is false, the result of the overall expression is 0.  If it is
  1359.      true, the expression BOOLEAN2 is evaluated and converted to a
  1360.      scalar using the equivalent of the operation `all (all
  1361.      (BOOLEAN1))'.  If it is true, the result of the overall expression
  1362.      is 1.  Otherwise, the result of the overall expression is 0.
  1363.  
  1364. `BOOLEAN1 || BOOLEAN2'
  1365.      The expression BOOLEAN1 is evaluated and converted to a scalar
  1366.      using the equivalent of the operation `all (all (BOOLEAN1))'.  If
  1367.      it is true, the result of the overall expression is 1.  If it is
  1368.      false, the expression BOOLEAN2 is evaluated and converted to a
  1369.      scalar using the equivalent of the operation `all (all
  1370.      (BOOLEAN1))'.  If it is true, the result of the overall expression
  1371.      is 1.  Otherwise, the result of the overall expression is 0.
  1372.  
  1373.    The fact that both operands may not be evaluated before determining
  1374. the overall truth value of the expression can be important.  For
  1375. example, in the expression
  1376.  
  1377.      a && b++
  1378.  
  1379. the value of the variable B is only incremented if the variable A is
  1380. nonzero.
  1381.  
  1382.    This can be used to write somewhat more concise code.  For example,
  1383. it is possible write
  1384.  
  1385.      function f (a, b, c)
  1386.        if (nargin > 2 && isstr (c))
  1387.          ...
  1388.  
  1389. instead of having to use two `if' statements to avoid attempting to
  1390. evaluate an argument that doesn't exist.  For example, without the
  1391. short-circuit feature, it would be necessary to write
  1392.  
  1393.      function f (a, b, c)
  1394.        if (nargin > 2)
  1395.          if (isstr (c))
  1396.            ...
  1397.  
  1398.    Writing
  1399.  
  1400.      function f (a, b, c)
  1401.        if (nargin > 2 & isstr (c))
  1402.          ...
  1403.  
  1404. would result in an error if `f' were called with one or two arguments
  1405. because Octave would be forced to try to evaluate both of the operands
  1406. for the operator `&'.
  1407.  
  1408. 
  1409. File: octave,  Node: Assignment Ops,  Next: Increment Ops,  Prev: Boolean Expressions,  Up: Expressions
  1410.  
  1411. Assignment Expressions
  1412. ======================
  1413.  
  1414.    An "assignment" is an expression that stores a new value into a
  1415. variable.  For example, the following expression assigns the value 1 to
  1416. the variable `z':
  1417.  
  1418.      z = 1
  1419.  
  1420.    After this expression is executed, the variable `z' has the value 1.
  1421. Whatever old value `z' had before the assignment is forgotten.  The `='
  1422. sign is called an "assignment operator".
  1423.  
  1424.    Assignments can store string values also.  For example, the following
  1425. expression would store the value `"this food is good"' in the variable
  1426. `message':
  1427.  
  1428.      thing = "food"
  1429.      predicate = "good"
  1430.      message = [ "this " , thing , " is " , predicate ]
  1431.  
  1432. (This also illustrates concatenation of strings.)
  1433.  
  1434.    Most operators (addition, concatenation, and so on) have no effect
  1435. except to compute a value.  If you ignore the value, you might as well
  1436. not use the operator.  An assignment operator is different.  It does
  1437. produce a value, but even if you ignore the value, the assignment still
  1438. makes itself felt through the alteration of the variable.  We call this
  1439. a "side effect".
  1440.  
  1441.    The left-hand operand of an assignment need not be a variable (*note
  1442. Variables::.).  It can also be an element of a matrix (*note Index
  1443. Expressions::.) or a list of return values (*note Calling
  1444. Functions::.).  These are all called "lvalues", which means they can
  1445. appear on the left-hand side of an assignment operator.  The right-hand
  1446. operand may be any expression.  It produces the new value which the
  1447. assignment stores in the specified variable, matrix element, or list of
  1448. return values.
  1449.  
  1450.    It is important to note that variables do *not* have permanent types.
  1451. The type of a variable is simply the type of whatever value it happens
  1452. to hold at the moment.  In the following program fragment, the variable
  1453. `foo' has a numeric value at first, and a string value later on:
  1454.  
  1455.      octave:13> foo = 1
  1456.      foo = 1
  1457.      octave:13> foo = "bar"
  1458.      foo = bar
  1459.  
  1460. When the second assignment gives `foo' a string value, the fact that it
  1461. previously had a numeric value is forgotten.
  1462.  
  1463.    Assignment of a scalar to an indexed matrix sets all of the elements
  1464. that are referenced by the indices to the scalar value.  For example, if
  1465. `a' is a matrix with at least two columns,
  1466.  
  1467.      a(:, 2) = 5
  1468.  
  1469. sets all the elements in the second column of `a' to 5.
  1470.  
  1471.    Assigning an empty matrix `[]' works in most cases to allow you to
  1472. delete rows or columns of matrices and vectors.  *Note Empty Matrices::.
  1473. For example, given a 4 by 5 matrix A, the assignment
  1474.  
  1475.      A (3, :) = []
  1476.  
  1477. deletes the third row of A, and the assignment
  1478.  
  1479.      A (:, 1:2:5) = []
  1480.  
  1481. deletes the first, third, and fifth columns.
  1482.  
  1483.    An assignment is an expression, so it has a value.  Thus, `z = 1' as
  1484. an expression has the value 1.  One consequence of this is that you can
  1485. write multiple assignments together:
  1486.  
  1487.      x = y = z = 0
  1488.  
  1489. stores the value 0 in all three variables.  It does this because the
  1490. value of `z = 0', which is 0, is stored into `y', and then the value of
  1491. `y = z = 0', which is 0, is stored into `x'.
  1492.  
  1493.    This is also true of assignments to lists of values, so the
  1494. following is a valid expression
  1495.  
  1496.      [a, b, c] = [u, s, v] = svd (a)
  1497.  
  1498. that is exactly equivalent to
  1499.  
  1500.      [u, s, v] = svd (a)
  1501.      a = u
  1502.      b = s
  1503.      c = v
  1504.  
  1505.    In expressions like this, the number of values in each part of the
  1506. expression need not match.  For example, the expression
  1507.  
  1508.      [a, b, c, d] = [u, s, v] = svd (a)
  1509.  
  1510. is equivalent to the expression above, except that the value of the
  1511. variable `d' is left unchanged, and the expression
  1512.  
  1513.      [a, b] = [u, s, v] = svd (a)
  1514.  
  1515. is equivalent to
  1516.  
  1517.      [u, s, v] = svd (a)
  1518.      a = u
  1519.      b = s
  1520.  
  1521.    You can use an assignment anywhere an expression is called for.  For
  1522. example, it is valid to write `x != (y = 1)' to set `y' to 1 and then
  1523. test whether `x' equals 1.  But this style tends to make programs hard
  1524. to read.  Except in a one-shot program, you should rewrite it to get
  1525. rid of such nesting of assignments.  This is never very hard.
  1526.  
  1527. 
  1528. File: octave,  Node: Increment Ops,  Next: Operator Precedence,  Prev: Assignment Ops,  Up: Expressions
  1529.  
  1530. Increment Operators
  1531. ===================
  1532.  
  1533.    *Increment operators* increase or decrease the value of a variable
  1534. by 1.  The operator to increment a variable is written as `++'.  It may
  1535. be used to increment a variable either before or after taking its value.
  1536.  
  1537.    For example, to pre-increment the variable X, you would write `++X'.
  1538. This would add one to X and then return the new value of X as the
  1539. result of the expression.  It is exactly the same as the expression `X
  1540. = X + 1'.
  1541.  
  1542.    To post-increment a variable X, you would write `X++'.  This adds
  1543. one to the variable X, but returns the value that X had prior to
  1544. incrementing it.  For example, if X is equal to 2, the result of the
  1545. expression `X++' is 2, and the new value of X is 3.
  1546.  
  1547.    For matrix and vector arguments, the increment and decrement
  1548. operators work on each element of the operand.
  1549.  
  1550.    Here is a list of all the increment and decrement expressions.
  1551.  
  1552. `++X'
  1553.      This expression increments the variable X.  The value of the
  1554.      expression is the *new* value of X.  It is equivalent to the
  1555.      expression `X = X + 1'.
  1556.  
  1557. `--X'
  1558.      This expression decrements the variable X.  The value of the
  1559.      expression is the *new* value of X.  It is equivalent to the
  1560.      expression `X = X - 1'.
  1561.  
  1562. `X++'
  1563.      This expression causes the variable X to be incremented.  The
  1564.      value of the expression is the *old* value of X.
  1565.  
  1566. `X--'
  1567.      This expression causes the variable X to be decremented.  The
  1568.      value of the expression is the *old* value of X.
  1569.  
  1570.    It is not currently possible to increment index expressions.  For
  1571. example, you might expect that the expression `V(4)++' would increment
  1572. the fourth element of the vector V, but instead it results in a parse
  1573. error.  This problem may be fixed in a future release of Octave.
  1574.  
  1575. 
  1576. File: octave,  Node: Operator Precedence,  Prev: Increment Ops,  Up: Expressions
  1577.  
  1578. Operator Precedence
  1579. ===================
  1580.  
  1581.    "Operator precedence" determines how operators are grouped, when
  1582. different operators appear close by in one expression.  For example,
  1583. `*' has higher precedence than `+'.  Thus, the expression `a + b * c'
  1584. means to multiply `b' and `c', and then add `a' to the product (i.e.,
  1585. `a + (b * c)').
  1586.  
  1587.    You can overrule the precedence of the operators by using
  1588. parentheses.  You can think of the precedence rules as saying where the
  1589. parentheses are assumed if you do not write parentheses yourself.  In
  1590. fact, it is wise to use parentheses whenever you have an unusual
  1591. combination of operators, because other people who read the program may
  1592. not remember what the precedence is in this case.  You might forget as
  1593. well, and then you too could make a mistake.  Explicit parentheses will
  1594. help prevent any such mistake.
  1595.  
  1596.    When operators of equal precedence are used together, the leftmost
  1597. operator groups first, except for the assignment and exponentiation
  1598. operators, which group in the opposite order.  Thus, the expression `a
  1599. - b + c' groups as `(a - b) + c', but the expression `a = b = c' groups
  1600. as `a = (b = c)'.
  1601.  
  1602.    The precedence of prefix unary operators is important when another
  1603. operator follows the operand.  For example, `-x^2' means `-(x^2)',
  1604. because `-' has lower precedence than `^'.
  1605.  
  1606.    Here is a table of the operators in Octave, in order of increasing
  1607. precedence.
  1608.  
  1609. `statement separators'
  1610.      `;', `,'.
  1611.  
  1612. `assignment'
  1613.      `='.  This operator groups right to left.
  1614.  
  1615. `logical "or" and "and"'
  1616.      `||', `&&'.
  1617.  
  1618. `element-wise "or" and "and"'
  1619.      `|', `&'.
  1620.  
  1621. `relational'
  1622.      `<', `<=', `==', `>=', `>', `!=', `~=', `<>'.
  1623.  
  1624. `colon'
  1625.      `:'.
  1626.  
  1627. `add, subtract'
  1628.      `+', `-'.
  1629.  
  1630. `multiply, divide'
  1631.      `*', `/', `\', `.\', `.*', `./'.
  1632.  
  1633. `transpose'
  1634.      `'', `.''
  1635.  
  1636. `unary plus, minus, increment, decrement, and ``not'''
  1637.      `+', `-', `++', `--', `!', `~'.
  1638.  
  1639. `exponentiation'
  1640.      `^', `**', `.^', `.**'.
  1641.  
  1642.