[dynamic_link] fix ilib_gen_Make_unix regression after fb164e7
[scilab.git] / scilab / modules / elementary_functions / help / en_US / bitwise / bitcmp.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  *
4  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
5  * Copyright (C) 2011 - DIGITEO - Michael Baudin
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <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">
18     <refnamediv>
19         <refname>bitcmp</refname>
20         <refpurpose>bitwise complement</refpurpose>
21     </refnamediv>
22     <refsynopsisdiv>
23         <title>Syntax</title>
24         <synopsis>
25             y = bitcmp(x)
26             y = bitcmp(x, bitnum)
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Parameters</title>
31         <variablelist>
32             <varlistentry>
33                 <term>x :</term>
34                 <listitem>
35                     <para>
36                         a <literal>m</literal>-by-<literal>n</literal> matrix of doubles
37                         or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of doubles
38                         or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers (<literal>uint8</literal>, <literal>uint16</literal> or <literal>uint32</literal>).
39                         Must contain positive integer values.
40                     </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>bitnum :</term>
45                 <listitem>
46                     <para>
47                         a <literal>m</literal>-by-<literal>n</literal> matrix of doubles
48                         or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of doubles
49                         or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers (<literal>uint8</literal>, <literal>uint16</literal> or <literal>uint32</literal>).
50                         The input <literal>n</literal> must be in the range 1, 2, ..., <literal>bitmax</literal>
51                         where <literal>bitmax</literal> is the maximum number of bits in <varname>x</varname>.
52                         <varname>bitnum</varname> must contain positive integer values. The default value for <varname>bitnum</varname> is <literal>bitmax</literal>.
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>y :</term>
58                 <listitem>
59                     <para>
60                         a <literal>m</literal>-by-<literal>n</literal> matrix of doubles
61                         or a <literal>m1</literal>-by-<literal>m2</literal>-by-...-by-<literal>mm</literal> hypermatrix of  doubles
62                         or a <literal>m</literal>-by-<literal>n</literal> matrix of unsigned integers.
63                     </para>
64                 </listitem>
65             </varlistentry>
66         </variablelist>
67     </refsection>
68     <refsection>
69         <title>Description</title>
70         <para>
71             Given an unsigned integer <varname>x</varname>, this function returns the unsigned integer <varname>y</varname>
72             which is the integer corresponding to the complementary of the binary
73             form of <varname>x</varname>.
74         </para>
75         <para>
76             The integer <varname>bitnum</varname> sets the maximum number of bits.
77         </para>
78         <para>
79             If the bits number of the <varname>x</varname> binary representation is less than the
80             <literal>bitmax</literal> number (8,16 or 32) then the bits <literal>'1'</literal> are added to the
81             complementary in order to have <literal>bitmax</literal> number (8, 16 or 32) for the
82             complementary.
83         </para>
84         <para>
85             If only one input argument is given, <varname>x</varname> must be a matrix of unsigned integers.
86         </para>
87     </refsection>
88     <refsection>
89         <title>Examples</title>
90         <programlisting role="example"><![CDATA[
91 // 13 is (1101)_2
92 // We insert zeros in the beginning to get a 8-bit number:
93 // (00001101)_2
94 // The 8-bits complement is then (11110010)_2
95 // which is 242
96 bitcmp(13,8)
97 expected = 242
98
99 // The input argument can be an unsigned int
100 bitcmp(uint8(99),8)
101 expected = 156
102    ]]></programlisting>
103     </refsection>
104 </refentry>