<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) - INRIA
 * Copyright (C) 2017 - Samuel GOUGEON
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
          xml:lang="ru" xml:id="matrix">
    <refnamediv>
        <refname>matrix</refname>
        <refpurpose>изменение вектора или матрицы в матрицу иных размеров</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Синтаксис</title>
        <synopsis>
            y = matrix(v, m, n)
            y = matrix(v, m1, m2, m3, ..)
            y = matrix(v, [sizes])
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Аргументы</title>
        <variablelist>
            <varlistentry>
                <term>v</term>
                <listitem>
                    <para>вектор, матрица или гиперматрица</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>n, m, m1, m2, ..</term>
                <listitem>
                    <para>целые числа</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>sizes</term>
                <listitem>
                    <para>вектор целых чисел</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y</term>
                <listitem>
                    <para>вектор, матрица или гиперматрица</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Описание</title>
        <para>
            Для вектора или матрицы с элементами <literal>n x m</literal> команда
            <literal>y=matrix(v,n,m)</literal> или аналогичная <literal>y=matrix(v,[n,m])</literal>
            преобразует вектор (или матрицу) <literal>v</literal> в матрицу размерами
            <literal>n x m</literal> постолбцовой установкой элементов <literal>v</literal>.
        </para>
        <para>
            Если один из размеров <literal>m</literal> или <literal>n</literal> равен -1, то он автоматически
            присваивается отношению  <literal>size(v,'*')</literal> к другому размеру.
        </para>
        <para>
            Для гиперматрицы такой, что <literal>prod(size(v))==prod(sizes)</literal> команда
            <literal>y=matrix(v,sizes)</literal> (или аналогичная <literal>y=matrix(v,n1,n2,...nm)</literal>)
            преобразует <literal>v</literal> в матрицу или гиперматрицу постолбцовой установкой
            (первый размер меняется первым) элементов <literal>v</literal>.
            <literal>y=matrix(v,sizes)</literal> даёт обычную матрицу, если размеры являются скалярами или
            двумерным вектором.
        </para>
        <note>
            <itemizedlist>
                <listitem>
                    <literal>y = v(:)</literal> эквивалентно <literal>matrix(v,-1, 1)</literal>
                </listitem>
                <listitem>
                    <literal>matrix()</literal> может быть перегружена для любого типа <literal>mlist()</literal>
                    с функцией, названной <literal>%&lt;type>_matrix(v,s,..)</literal>, с, по крайней мере,
                    двумя входными аргументами.
                </listitem>
            </itemizedlist>
        </note>
    </refsection>
    <refsection>
        <title>Примеры</title>
        <para><emphasis role="bold">С обычной матрицей десятичных чисел:</emphasis></para>
        <programlisting role="example"><![CDATA[
a = [1 3 5 7 9 11; 2 4 6 8 10 12]
matrix(a, 4, 3)
matrix(a, [3 4])
matrix(a, 3, -1)
// в гиперматрицу:
matrix(a, 3, 2, 2)
 ]]></programlisting>
    <para>
        <emphasis role="bold">С текстами:</emphasis>
    </para>
        <programlisting role="example"><![CDATA[
t = strsplit("a":"x",1:23)'
matrix(t,[3,8])
 ]]></programlisting>
    <screen><![CDATA[
--> t = strsplit("a":"x",1:23)'
 t  =
!a  b  c  d  e  f  g  h  i  j  k  l  m  n  o  p  q  r  s  t  u  v  w  x  !

--> matrix(t,[3,8])
 ans  =
!a  d  g  j  m  p  s  v  !
!b  e  h  k  n  q  t  w  !
!c  f  i  l  o  r  u  x  !
]]></screen>
    <para>
        <emphasis role="bold">С гипермассивом cell-элементов:</emphasis>
    </para>
        <programlisting role="example"><![CDATA[
c = makecell([2,3,2], %t,%z, %i,"abc", list(%pi,"a"), int8(23),cos,sind,"àèìòù",corelib, 0.5, 1/%z^2)
rc = matrix(c, 3, 4)
rc(8)==c(8)
rc{8}.getshell
 ]]></programlisting>
    <screen><![CDATA[
 c  =
(:,:,1)
  [1x1 boolean]  [1x1 polynomial]  [1x1 constant]
  [1x1 string ]  [    list      ]  [1x1 int8    ]
(:,:,2)
  [      1 fptr   ]  [      1 function]  [1x1 string]
  [        library]  [    1x1 constant]  [    r     ]

--> rc = matrix(c, 3, 4)
 rc  =
  [1x1 boolean   ]  [    list    ]  [      1 fptr    ]  [1x1 constant]
  [1x1 string    ]  [1x1 constant]  [        library ]  [1x1 string  ]
  [1x1 polynomial]  [1x1 int8    ]  [      1 function]  [    r       ]

--> rc(8)==c(8)
 ans  =
  T

--> rc{8}.getshell
 ans  =
 cmd
]]></screen>
    <para>
        <emphasis role="bold">С массивом структур:</emphasis>
    </para>
        <programlisting role="example"><![CDATA[
clear s
s(3,6).r = %pi
matrix(s,2,9)
 ]]></programlisting>
    <screen><![CDATA[
--> s(3,6).r = %pi
 s  =
  3x6 struct array with fields:
    r

--> matrix(s,2,9)
 ans  =
  2x9 struct array with fields:
    r
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>Смотрите также</title>
        <simplelist type="inline">
            <member>
                <link linkend="colon">двоеточие (:)</link>
            </member>
            <member>
                <link linkend="resize_matrix">resize_matrix</link>
            </member>
            <member>
                <link linkend="ndims">ndims</link>
            </member>
            <member>
                <link linkend="size">size</link>
            </member>
            <member>
                <link linkend="extraction">выделение</link>
            </member>
            <member>
                <link linkend="quote">транспонирование</link>
            </member>
            <member>
                <link linkend="brackets">квадратные скобки [..]</link>
            </member>
            <member>
                <link linkend="matrices">матрицы</link>
            </member>
            <member>
                <link linkend="hypermatrices">гиперматрицы</link>
            </member>
            <member>
                <link linkend="makecell">makecell</link>
            </member>
            <member>
                <link linkend="struct">struct</link>
            </member>
            <member>
                <link linkend="mlist">mlist</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
