home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 April / macformat-023.iso / Shareware City / Developers / RLaB / help / LIST < prev    next >
Encoding:
Text File  |  1994-02-21  |  4.6 KB  |  158 lines  |  [TEXT/RLAB]
  1. list:
  2.  
  3.     RLaB LIST objects, or entities, are arrays of other entities.
  4.     You can think of lists as N-dimensional arrays. In their
  5.     simplest form a list is a single dimension array with funny
  6.     indexing syntax. The neat thing about lists is that the index
  7.     does not have to be an integer value. The index can be a
  8.     string, or a scalar. It is OK to use an expression as a list
  9.     index value since RLaB will evaluate it (it had better
  10.     evaluate to a string or scalar).
  11.  
  12.     One advantage of lists is the ability to give array elements
  13.     descriptive names, such as: `a.mass', `m.modes', etc... The
  14.     syntax `a.name' where name is a descriptive string, is
  15.     shorthand for the more complex LIST indexing syntax. The
  16.     formal indexing syntax is:
  17.  
  18.     expr . [ scalar_or_string_expr ]
  19.  
  20.     Where expr is any valid expression that evaluates to a LIST,
  21.     scalar_or_string_expr is any valid expression that evaluates
  22.     to a scalar or string.
  23.  
  24.     To use a list, or assign to members of the list you can create
  25.     it first...  
  26.  
  27.     list = <<>>
  28.  
  29.     This will create an empty list. Or, you can create and load
  30.     the list at the same time...
  31.  
  32.     list = <<a; b>>
  33.     
  34.     The above will create the list, and COPY the objects a and b
  35.     into the list. The list members will have index values 1 and
  36.     2.
  37.  
  38.     list = <<A=a; B=b>>
  39.  
  40.     The above will create a list, copying the variable a into the
  41.     variable A, and so on. When an assignment occurs inside the
  42.     list creation operators the LHS variable does not appear on
  43.     the global symbol table. The new list has members named `A'
  44.     and `B'.
  45.  
  46.     Like other objects you can just start using the list...
  47.  
  48.     list.a_inv = inv(a);
  49.  
  50.     This will create the list and it's first member. The name of
  51.     the member is `a_inv'. To reference a list member, two methods
  52.     are available.
  53.  
  54.     list.NAME
  55.     list.[ scalar_or_string_expr ]
  56.  
  57.     The first method interprets NAME as a character string, and
  58.     uses the string to index the member. The second method
  59.     converts the result of the scalar or string expression into a
  60.     string and uses that to index the list. Therefore
  61.  
  62.     list.[2.5]
  63.     x = 2.5; list.[x]
  64.     list.[1.5 + sqrt(1)]
  65.  
  66.     are equivalent.
  67.  
  68.     list.matrix
  69.     list.["matrix"]
  70.  
  71.     are also equivalent.
  72.  
  73.     A nice thing about lists is that they only contain objects
  74.     that are explicitly installed, regardless of the index values.
  75.     For instance, a list with index values of "1" and "100" will
  76.     only contains two items, the elements for the "1" and "100"
  77.     indices, no more. Furthermore, lists can be more efficient
  78.     than appending rows or columns onto matrices, since the memory
  79.     management overhead is less.
  80.  
  81.     Lists can also be a convenient way to have an array that
  82.     indexes from zero. This may not be as efficient as using a
  83.     matrix, but if the problem is expressed more clearly then a
  84.     list may be appropriate.
  85.  
  86.     The built-in function members() returns a matrix of the
  87.     argument's indices. This can be useful when a function
  88.     encounters a LIST, but doesn't know the member names.
  89.  
  90.     Example:
  91.  
  92.     > xlist = << Mass = sqrt(200); Inertia = eye(3,3); xdot = [1,2,3] >>
  93.        Inertia      Mass         xdot         
  94.     > for( i in members(xlist) )
  95.       {
  96.         xlist.[i]
  97.       }
  98.      Inertia =
  99.      matrix columns 1 thru 3
  100.                1           0           0
  101.                0           1           0
  102.                0           0           1
  103.      Mass =
  104.            14.14
  105.      xdot =
  106.      matrix columns 1 thru 3
  107.            1           2           3
  108.  
  109.     ----------------------------------------------------------------
  110.  
  111.     The Rlab symbol-table is a list. It can be referenced with the
  112.     special symbol `$$'. The symbol-table can be used like other
  113.     lists, with certain exceptions.
  114.  
  115.     1.) The symbol-table cannot be copied.
  116.  
  117.     2.) The symbol table cannot be destroyed.
  118.  
  119.     Why would you want to use `$$' ? Well, you might use it to
  120.     reference a variable with a string. For example:
  121.  
  122.     > printf ("Enter variable name to print: "); a = getline ("stdin");
  123.     Enter variable name to print: eps
  124.     > $$.[a.[1]]
  125.      eps =
  126.      1.11e-16
  127.  
  128.     Another example of `$$' usage can be found in the rfile
  129.     rlib/save.r, or type `help save'.
  130.  
  131.     ----------------------------------------------------------------
  132.  
  133.     When using the list syntax:
  134.  
  135.         list.[ scalar_or_string_expr ]
  136.  
  137.     If scalar_or_string_expr does not evaluate to a string, then
  138.     it is converted to a string with a "%.6g" format ("%.6gi" if
  139.     it is a complex constant"). The same is true whether you are
  140.     assigning to members of a list, or referencing existing list
  141.     members. This may lead to some unexpected results if you use
  142.     floating-point numbers for list indices.
  143.  
  144.     > a.[1.23456] = 13
  145.        1.23456      
  146.     > a.[1.2345]
  147.         UNDEFINED
  148.     > a.[1.23456]
  149.      1.23456 =
  150.            13
  151.     > a.[1.234567]
  152.         UNDEFINED
  153.     > a.[1.234563]
  154.      1.23456 =
  155.            13
  156.  
  157.     ----------------------------------------------------------------
  158.