bitor bitxor bitand upgraded. Help pages rewritten. Bug #14654 fixed
[scilab.git] / scilab / modules / elementary_functions / help / en_US / bitwise / bitor.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="bitor" xml:lang="en">
21     <refnamediv>
22         <refname>bitor</refname>
23         <refpurpose>bitwise logical OR between element-wise integers of 2 arrays</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             w = bitor(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                         <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>bitor(u, v)</literal> computes and returns in <literal>w(i)</literal>
103         the bitwise OR conjunction of <literal>u(i)</literal> and <literal>v(i)</literal>
104         bits.
105         <note>
106             With encoded integers, <literal>bitor(u, v)</literal> is equivalent
107             to <literal>u | v</literal>. However, <literal>u | v</literal>
108             demands that <literal>u</literal> and <literal>v</literal> have
109             the same inttype, while <literal>bitor(..)</literal> accepts
110             mixed operands.
111         </note>
112         <note>
113             For any decimal integer <literal>u</literal> greater than 2^52,
114             only its bits from log2(u) down to log2(u)-52 are encoded and can
115             be actually taken into account. Lower bits are not stored and are
116             then ignored.
117         </note>
118     </refsection>
119     <refsection>
120         <title>Examples</title>
121         <programlisting role="example"><![CDATA[
122 bitor(25, 33)
123 dec2bin([25 33 57]')  // binary representations
124      ]]></programlisting>
125         <screen><![CDATA[--> bitor(25, 33)
126  ans  =
127    57.
128
129 --> dec2bin([25 33 57]'))
130  ans  =
131 !011001  !
132 !100001  !
133 !111001  !
134 ]]></screen>
135         <para></para>
136         <programlisting role="example"><![CDATA[
137 // Between 2 simple rows with zeros and ones
138 u = [0 1 0 1];
139 v = [0 0 1 1];
140 bitor(u, v)  // [0 1 1 1] expected
141
142 // Encoded integers such as int8 are accepted:
143 u = int8([0 1 0 1]);
144 v = int8([0 0 1 1]);
145 bitor(u, v)
146
147 // Operands of mixed types are accepted.
148 // The type of the result is decimal if a decimal operand is involved,
149 // or the widest integer one otherwise:
150 u = [0 1 0 1];
151 v = [0 0 1 1];
152 z = bitor(u, int64(v));         type(z)       // 1 : decimal representation
153 z = bitor(uint8(u), int8(v));   typeof(z)     // uint8
154 z = bitor(uint8(u), int32(v));  typeof(z)     // int32
155
156 // Usage with 2 matrices
157 u = [  1  2  4  8
158       25 33 25 33 ];
159 v = [  2  4  8 16
160       33 25 57 57 ];
161 bitor(u, v)      //  [ 3 6 12 24 ;  57 57 57 57 ]   expected
162
163 // Usage with a distributed scalar:
164 bitor([1 2 4 8 9 10 12], 8)  // == bitor([1 2 4 8 9 10 12], [8 8 8 8 8 8 8])
165 bitor(4, [1 2 4 8 9 10 12])  // == bitor([4 4 4 4 4 4 4], [1 2 4 8 9 10 12])
166     ]]></programlisting>
167         <para></para>
168         <programlisting role="example"><![CDATA[
169 // With encoded integers, bitor(u,v) and u|v are equivalent:
170 u = int8([2 3 10]);
171 v = int8(6);
172 [bitor(u, v) ; u | v]
173 // ... but "|" demands operands with the same type:
174 u | 6    // mismatching int8- | decimal- encodings
175    ]]></programlisting>
176         <screen><![CDATA[--> u = int8([2 3 10]);
177 --> v = int8(6);
178 --> [bitor(u, v) ; u | v]
179  ans  =
180   6  7  14
181   6  7  14
182 --> u | 6
183 Undefined operation for the given operands.
184 check or define function %i_g_s for overloading.
185 ]]></screen>
186         <para></para>
187         <programlisting role="example"><![CDATA[
188 // Examples with big decimal integers:
189
190 u = sum(2 .^(600+[0 3 9 20 45]))        // ~ 1.46D+194
191 v = 2^630                               // ~ 4.46D+189
192 w = bitor(u, v)
193 w == (u+v)  // must be true, since u is built without the bit #630
194 bitor(u, 2^645) == u   // true, since u has already its bit #645 set to 1
195 bitor(u, 2^601) == u   // false
196 //
197 n = fix(log2(u))       // Index of the heaviest bit of u
198 bitor(u, 2^(n-52)) == u   // false: The lightest bit of u was at 0 => This changes it
199 bitor(u, 2^(n-53)) == u   // true: Addressing bits below the lightest doesn't change u
200    ]]></programlisting>
201     </refsection>
202     <refsection role="see also">
203         <title>See also</title>
204         <simplelist type="inline">
205             <member>
206                 <link linkend="or_op">|</link>
207             </member>
208             <member>
209                 <link linkend="or">or</link>
210             </member>
211             <member>
212                 <link linkend="bitxor">bitxor</link>
213             </member>
214             <member>
215                 <link linkend="bitand">bitand</link>
216             </member>
217             <member>
218                 <link linkend="dec2bin">dec2bin</link>
219             </member>
220         </simplelist>
221     </refsection>
222     <refsection role="history">
223         <title>History</title>
224         <revhistory>
225             <revision>
226                 <revnumber>6.0</revnumber>
227                 <revdescription>
228                     <itemizedlist>
229                         <listitem>
230                             Extension to positive signed encoded integers
231                         </listitem>
232                         <listitem>
233                             Extension to new int64 and uint64 inttypes
234                         </listitem>
235                         <listitem>
236                             Operands of mixed types or inttypes are now accepted.
237                         </listitem>
238                         <listitem>
239                             bitor(scalar, array) and bitor(array, scalar) are now supported.
240                         </listitem>
241                         <listitem>
242                             Extension to decimal numbers greater than
243                             2^32 and even than 2^52,
244                             up to 1.80D+308 (== number_properties("huge")), for
245                             the 52 heaviest encoded bits of their unsigned mantissa.
246                         </listitem>
247                     </itemizedlist>
248                 </revdescription>
249             </revision>
250         </revhistory>
251     </refsection>
252 </refentry>