2dfaaac06bf4e41d990b66ec31ca155481aa14b1
[scilab.git] / scilab / modules / string / help / en_US / strtod.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) 2016 - Samuel GOUGEON
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org" xml:id="strtod" xml:lang="en">
20     <refnamediv>
21         <refname>strtod</refname>
22         <refpurpose>parse and convert literal numbers STRings TO Decimal numbers</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             d =  strtod(str [,decimalseparator])
28             [d, tails] = strtod(str [,decimalseparator])
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection role="arguments">
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>str</term>
36                 <listitem>
37                     <para>
38                         single component, vector, or matrix of text (strings).
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>decimalseparator</term>
44                 <listitem>
45                     <para>
46                         the decimal separator chosen: "." (by default) or ",".
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>d</term>
52                 <listitem>
53                     <para>
54                         scalar, vector, or matrix of decimal numbers.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>tails</term>
60                 <listitem>
61                     <para>
62                         a string or matrix of strings: remaining parts of
63                         <varname>str</varname> after the numerical heads
64                         (if any).
65                     </para>
66                 </listitem>
67             </varlistentry>
68         </variablelist>
69     </refsection>
70     <refsection role="description">
71         <title>Description</title>
72         <para>
73             <code>[d, tails] = strtod(str)</code> parses each string of
74             <varname>str</varname> and tries to interpret its content as a decimal
75             number:
76             <itemizedlist>
77                 <listitem>If it succeeds, at least for the heading part of
78                     <varname>str(i)</varname>, the corresponding decimal number
79                     is returned in <varname>d(i)</varname>. If any, the
80                     trailing part of <varname>str(i)</varname> is ignored and
81                     returned in <varname>tails(i)</varname>; otherwise,
82                     <varname>tails(i)</varname> returns "".
83                 </listitem>
84                 <listitem>Otherwise, <varname>d(i)</varname> returns
85                     <literal>%nan</literal>, and <varname>tails(i)</varname> is
86                     the whole <varname>str(i)</varname>.
87                 </listitem>
88             </itemizedlist>
89         </para>
90         <warning>
91             <itemizedlist>
92                 <listitem>
93                     Complex numbers: <function>strtod(..)</function> parses
94                     and returns only their real part, provided that it is writen
95                     before their imaginary part.
96                 </listitem>
97                 <listitem>
98                     <function>strtod(..)</function> does not acknowledge any
99                     thousands separator, neither " ", nor "," nor any other one.
100                 </listitem>
101                 <listitem>
102                     <function>strtod(..)</function> parses strings only against
103                     decimal numbers. It does not interpret hexadecimal, octal
104                     or other radix strings.
105                 </listitem>
106                 <listitem>
107                     <function>strtod(..)</function> does not interpret any
108                     name of Scilab predefined or user-defined variables or special
109                     strings for <literal>%inf</literal> or <literal>%nan</literal>.
110                     Hence we have:
111                     <programlisting role="example"><![CDATA[
112 s = ["-0.034" "- 0.034"  "+1234.5678" "1234 5678"
113      "-.764"  "+.432"    "12,231.7"   "-5.458,871"
114      "1e43"   "-3.5d-12" "-1.2+i"     "i+1.2"
115      ""       "%inf"     "Inf"        "-Inf"
116      "%i"     "%pi"      "%e"         "%eps"
117      "%F"     "0x19B"    "#14C4"      "o5745"
118      ]
119 strtod(s)
120 ]]>             </programlisting>
121                 <screen><![CDATA[  s  =
122 !-0.034  - 0.034   +1234.5678  1234 5678   !
123 !-.764   +.432     12,231.7    -5.458,871  !
124 !1e43    -3.5d-12  -1.2+i      i+1.2       !
125 !        %inf      Inf         -Inf        !
126 !%i      %pi       %e          %eps        !
127 !%F      0x19B     #14C4       o5745       !
128
129 --> strtod(s)
130  ans  =
131   -0.034       Nan         1234.5678   1234.
132   -0.764       0.432       12.        -5.458
133    1.000D+43  -3.500D-12  -1.2         Nan
134    Nan         Nan         Nan         Nan
135    Nan         Nan         Nan         Nan
136    Nan         0.          Nan         Nan
137 ]]></screen>
138                 </listitem>
139                 <listitem>
140                     <function>strtod(..)</function> does not interpret
141                     escape sequences <literal>"\n"</literal>, <literal>"\t"</literal>,
142                     etc.
143                 </listitem>
144                 <listitem>
145                     This function is based on the strtod C function which
146                     causes different behaviors on Windows and Linux. In fact, on
147                     Windows, it is possible to use "d" or "D" for exponents,
148                     but it is not possible to use hexadecimal numbers.
149                 </listitem>
150             </itemizedlist>
151         </warning>
152     </refsection>
153
154     <refsection role="examples">
155         <title>Examples</title>
156         <programlisting role="example"><![CDATA[
157 s = ["123.556 abc " ".543"      "#58B" "0x73 " "%inf"
158      "-1.47e-71"    "67,432.57" " 23,5" "-,57" "Inf" ]
159 [num, trail] = strtod(s);
160 num, "/"+trail+"/"
161
162 // With "," as decimal separator:
163 [num, trail] = strtod(s, ",");
164 num, "/"+trail+"/"
165  ]]></programlisting>
166     </refsection>
167     <refsection role="see also">
168         <title>See Also</title>
169         <simplelist type="inline">
170             <member>
171                 <link linkend="evstr">evstr</link>
172             </member>
173             <member>
174                 <link linkend="isnum">isnum</link>
175             </member>
176             <member>
177                 <link linkend="isdigit">isdigit</link>
178             </member>
179             <member>
180                 <link linkend="bin2dec">bin2dec</link>
181             </member>
182             <member>
183                 <link linkend="oct2dec">oct2dec</link>
184             </member>
185             <member>
186                 <link linkend="hex2dec">hex2dec</link>
187             </member>
188         </simplelist>
189     </refsection>
190     <refsection role="history">
191         <title>History</title>
192         <revhistory>
193             <revision>
194                 <revnumber>5.5.0</revnumber>
195                 <revremark>
196                     Option decimalseparator introduced (SEP 97).
197                 </revremark>
198             </revision>
199             <revision>
200                 <revnumber>5.4.1</revnumber>
201                 <revremark>
202                     If <varname>str</varname> does not contain any numerical value,
203                     <varname>d</varname> now returns <literal>Nan</literal>
204                     instead of <literal>0</literal>.
205                 </revremark>
206             </revision>
207         </revhistory>
208     </refsection>
209 </refentry>