====================================================================
Two Dimensional Array
====================================================================

The TwoDimensionalArray domain is used for storing data in a two
dimensional data structure indexed by row and by column.  Such an
array is a homogeneous data structure in that all the entries of the
array must belong to the same FriCAS domain..  Each array has a fixed
number of rows and columns specified by the user and arrays are not
extensible.  In FriCAS, the indexing of two-dimensional arrays is
one-based.  This means that both the "first" row of an array and the
"first" column of an array are given the index 1.  Thus, the entry
in the upper left corner of an array is in position (1,1).

The operation new creates an array with a specified number of rows and
columns and fills the components of that array with a specified entry.
The arguments of this operation specify the number of rows, the number
of columns, and the entry.

This creates a five-by-four array of integers, all of whose entries are
zero.::

  arr : ARRAY2 INT := new(5,4,0)
        +0  0  0  0+
        |          |
        |0  0  0  0|
        |          |
        |0  0  0  0|
        |          |
        |0  0  0  0|
        |          |
        +0  0  0  0+
                         Type: TwoDimensionalArray Integer

The entries of this array can be set to other integers using setelt.

Issue this to set the element in the upper left corner of this array to 17. ::

  setelt(arr,1,1,17)
    17
                         Type: PositiveInteger

Now the first element of the array is 17. ::

  arr
        +17  0  0  0+
        |           |
        |0   0  0  0|
        |           |
        |0   0  0  0|
        |           |
        |0   0  0  0|
        |           |
        +0   0  0  0+
                         Type: TwoDimensionalArray Integer

Likewise, elements of an array are extracted using the operation elt. ::

  elt(arr,1,1)
    17
                         Type: PositiveInteger

Another way to use these two operations is as follows.  This sets the
element in position (3,2) of the array to 15. ::

  arr(3,2) := 15
    15
                         Type: PositiveInteger

This extracts the element in position (3,2) of the array. ::

  arr(3,2)
    15
                         Type: PositiveInteger

The operations elt and setelt come equipped with an error check which
verifies that the indices are in the proper ranges.  For example, the
above array has five rows and four columns, so if you ask for the
entry in position (6,2) with arr(6,2) FriCAS displays an error message.
If there is no need for an error check, you can call the operations qelt 
and qsetelt which provide the same functionality but without the error 
check. Typically, these operations are called in well-tested programs.

The operations row and column extract rows and columns, respectively,
and return objects of OneDimensionalArray with the same underlying
element type. ::

  row(arr,1)
    [17,0,0,0]
                         Type: OneDimensionalArray Integer

  column(arr,1)
    [17,0,0,0,0]
                         Type: OneDimensionalArray Integer

You can determine the dimensions of an array by calling the operations
nrows and ncols, which return the number of rows and columns, respectively. ::

  nrows(arr)
    5
                         Type: PositiveInteger

  ncols(arr)
    4
                         Type: PositiveInteger

To apply an operation to every element of an array, use map.  This
creates a new array.  This expression negates every element. ::

  map(-,arr)
         +- 17   0    0  0+
         |                |
         | 0     0    0  0|
         |                |
         | 0    - 15  0  0|
         |                |
         | 0     0    0  0|
         |                |
         + 0     0    0  0+
                         Type: TwoDimensionalArray Integer

This creates an array where all the elements are doubled. ::

  map((x +-> x + x),arr)
         +34  0   0  0+
         |            |
         |0   0   0  0|
         |            |
         |0   30  0  0|
         |            |
         |0   0   0  0|
         |            |
         +0   0   0  0+
                         Type: TwoDimensionalArray Integer

To change the array destructively, use map instead of map.  If you
need to make a copy of any array, use copy. ::

  arrc := copy(arr)
         +17  0   0  0+
         |            |
         |0   0   0  0|
         |            |
         |0   15  0  0|
         |            |
         |0   0   0  0|
         |            |
         +0   0   0  0+
                         Type: TwoDimensionalArray Integer

  map!(-,arrc)
         +- 17   0    0  0+
         |                |
         | 0     0    0  0|
         |                |
         | 0    - 15  0  0|
         |                |
         | 0     0    0  0|
         |                |
         + 0     0    0  0+
                         Type: TwoDimensionalArray Integer

  arrc
         +- 17   0    0  0+
         |                |
         | 0     0    0  0|
         |                |
         | 0    - 15  0  0|
         |                |
         | 0     0    0  0|
         |                |
         + 0     0    0  0+
                         Type: TwoDimensionalArray Integer

  arr
         +17  0   0  0+
         |            |
         |0   0   0  0|
         |            |
         |0   15  0  0|
         |            |
         |0   0   0  0|
         |            |
         +0   0   0  0+
                         Type: TwoDimensionalArray Integer

Use member? to see if a given element is in an array. ::

  member?(17,arr)
    true
                         Type: Boolean

  member?(10317,arr)
    false
                         Type: Boolean

To see how many times an element appears in an array, use count. ::

  count(17,arr)
    1
                         Type: PositiveInteger

  count(0,arr)
    18
                         Type: PositiveInteger

See Also:

* )help Matrix
* )help OneDimensionalArray
* )show TwoDimensionalArray