.. highlightlang:: us

.. _uniscript-r2011:

UniScript R2011
===============

Modifications to UniScript.

* A matrix stored in an object can be accessed in the same manner as a matrix
  stored in a variable. It is not necessary anymore to save a copy of the matrix
  in a variable before accessing the elements.
* The usage of variant matrices has been simplified. During access of elements
  a type conversion will be executed. A variant matrix can now contain UniScript 
  objects. Four new functions have been added for variant matrices:
  :ref:`vmatrix`, :ref:`vconvert`, :ref:`vtype`, :ref:`vcast`.
* Arrays and matrices of COM objects now using variant matrices.
* Copy-on-write (COW) optimization.
 

Matrices in UniScript Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In older UniScript versions a matrix had to be copied into a variable before the 
matrix elements could be accessed. After the modification the matrix was copied 
back into the object

Example (old version)::

  a = [.];
  val = rand(2,2);
  tmp = a.val;
  tmp[1] = 55;
  a.val = tmp;

Example (new version)::

  a = [.];
  a.val = rand(2,2);
  a.val[1] = 55;

Variant Matrices
~~~~~~~~~~~~~~~~

A variant matrix can contain elements with different data types (numbers, strings,
complex numbers, UniScript objects and COM objects).

Example::

  v = vmatrix(5,1)

creates a variant matrix with 5 rows and one column. The elements are numbers
with the value 0.

Each element can contain a value with a different data type::

  v[1] = 123;
  v[2] = "Nm";
  v[3] = 1+2i;
  v[4] = CreateObject("Excel.Application");
  v[5] = [. a = 1:5];

If an element is accessed it will be converted to its base type::

  print type(v[1]) == "real" // returns TRUE (1)
  v[5].b = 1:3 // adds to the object in element 5 the member variable "b".

If a submatrix of a variant matrix is accessed and the elements of the submatrix
have different data types, the submatrix will be a variant matrix::

   v2 = v[1:3]; // v2 is a variant matrix

If all elements of the submatrix have the same data type, a matrix of the base 
type is returned::

   v[2:3] = [11,12];
   a = v[1:3];    // a is real vector with numbers [123, 11, 12]

The colon operator can be used to access all elements. The following assignment
sets all elements of v to the real value 0

::

   v[:] = 0;
   
This assignment will not modify the format and type of the matrix. It will
still be a variant matrix.

The :ref:`vconvert` function can be used to convert a matrix of any type
to a variant matrix.

The :ref:`vtype` function returns the element types of a variant matrix
as a real matrix.

.. list-table::
   :header-rows: 1

   * - Value
     - Description
   * - 0
     - Real-Number
   * - 1
     - String
   * - 2
     - Complex
   * - 4
     - COM-Object-Pointer
   * - 5
     - Pointer to a UniScript object

The :ref:`vcast` function converts a variant matrix to a base type matrix.

Most of the operators cannot be used for variant matrices. 

COM-Objects
~~~~~~~~~~~

So far UniScript could create a matrix of COM objects. Now the elements
are saved in a variant matrix::

   xls = CreateObject("Excel.Application");
   up = CreateObject("UniPlot.Application");

The following assignment creates a variant matrix instead of a matrix of COM 
objects::

   com = [xls, up];

Copy-on-write
~~~~~~~~~~~~~

When a matrix is assigned to a variable, no copying takes place. Only the 
pointer is copied to the variable. As soon as one of the two (or more) matrices
is modified, the matrix will be copied. As data copying only happens when the 
matrix is written to, this is known as COW. The result is a performance gain.

Example::

   a = rand(1000,1000);
   b = a;    // No copy created
   b[1] = 1; // First copy a and than modify element [1]

The following assignment can force the copy::

   b = a;
   b[1] = b[1];

:sub:`id-102742`