<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA
 *
 * 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="en" xml:id="colon">
    <refnamediv>
        <refname>colon (:)</refname>
        <refpurpose>Ranging operator. Addresses all elements along an array dimension or of a list.</refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>
            Colon symbol <literal>:</literal> can be used to form implicit
            vectors (see also <link linkend="linspace">linspace</link>,  <link linkend="logspace">logspace</link>) :
        </para>
        <variablelist>
            <varlistentry>
                <term>j:k</term>
                <listitem>
                    <para>
                        is the vector <literal>[j, j+1,...,k]</literal> (empty if
                        <literal>j&gt;k</literal>);
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>j:d:k</term>
                <listitem>
                    <para>
                        is the vector <literal>[j, j+d, ..., j+m*d]  </literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            The colon notation can also be used to pick out selected rows,  columns and elements
            of vectors and other arrays (see also <link linkend="extraction">extraction</link>,
            <link linkend="insertion">insertion</link>):
        </para>
        <variablelist>
            <varlistentry>
                <term>A(:)</term>
                <listitem>
                    <para>
                        is the vector of all the elements of <literal>A</literal>  regarded as a single column;
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>A(:,j)</term>
                <listitem>
                    <para>
                        is the <literal>j</literal>-th column of <literal>A</literal>;
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>A(i,:)</term>
                <listitem>
                    <para>
                        is the <literal>i</literal>-th row of <literal>A</literal>;
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>A(j:k)</term>
                <listitem>
                    <para>
                        is <literal>[A(j),A(j+1),...,A(k)]</literal>;
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>A(:,j:k)</term>
                <listitem>
                    <para>
                        is
                        <programlisting><![CDATA[
              [A(1,j)  A(1,j+1)  ... A(1,k)
              A(2,j)  A(2,j+1)  ... A(2,k)
              . . . . . . . . . . .
              A(M,j)  A(M,j+1)  ... A(M,k)]
             ]]></programlisting>
                        if size of <literal>A</literal> is <literal>M</literal>-by-<literal>N</literal>;
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>A(j:k,:)</term>
                <listitem>
                    <para>is
                        <programlisting><![CDATA[
              [A(j,1)    A(j,2)   ... A(j,N)
              A(j+1,1)  A(j+1,2) ... A(j+1,N)
              . . . . . . . . . . .
              A(k,1)    A(k,2)   ... A(k,N)]
             ]]></programlisting>
                        if size of <literal>A</literal> is <literal>M</literal>-by-<literal>N</literal>;
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>A(:)=w</term>
                <listitem>
                    <para>
                        fills the array <literal>A</literal> with entries of <literal>w</literal>
                        (taken column by column if <literal>w</literal> is a 2D array). The amount of
                        entries of <literal>A</literal> must be equal to the amount of
                        entries of <literal>w</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            Please note that even if <literal>i</literal>, <literal>j</literal>,
            <literal>k</literal> or <literal>d</literal> have a decimal part, only
            the integer part will be used.
        </para>
       <note>
          <literal>type(:)</literal> is 129.
          <literal>typeof(:)</literal> is <literal>"implicitlist"</literal>.
       </note>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting><![CDATA[
a = 1:5
b = 1:3:12
A = matrix(1:42,7,6);
// vector of all the elements of A
A(:)

// the j-th column of A
A(:,j)

// the i-th row of A
A(i,:)

// elements of columns from j to k and all rows
A(:,j:k)

// elements of all columns and rows from j to k
A(j:k,:)

w = matrix(101:142,7,6);
A(:) = w

// if indices are not integer
i = 1:0.4:10; //indices
A(i)

 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="dollar">dollar</link>
            </member>
            <member>
                <link linkend="extraction">extraction</link>
            </member>
            <member>
                <link linkend="matrix">matrix</link>
            </member>
            <member>
                <link linkend="linspace">linspace</link>
            </member>
            <member>
                <link linkend="logspace">logspace</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.0</revnumber>
                <revdescription>
                  <itemizedlist>
                    <listitem>
                        <literal>type(:)</literal> is 129 (as for <literal>1:$</literal>)
                        instead of 1. <literal>size(:)</literal> is undefined
                        (instead of <literal>[-1,-1]</literal>).
                    </listitem>
                    <listitem>
                        <literal>typeof(:)</literal> is now <literal>"implicitlist"</literal>,
                        like <literal>1:$</literal>.
                    </listitem>
                    <listitem>
                        <literal>%i:10</literal> now yields an error.
                    </listitem>
                  </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
