Typo in help sections: 'See Also'->'See also'
[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>
85                     Otherwise, <varname>d(i)</varname> returns
86                     <literal>%nan</literal>, and <varname>tails(i)</varname> is
87                     the whole <varname>str(i)</varname>.
88                 </listitem>
89             </itemizedlist>
90         </para>
91         <warning>
92             <itemizedlist>
93                 <listitem>
94                     Complex numbers: <function>strtod(..)</function> parses
95                     and returns only their real part, provided that it is writen
96                     before their imaginary part.
97                 </listitem>
98                 <listitem>
99                     <function>strtod(..)</function> does not acknowledge any
100                     thousands separator, neither " ", nor "," nor any other one.
101                 </listitem>
102                 <listitem>
103                     <function>strtod(..)</function> parses strings only against
104                     decimal numbers. It does not interpret hexadecimal, octal
105                     or other radix strings.
106                 </listitem>
107                 <listitem>
108                     <function>strtod(..)</function> does not interpret any
109                     name of Scilab predefined or user-defined variables or special
110                     strings for <literal>%inf</literal> or <literal>%nan</literal>.
111                     Hence we have:
112                     <programlisting role="example"><![CDATA[
113 s = ["-0.034" "- 0.034"  "+1234.5678" "1234 5678"
114      "-.764"  "+.432"    "12,231.7"   "-5.458,871"
115      "1e43"   "-3.5d-12" "-1.2+i"     "i+1.2"
116      ""       "%inf"     "Inf"        "-Inf"
117      "%i"     "%pi"      "%e"         "%eps"
118      "%F"     "0x19B"    "#14C4"      "o5745"
119      ]
120 strtod(s)
121 ]]>             </programlisting>
122                     <screen><![CDATA[  s  =
123 !-0.034  - 0.034   +1234.5678  1234 5678   !
124 !-.764   +.432     12,231.7    -5.458,871  !
125 !1e43    -3.5d-12  -1.2+i      i+1.2       !
126 !        %inf      Inf         -Inf        !
127 !%i      %pi       %e          %eps        !
128 !%F      0x19B     #14C4       o5745       !
129
130 --> strtod(s)
131  ans  =
132   -0.034       Nan         1234.5678   1234.
133   -0.764       0.432       12.        -5.458
134    1.000D+43  -3.500D-12  -1.2         Nan
135    Nan         Nan         Nan         Nan
136    Nan         Nan         Nan         Nan
137    Nan         0.          Nan         Nan
138 ]]></screen>
139                 </listitem>
140                 <listitem>
141                     <function>strtod(..)</function> does not interpret
142                     escape sequences <literal>"\n"</literal>, <literal>"\t"</literal>,
143                     etc.
144                 </listitem>
145                 <listitem>
146                     This function is based on the strtod C function which
147                     causes different behaviors on Windows and Linux. In fact, on
148                     Windows, it is possible to use "d" or "D" for exponents,
149                     but it is not possible to use hexadecimal numbers.
150                 </listitem>
151             </itemizedlist>
152         </warning>
153     </refsection>
154     
155     <refsection role="examples">
156         <title>Examples</title>
157         <programlisting role="example"><![CDATA[
158 s = ["123.556 abc " ".543"      "#58B" "0x73 " "%inf"
159      "-1.47e-71"    "67,432.57" " 23,5" "-,57" "Inf" ]
160 [num, trail] = strtod(s);
161 num, "/"+trail+"/"
162
163 // With "," as decimal separator:
164 [num, trail] = strtod(s, ",");
165 num, "/"+trail+"/"
166  ]]></programlisting>
167     </refsection>
168     <refsection role="see also">
169         <title>See also</title>
170         <simplelist type="inline">
171             <member>
172                 <link linkend="evstr">evstr</link>
173             </member>
174             <member>
175                 <link linkend="isnum">isnum</link>
176             </member>
177             <member>
178                 <link linkend="isdigit">isdigit</link>
179             </member>
180             <member>
181                 <link linkend="bin2dec">bin2dec</link>
182             </member>
183             <member>
184                 <link linkend="oct2dec">oct2dec</link>
185             </member>
186             <member>
187                 <link linkend="hex2dec">hex2dec</link>
188             </member>
189         </simplelist>
190     </refsection>
191     <refsection role="history">
192         <title>History</title>
193         <revhistory>
194             <revision>
195                 <revnumber>5.5.0</revnumber>
196                 <revremark>
197                     Option decimalseparator introduced (SEP 97).
198                 </revremark>
199             </revision>
200             <revision>
201                 <revnumber>5.4.1</revnumber>
202                 <revremark>
203                     If <varname>str</varname> does not contain any numerical value,
204                     <varname>d</varname> now returns <literal>Nan</literal>
205                     instead of <literal>0</literal>.
206                 </revremark>
207             </revision>
208         </revhistory>
209     </refsection>
210 </refentry>