<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * 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="circshift">
    <refnamediv>
        <refname>circshift</refname>
        <refpurpose>
            смещает по кругу элементы матрицы
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Синтаксис</title>
        <synopsis>
            B = circshift(A, shift)
            B = circshift(A, shift, 0)
            B = circshift(A, shifts)
            B = circshift(A, shifts, dims)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Аргументы</title>
        <variablelist>
            <varlistentry>
                <term>A, B</term>
                <listitem>
                    <para>
                        векторы, матрицы, гиперматрицы любого обычного типа данных, структуры,
                        cell-массивы, пользовательских типов. <varname>B</varname> имеет форму,
                        размеры и тип <varname>A</varname>. Пользовательские типы применимы, при
                        условии, что операторы <literal>size()</literal>, вставки и извлечения
                        определены для типа переменной <varname>A</varname>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>shift</term>
                <listitem>
                    <para>
                        уникальное положительное или отрицательное целое: сдвиг для применения к
                        индексам вдоль первого неединичной размерности, или к линейным индексам
                        элементов <varname>A</varname>, если в качестве третьего входного
                        аргумента используется <literal>0</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>shifts</term>
                <listitem>
                    <para>
                        вектор положительных или отрицательных целых чисел: свдиги, которые
                        применяются к диапазонам вдоль направлений, указанных в <varname>dims</varname>
                        (или <literal>1:length(shifts)</literal> по умолчанию).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>dims</term>
                <listitem>
                    <para>
                        вектор целых чисел в диапазоне <literal>[1, ndims(A)]</literal>:
                        указывает размерности <varname>A</varname>, вдоль которых, соответственно,
                        должны применятся сдвиги <literal>shifts</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Описание</title>
        <para>
            <literal>circshift(A, shift)</literal> сдвигает вдоль первой размерности
            <literal>A</literal> размером > 1.
        </para>
        <para>
            <literal>circshift(A, shift, 0)</literal> по кругу сдвигает элементы
            <literal>A</literal> на <varname>shift</varname> позиций.
        </para>
        <para>
            <literal>circshift(A, shifts)</literal> по кругу сдвигает индексы
            строк <literal>A</literal> на <literal>shifts(1)</literal>,
            индексы столбцов <literal>A</literal> на <literal>shifts(2)</literal>,
            индексы слоёв <literal>A</literal> на <literal>shifts(3)</literal> и т.д.
        </para>
        <para>
            <literal>circshift(A, shifts, dims)</literal> по кругу сдвигает <literal>A</literal>
            на <literal>shifts(1)</literal> вдоль её размерности №<literal>dims(1)</literal>,
            на <literal>shifts(2)</literal> вдоль её размерности №<literal>dims(2)</literal> и т.д.
        </para>
    </refsection>
    <refsection>
        <title>Примеры</title>
        <programlisting role="example"><![CDATA[
circshift(1:7, 2)
circshift(1:7, -1)
      ]]></programlisting>
        <screen><![CDATA[
--> circshift(1:7, 2)
 ans  =
   6.   7.   1.   2.   3.   4.   5.

--> circshift(1:7, -1)
 ans  =
   2.   3.   4.   5.   6.   7.   1.
]]></screen>
        <para/>
        <programlisting role="example"><![CDATA[
M = matrix(1:12, 3, 4)
circshift(M, 1)
circshift(M, 1, 2)
circshift(M, [-1 1])
circshift(M, [-2 1], [2 1])
      ]]></programlisting>
        <screen><![CDATA[
--> M = matrix(1:12, 3, 4)
 M  =
   1.   4.   7.   10.
   2.   5.   8.   11.
   3.   6.   9.   12.

--> circshift(M, 1)
 ans  =
   3.   6.   9.   12.
   1.   4.   7.   10.
   2.   5.   8.   11.

--> circshift(M, 1, 2)
 ans  =
   10.   1.   4.   7.
   11.   2.   5.   8.
   12.   3.   6.   9.

--> circshift(M, [-1 1])
 ans  =
   11.   2.   5.   8.
   12.   3.   6.   9.
   10.   1.   4.   7.

--> circshift(M, [-2 1], [2 1])
 ans  =
   9.   12.   3.   6.
   7.   10.   1.   4.
   8.   11.   2.   5.
]]></screen>
        <para/>
        <programlisting role="example"><![CDATA[
M = matrix(1:12, 3, 4)
circshift(M, 5, 0)
      ]]></programlisting>
        <screen><![CDATA[
--> circshift(M, 5, 0)
 ans  =
   8.    11.   2.   5.
   9.    12.   3.   6.
   10.   1.    4.   7.
]]></screen>
        <para>
            <emphasis role="bold">С гиперматрицей текстов:</emphasis>
        </para>
        <programlisting role="example"><![CDATA[
t = matrix([string(1:12) strsplit("a":"l")' strsplit("A":"L")'],3,4,3)
circshift(t, 1, 0)
circshift(t, 1)
circshift(t, 1, 3)
circshift(t, [1 -1], [2 3])
      ]]></programlisting>
        <screen><![CDATA[
--> t = matrix([string(1:12) strsplit("a":"l")' strsplit("A":"L")'],3,4,3)
 t  =
(:,:,1)
!1  4  7  10  !
!2  5  8  11  !
!3  6  9  12  !

(:,:,2)
!a  d  g  j  !
!b  e  h  k  !
!c  f  i  l  !

(:,:,3)
!A  D  G  J  !
!B  E  H  K  !
!C  F  I  L  !

--> circshift(t, 1, 0)
 ans  =
(:,:,1)
!L  3  6  9   !
!1  4  7  10  !
!2  5  8  11  !

(:,:,2)
!12  c  f  i  !
!a   d  g  j  !
!b   e  h  k  !

(:,:,3)
!l  C  F  I  !
!A  D  G  J  !
!B  E  H  K  !

--> circshift(t, 1)
 ans  =
(:,:,1)
!3  6  9  12  !
!1  4  7  10  !
!2  5  8  11  !

(:,:,2)
!c  f  i  l  !
!a  d  g  j  !
!b  e  h  k  !

(:,:,3)
!C  F  I  L  !
!A  D  G  J  !
!B  E  H  K  !

--> circshift(t, 1, 3)
 ans  =
(:,:,1)
!A  D  G  J  !
!B  E  H  K  !
!C  F  I  L  !

(:,:,2)
!1  4  7  10  !
!2  5  8  11  !
!3  6  9  12  !

(:,:,3)
!a  d  g  j  !
!b  e  h  k  !
!c  f  i  l  !

--> circshift(t, [1 -1], [2 3])
 ans  =
(:,:,1)
!j  a  d  g  !
!k  b  e  h  !
!l  c  f  i  !

(:,:,2)
!J  A  D  G  !
!K  B  E  H  !
!L  C  F  I  !

(:,:,3)
!10  1  4  7  !
!11  2  5  8  !
!12  3  6  9  !
]]></screen>
        <para>
            <emphasis role="bold">С cell-массивом:</emphasis>
        </para>
        <programlisting role="example"><![CDATA[
L = list(1,%t);
C = {%f "a" %i  %z
     %t "b" %e  %s
      0 "c" %pi L }
circshift(C, 1, 0)
circshift(C, 1)
circshift(C, 1, 2)
circshift(C, [1 -1])
      ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Смотрите также</title>
        <simplelist type="inline">
            <member>
                <link linkend="flipdim">flipdim</link>
            </member>
            <member>
                <link linkend="fftshift">fftshift</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>История</title>
        <revhistory>
            <revision>
                <revnumber>6.1</revnumber>
                <revremark>
                    Введена <literal>circshift()</literal>.
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
