scilab/modules/elementary_functions/help/en_US/bitwise/bitand.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) 2016 - Samuel GOUGEON
   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"
  18 xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
  19 xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
  20 xmlns:scilab="http://www.scilab.org" xml:id="bitand" xml:lang="en">
  21     <refnamediv>
  22         <refname>bitand</refname>
  23         <refpurpose>bitwise logical AND between element-wise integers of 2 arrays</refpurpose>
  24     </refnamediv>
  25     <refsynopsisdiv>
  26         <title>Syntax</title>
  27         <synopsis>
  28             w = bitand(u, v)
  29         </synopsis>
  30     </refsynopsisdiv>
  31     <refsection>
  32         <title>Parameters</title>
  33         <variablelist>
  34             <varlistentry>
  35                 <term>u, v, w</term>
  36                 <listitem>
  37                     <para>
  38                         scalars, vectors, matrices or hypermatrices of null or
  39                         positive integers encoded as decimal or integer numbers
  40                         of any signed or unsigned <link linkend="inttype">inttype</link>.
  41                         <warning>Sparse-encoded matrices are not accepted.</warning>
  42                     </para>
  43                     <para>
  44                         If <literal>u</literal> and <literal>v</literal> have
  45                         the same type and inttype, this one is the working one.
  46                         Otherwise,
  47                         <itemizedlist>
  48                             <listitem>
  49                                 if <literal>u</literal> or <literal>v</literal>
  50                                 is decimal-encoded, the working inttype is 0
  51                                 (real decimal), even if the other operand
  52                                 is int64- or uint64-encoded.
  53                             </listitem>
  54                             <listitem>
  55                                 if <literal>u</literal> and <literal>v</literal>
  56                                 are both encoded integers, the working inttype
  57                                 is the widest of both: int8 &lt; uint8 &lt;
  58                                 int16 &lt; uint16 &lt; int32 &lt; uint32 &lt;
  59                                 int64 &lt; uint64.
  60                             </listitem>
  61                         </itemizedlist>
  62                     </para>
  63                     <para>
  64                         The result <literal>w</literal> gets the type of the
  65                         working encoding.
  66                     </para>
  67                     <para>
  68                         <literal>u</literal> and <literal>v</literal> are
  69                         processed element-wise.
  70                         <itemizedlist>
  71                             <listitem>
  72                                 If <literal>u</literal> is a single value (scalar)
  73                                 and <literal>v</literal> is a vector, matrix or
  74                                 hypermatrix, <literal>u</literal> is priorly
  75                                 expanded as <literal>u*ones(v)</literal> in order
  76                                 to operate <literal>u</literal> with every
  77                                 <literal>v</literal> component.
  78                             </listitem>
  79                             <listitem>
  80                                 Conversely, <literal>v</literal> is priorly
  81                                 expanded as <literal>v*ones(u)</literal> if it
  82                                 is a single value.
  83                             </listitem>
  84                             <listitem>
  85                                 If neither <literal>u</literal> nor <literal>v</literal>
  86                                 are scalars, they must have the same sizes.
  87                             </listitem>
  88                         </itemizedlist>
  89                     </para>
  90                     <para>
  91                         The result <literal>w</literal> gets the sizes of
  92                         <literal>u</literal> or/and <literal>v</literal>
  93                         arrays.
  94                     </para>
  95                 </listitem>
  96             </varlistentry>
  97         </variablelist>
  98     </refsection>
  99     <refsection>
 100         <title>Description</title>
 101         For each pair of components <literal>u(i)</literal> and <literal>v(i)</literal>,
 102         <literal>bitand(u, v)</literal> computes and returns in <literal>w(i)</literal>
 103         the bitwise AND conjunction of <literal>u(i)</literal> and <literal>v(i)</literal>
 104         bits: Bits of <literal>w(i)</literal> set to 1 are met
 105         in <literal>u(i)</literal> AND in <literal>v(i)</literal>. Otherwise,
 106         they are set to 0.
 107         <note>
 108             With encoded integers, <literal>bitand(u, v)</literal> is equivalent
 109             to <literal>u &amp; v</literal>. However, <literal>u &amp; v</literal>
 110             demands that <literal>u</literal> and <literal>v</literal> have
 111             the same inttype, while <literal>bitand(..)</literal> accepts
 112             mixed operands.
 113         </note>
 114         <note>
 115             For any decimal integer <literal>u</literal> greater than 2^52,
 116             only its bits from log2(u) down to log2(u)-52 are encoded and can
 117             be actually taken into account. Lower bits are not stored and are
 118             then ignored.
 119         </note>
 120     </refsection>
 121     <refsection>
 122         <title>Examples</title>
 123         <programlisting role="example"><![CDATA[
 124 bitand(54, 107)
 125 dec2bin([54 107 34]')  // binary representations
 126      ]]></programlisting>
 127         <screen><![CDATA[--> bitand(54, 107)
 128  ans  =
 129    34.
 130
 131 --> dec2bin([54 107 34]')
 132  ans  =
 133 !0110110  !
 134 !1101011  !
 135 !0100010  !
 136 ]]></screen>
 137         <para></para>
 138         <programlisting role="example"><![CDATA[
 139 // Between 2 simple rows with zeros and ones
 140 u = [0 1 0 1];
 141 v = [0 0 1 1];
 142 bitand(u, v)    // [0 0 0 1] expected
 143
 144 // Encoded integers such as int8 are accepted:
 145 u = int8([0 1 0 1]);
 146 v = int8([0 0 1 1]);
 147 bitand(u, v)
 148
 149 // Operands of mixed types are accepted.
 150 // The type of the result is decimal if a decimal operand is involved,
 151 // or the widest integer one otherwise:
 152 u = [0 1 0 1];
 153 v = [0 0 1 1];
 154 z = bitand(u, int64(v));         type(z)      // 1 : decimal representation
 155 z = bitand(uint8(u), int8(v));   typeof(z)    // uint8
 156 z = bitand(uint8(u), int32(v));  typeof(z)    // int32
 157
 158 // Usage with 2 matrices
 159 u = [  0  1   0   1
 160       54 107 107 54 ];
 161 v = [  0  0   1   1
 162       107 54 34  34 ];
 163 bitand(u, v)     //  [ 0 0 0 1 ;  34 34 34 34 ]   expected
 164
 165 // Usage with a distributed scalar:
 166 bitand([1 2 4 8 9 10 12], 8)  // == bitand([1 2 4 8 9 10 12], [8 8 8 8 8 8 8])
 167 bitand(4, [1 2 4 8 9 10 12])  // == bitand([4 4 4 4 4 4 4], [1 2 4 8 9 10 12])
 168    ]]></programlisting>
 169         <para></para>
 170         <programlisting role="example"><![CDATA[
 171 // With encoded integers, bitand(u,v) and u & v are equivalent:
 172 u = int8([2 3 10]);
 173 v = int8(13);
 174 [bitand(u, v) ; u &amp; v]
 175 // ... but "&" demands operands having the same type:
 176 u &amp; 13    // mismatching int8- | decimal- encodings
 177    ]]></programlisting>
 178         <screen><![CDATA[--> u = int8([2 3 10]);
 179 --> v = int8(13);
 180 --> [bitand(u, v) ; u &amp; v]
 181  ans  =
 182   0  1  8
 183   0  1  8
 184 --> u &amp; 13
 185 Undefined operation for the given operands.
 186 check or define function %i_h_s for overloading.
 187 ]]></screen>
 188         <para></para>
 189         <programlisting role="example"><![CDATA[
 190 // Examples with big decimal integers:
 191
 192 u = sum(2 .^(600+[0 3 9 20 45]))        // ~ 1.46D+194
 193 bitand(u, 2^601) == 0    // True: The bit #601 is set to 0 in u
 194 v = 2 .^[603 610];
 195 bitand(u, v) == 2^603    // True: the bit #603 is the only one common to u and v
 196 bitand(u, 2^646-1) == 0  // True: 2^646-1 has theoretically bits #1 to #645 set to 1
 197                          // BUT -1/(2^646) is <<< %eps and is then ignored:
 198                          // 2^646 is actually used instead of 2^646-1.
 199                          // Now, 2^646 has bits #1 to #645set to 0. So the result.
 200 bitand(u, 2^646-2^599)==u  // %T: 2^646-2^599 has actually bits #599 to #645 set to 1
 201 //
 202 n = fix(log2(u))       // == 645: Index of the heaviest bit of u
 203 bitand(u, u+2^(n-53)) == u   // True: Addressing bits below the lightest one has no effect
 204 bitand(u, u-2^(n-53)) == u   // True: idem
 205    ]]></programlisting>
 206     </refsection>
 207     <refsection role="see also">
 208         <title>See also</title>
 209         <simplelist type="inline">
 210             <member>
 211                 <link linkend="and_op">&amp;</link>
 212             </member>
 213             <member>
 214                 <link linkend="and">and</link>
 215             </member>
 216             <member>
 217                 <link linkend="bitor">bitor</link>
 218             </member>
 219             <member>
 220                 <link linkend="dec2bin">dec2bin</link>
 221             </member>
 222         </simplelist>
 223     </refsection>
 224     <refsection role="history">
 225         <title>History</title>
 226         <revhistory>
 227             <revision>
 228                 <revnumber>6.0</revnumber>
 229                 <revdescription>
 230                     <itemizedlist>
 231                         <listitem>
 232                             Extension to positive signed encoded integers
 233                         </listitem>
 234                         <listitem>
 235                             Extension to new int64 and uint64 inttypes
 236                         </listitem>
 237                         <listitem>
 238                             Operands of mixed types or inttypes are now accepted.
 239                         </listitem>
 240                         <listitem>
 241                             bitand(scalar, array) and bitand(array, scalar) are now supported.
 242                         </listitem>
 243                         <listitem>
 244                             Extension to decimal numbers greater than
 245                             2^32 and even than 2^52,
 246                             up to 1.80D+308 (== number_properties("huge")), for
 247                             the 52 heaviest encoded bits of their unsigned mantissa.
 248                         </listitem>
 249                     </itemizedlist>
 250                 </revdescription>
 251             </revision>
 252         </revhistory>
 253     </refsection>
 254 </refentry>