reference/math/functions/is-nan.xml
61374bbe228e8e9c55a24aba59a1e2bb2a871148
61374bbe228e8e9c55a24aba59a1e2bb2a871148
...
...
@@ -1,21 +1,40 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xml:id='function.is-nan' xmlns="http://docbook.org/ns/docbook">
3
+
<refentry xml:id="function.is-nan" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>is_nan</refname>
6
-
<refpurpose>Finds whether a value is not a number</refpurpose>
6
+
<refpurpose>Checks whether a float is NAN</refpurpose>
7
7
</refnamediv>
8
8
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>bool</type><methodname>is_nan</methodname>
13
-
<methodparam><type>float</type><parameter>val</parameter></methodparam>
13
+
<methodparam><type>float</type><parameter>num</parameter></methodparam>
14
14
</methodsynopsis>
15
15
<para>
16
-
Checks whether <parameter>val</parameter> is 'not a number',
17
-
like the result of <literal>acos(1.01)</literal>.
16
+
Returns whether the given <parameter>num</parameter> is <constant>NAN</constant> (<quote>Not A Number</quote>).
18
17
</para>
18
+
<para>
19
+
<constant>NAN</constant> is returned from mathematical operations that are undefined,
20
+
for example when passing parameters outside of function’s input domain. The square root
21
+
(<function>sqrt</function>) is only defined for positive numbers, passing a negative number
22
+
will result in <constant>NAN</constant>. Other examples of operations returning <constant>NAN</constant>
23
+
are dividing <constant>INF</constant> by <constant>INF</constant> and any operation involving an
24
+
existing <constant>NAN</constant> value.
25
+
</para>
26
+
<note>
27
+
<para>
28
+
Despite its name of <quote>Not A Number</quote>, <constant>NAN</constant> is a valid value of type &float;.
29
+
</para>
30
+
</note>
31
+
<caution>
32
+
<para>
33
+
<constant>NAN</constant> does not compare equal to <constant>NAN</constant>. To check whether
34
+
a float is <constant>NAN</constant>, <function>is_nan</function> must be used. Checking
35
+
<code>$float === NAN</code> will not work.
36
+
</para>
37
+
</caution>
19
38
</refsect1>
20
39
21
40
<refsect1 role="parameters">
...
...
@@ -23,10 +42,10 @@
23
42
<para>
24
43
<variablelist>
25
44
<varlistentry>
26
-
<term><parameter>val</parameter></term>
45
+
<term><parameter>num</parameter></term>
27
46
<listitem>
28
47
<para>
29
-
The value to check
48
+
The &float; to check
30
49
</para>
31
50
</listitem>
32
51
</varlistentry>
...
...
@@ -37,8 +56,7 @@
37
56
<refsect1 role="returnvalues">
38
57
&reftitle.returnvalues;
39
58
<para>
40
-
Returns &true; if <parameter>val</parameter> is 'not a number',
41
-
else &false;.
59
+
&true; if <parameter>num</parameter> is <constant>NAN</constant>, else &false;.
42
60
</para>
43
61
</refsect1>
44
62
...
...
@@ -50,9 +68,7 @@
50
68
<programlisting role="php">
51
69
<![CDATA[
52
70
<?php
53
-
// Invalid calculation, will return a
54
-
// NaN value
55
-
$nan = acos(8);
71
+
$nan = sqrt(-1);
56
72
57
73
var_dump($nan, is_nan($nan));
58
74
?>
...
...
@@ -80,7 +96,6 @@ bool(true)
80
96
</refsect1>
81
97
82
98
</refentry>
83
-
84
99
<!-- Keep this comment at the end of the file
85
100
Local variables:
86
101
mode: sgml
87
102