* Bug 16148: xmlSetValues() <= setPreferencesValue()
[scilab.git] / scilab / modules / elementary_functions / help / en_US / floating_point / ieee.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) INRIA
5  * Copyright (C) 2017 - 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:ns5="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="ieee" xml:lang="en">
21     <refnamediv>
22         <refname>ieee</refname>
23         <refpurpose>sets or gets the floating point exception mode</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>mod = ieee()
28             ieee(mod)
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>mod</term>
36                 <listitem>
37                     <para>integer scalar whose possible values are 0, 1 or 2</para>
38                 </listitem>
39             </varlistentry>
40         </variablelist>
41     </refsection>
42     <refsection>
43         <title>Description</title>
44         <para>
45             <literal>ieee()</literal> returns the current floating point exception mode.
46         <variablelist>
47             <varlistentry>
48                 <term>0</term>
49                 <listitem>
50                     <para>floating point exception produces an error.</para>
51                     <para>
52                        <literal>%inf</literal> and <literal>%nan</literal> special values can be
53                        used in this mode without error. For instance, <literal>%inf/%inf</literal>,
54                        <literal>%inf-%inf</literal> or <literal>%inf/%nan</literal> are known
55                        operations.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>1</term>
61                 <listitem>
62                     floating point exception produces a warning.
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>2</term>
67                 <listitem>
68                     floating point exception produces Inf or Nan.
69                 </listitem>
70             </varlistentry>
71         </variablelist>
72         </para>
73         <para>
74             <literal>ieee(mod)</literal> sets the current floating point exception mode to
75             <varname>mod</varname>.
76         </para>
77         <note>
78             The default initial mode is 2. This default value may be set in any of the following ways:
79             <itemizedlist>
80                 <listitem>
81                   Through the Preferences GUI: <code>preferences</code>, in the section
82                   <emphasis role="italic">General => Environment => ieee</emphasis>.
83                 </listitem>
84                 <listitem>
85                   Equivalently, using <code>xmlSetValues</code> as follows
86                   (to set the mode to 1) :
87                   <para>
88                   <literal>xmlSetValues("//general/body/environment", ["fpe";"1"])</literal>
89                   </para>
90                 </listitem>
91                 <listitem>
92                     Or by using <literal>ieee(mod)</literal> in your startup file.
93                 </listitem>
94             </itemizedlist>
95         </note>
96         <warning>
97             Floating point exception arising inside some library algorithms are not yet handled
98             by <literal>ieee</literal> modes.
99         </warning>
100     </refsection>
101     <refsection>
102         <title>Examples</title>
103         <programlisting role="example"><![CDATA[
104 ieee(1); 1/0
105 ieee(2); 1/0, log(0)
106  ]]></programlisting>
107     </refsection>
108     <refsection role="see also">
109         <title>See Also</title>
110         <simplelist type="inline">
111             <member>
112                 <link linkend="percentnan">%nan</link>
113             </member>
114             <member>
115                 <link linkend="percentinf">%inf</link>
116             </member>
117             <member>
118                 <link linkend="isinf">isinf</link>
119             </member>
120              <member>
121                 <link linkend="isnan">isnan</link>
122             </member>
123            <member>
124                 <link linkend="number_properties">number_properties</link>
125             </member>
126         </simplelist>
127     </refsection>
128     <refsection role="history">
129         <title>History</title>
130         <revhistory>
131             <revision>
132                 <revnumber>6.0.0</revnumber>
133                 <revremark>2 is now the initial mode value.</revremark>
134             </revision>
135         </revhistory>
136     </refsection>
137 </refentry>