* modulo() and pmodulo() support integers & hypermatrices
[scilab.git] / scilab / modules / elementary_functions / help / en_US / modulo.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * Copyright (C) 2013 - Samuel GOUGEON
6  * 
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="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="modulo" xml:lang="en">
15     <refnamediv>
16         <refname>modulo</refname>
17         <refpurpose>remainder modulo m with the left operand sign</refpurpose>
18     </refnamediv>
19     <refnamediv xml:id="pmodulo">
20         <refname>pmodulo</refname>
21         <refpurpose>positive euclidian remainder modulo m</refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Calling Sequence</title>
25         <synopsis>i = modulo(n,m)</synopsis>
26         <synopsis>i = pmodulo(n,m)</synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>m, n</term>
33                 <listitem>
34                     <para>Scalar, vector, matrix or hypermatrix of encoded integers, reals or polynomials (Hypermatrix is not supported for polynomials). 
35                         <varname>m</varname> and <varname>n</varname> must have the same type. If they are of integer type, they may be of distinct 
36                         encoding length (for instance int8 and int16). If none of them is scalar, they must have the same sizes.
37                     </para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>i</term>
42                 <listitem>
43                     <para>
44                         Scalar, vector, matrix or hypermatrix of same type (and inttype) as <varname>n</varname>.
45                         <varname>i</varname> takes the sizes of the bigger <varname>m</varname> or<varname>n</varname>.
46                     </para>
47                 </listitem>
48             </varlistentry>
49         </variablelist>
50     </refsection>
51     <refsection>
52         <title>Description</title>
53         <para>
54             <function>modulo</function> computes <code>i = n (modulo m)</code>
55             i.e. remainder of <varname>n</varname> divided by <varname>m</varname>.
56         </para>
57         <para>
58             <code>i = n - m .* int (n ./ m)</code>. Here the answer may be negative
59             if <varname>n</varname> or <varname>m</varname> are negative.
60         </para>
61         <para>
62             <function>pmodulo</function> computes <code>i = n - |m| .* floor (n ./ |m|)</code>,
63             the answer is positive or zero.
64         </para>
65         <warning>
66             If <varname>m</varname> contains at least one 0 value, <code>modulo(x,m)</code> and <code>pmodulo(x,m)</code> will perform a division by zero. If <varname>m</varname> is of real type, this exception will be processed according to the <literal>ieee()</literal> mode. For encoded integers, it will always yield an error.
67         </warning>
68     </refsection>
69     <refsection>
70         <title>Examples</title>
71         <programlisting role="example"><![CDATA[ 
72 n = [1,2,10,15];
73 m = [2,2,3,5];
74 modulo(n,m)
75
76 modulo(-3, 9)
77 modulo(10, -4)
78
79 pmodulo(-3, 9)
80 pmodulo(10, -6)
81 pmodulo(-10, -6)
82
83 // Encoded integers
84 modulo( int8(-13), int16(-7))
85 pmodulo(int8(-13), int16(-7))
86 modulo( int8(-13), int16([-7 5]))
87 pmodulo(int8(-13), int16([-7 5]))
88 modulo( int8([-13 8]), int16(-7))
89 pmodulo(int8([-13 8]), int16(-7))
90 modulo( int8([-13 8]), int16([-7 5]))
91 pmodulo(int8([-13 8]), int16([-7 5]))
92
93 // Hypermatrices
94 m = grand(2,2,2,"uin",-100,100)
95 n = grand(2,2,2,"uin",-10 ,10);
96 n(n==0) = 1
97 modulo(m, 5)
98 pmodulo(m,5)
99 modulo(51, n)
100 pmodulo(51,n)
101 modulo(m, n)
102 pmodulo(m,n)
103
104 // Polynomials
105 modulo( %z^2+1, %z)
106 pmodulo(%z^2+1, %z)
107
108
109  ]]></programlisting>
110     </refsection>
111     <refsection role= "see also">
112         <title>See also</title>
113         <simplelist type="inline">
114             <member>
115                 <link linkend="ieee">ieee</link>
116             </member>
117         </simplelist>
118     </refsection>
119     <refsection>
120         <title>History</title>
121         <revhistory>
122             <revision>
123                 <revnumber>5.5.0</revnumber>
124                 <revremark>Extension to encoded integers and to hypermatrices of encoded integers or reals.</revremark>
125             </revision>
126         </revhistory>
127     </refsection>
128     
129 </refentry>