<?xml version="1.0" encoding="UTF-8"?>
<!--
 *
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2011 - DIGITEO - Michael Baudin
 *
 * 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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="bitcmp" xml:lang="en">
    <refnamediv>
        <refname>bitcmp</refname>
        <refpurpose>bitwise complement</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            y = bitcmp(x)
            y = bitcmp(x, bitnum)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parameters</title>
        <variablelist>
            <varlistentry>
                <term>x :</term>
                <listitem>
                    <para>
                        a <literal>m</literal>-by-<literal>n</literal> matrix of doubles
                        or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of doubles
                        or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers (<literal>uint8</literal>, <literal>uint16</literal> or <literal>uint32</literal>).
                        Must contain positive integer values.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>bitnum :</term>
                <listitem>
                    <para>
                        a <literal>m</literal>-by-<literal>n</literal> matrix of doubles
                        or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of doubles
                        or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers (<literal>uint8</literal>, <literal>uint16</literal> or <literal>uint32</literal>).
                        The input <literal>n</literal> must be in the range 1, 2, ..., <literal>bitmax</literal>
                        where <literal>bitmax</literal> is the maximum number of bits in <varname>x</varname>.
                        <varname>bitnum</varname> must contain positive integer values. The default value for <varname>bitnum</varname> is <literal>bitmax</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y :</term>
                <listitem>
                    <para>
                        a <literal>m</literal>-by-<literal>n</literal> matrix of doubles
                        or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of  doubles
                        or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Given an unsigned integer <varname>x</varname>, this function returns the unsigned integer <varname>y</varname>
            which is the integer corresponding to the complementary of the binary
            form of <varname>x</varname>.
        </para>
        <para>
            The integer <varname>bitnum</varname> sets the maximum number of bits.
        </para>
        <para>
            If the bits number of the <varname>x</varname> binary representation is less than the
            <literal>bitmax</literal> number (8,16 or 32) then the bits <literal>'1'</literal> are added to the
            complementary in order to have <literal>bitmax</literal> number (8, 16 or 32) for the
            complementary.
        </para>
        <para>
            If only one input argument is given, <varname>x</varname> must be a matrix of unsigned integers.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// 13 is (1101)_2
// We insert zeros in the beginning to get a 8-bit number:
// (00001101)_2
// The 8-bits complement is then (11110010)_2
// which is 242
bitcmp(13,8)
expected = 242

// The input argument can be an unsigned int
bitcmp(uint8(99),8)
expected = 156
   ]]></programlisting>
    </refsection>
</refentry>
