strtod() help page overhauled. (fr) added 84/18284/7
Samuel GOUGEON [Wed, 22 Jun 2016 02:38:19 +0000 (04:38 +0200)]
Change-Id: If322e0105df17938d560fd185c2c15006a1eddbf

scilab/CHANGES.md
scilab/modules/string/help/en_US/strtod.xml
scilab/modules/string/help/fr_FR/strtod.xml [new file with mode: 0644]
scilab/modules/string/help/ja_JP/strtod.xml [deleted file]
scilab/modules/string/help/pt_BR/strtod.xml [deleted file]
scilab/modules/string/help/ru_RU/strtod.xml

index 91b38a6..2b9ee26 100644 (file)
@@ -154,7 +154,7 @@ Help pages:
   - CACSD and Signal Processing help pages have been sorted up.
   - Colormaps and GUI/Menus subsections created
 * translations added:
-  - (fr): `format`, `typeof`, `isoview`, `ndgrid`, `bench_run`, `consolebox`, `harmean`, `sleep`
+  - (fr): `format`, `typeof`, `isoview`, `ndgrid`, `bench_run`, `consolebox`, `harmean`, `sleep`, `strtod`
   - (ru): homepage
 
 
index 8e6ae2b..2dfaaac 100644 (file)
@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) INRIA - 
- * 
+ * Copyright (C) INRIA -
+ * Copyright (C) 2016 - Samuel GOUGEON
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * along with this program.
  *
  -->
-<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="strtod" xml:lang="en">
+<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="strtod" xml:lang="en">
     <refnamediv>
         <refname>strtod</refname>
-        <refpurpose>convert string to double</refpurpose>
+        <refpurpose>parse and convert literal numbers STRings TO Decimal numbers</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
         <synopsis>
             d =  strtod(str [,decimalseparator])
-            [d, endstr] = strtod(str [,decimalseparator])
+            [d, tails] = strtod(str [,decimalseparator])
         </synopsis>
     </refsynopsisdiv>
-    <refsection>
+    <refsection role="arguments">
         <title>Arguments</title>
         <variablelist>
             <varlistentry>
                 <term>str</term>
                 <listitem>
                     <para>
-                        a character string or matrix of character strings.
+                        single component, vector, or matrix of text (strings).
                     </para>
                 </listitem>
             </varlistentry>
                 <term>d</term>
                 <listitem>
                     <para>
-                        a real or matrix of reals.
+                        scalar, vector, or matrix of decimal numbers.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>endstr</term>
+                <term>tails</term>
                 <listitem>
                     <para>
-                        a character string or matrix of character strings (next
-                        character in <varname>str</varname> after the numerical
-                        value).
+                        a string or matrix of strings: remaining parts of
+                        <varname>str</varname> after the numerical heads
+                        (if any).
                     </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
-    <refsection>
+    <refsection role="description">
         <title>Description</title>
         <para>
-            <code>[d, endstr] = strtod(str)</code> parses strings
-            <varname>str</varname> interpreting its content as a floating point
-            number and returns its value as a real. If <varname>str</varname> does not contain any numerical value then <varname>d</varname> equals <literal>Nan</literal>.
+            <code>[d, tails] = strtod(str)</code> parses each string of
+            <varname>str</varname> and tries to interpret its content as a decimal
+            number:
+            <itemizedlist>
+                <listitem>If it succeeds, at least for the heading part of
+                    <varname>str(i)</varname>, the corresponding decimal number
+                    is returned in <varname>d(i)</varname>. If any, the
+                    trailing part of <varname>str(i)</varname> is ignored and
+                    returned in <varname>tails(i)</varname>; otherwise,
+                    <varname>tails(i)</varname> returns "".
+                </listitem>
+                <listitem>Otherwise, <varname>d(i)</varname> returns
+                    <literal>%nan</literal>, and <varname>tails(i)</varname> is
+                    the whole <varname>str(i)</varname>.
+                </listitem>
+            </itemizedlist>
         </para>
+        <warning>
+            <itemizedlist>
+                <listitem>
+                    Complex numbers: <function>strtod(..)</function> parses
+                    and returns only their real part, provided that it is writen
+                    before their imaginary part.
+                </listitem>
+                <listitem>
+                    <function>strtod(..)</function> does not acknowledge any
+                    thousands separator, neither " ", nor "," nor any other one.
+                </listitem>
+                <listitem>
+                    <function>strtod(..)</function> parses strings only against
+                    decimal numbers. It does not interpret hexadecimal, octal
+                    or other radix strings.
+                </listitem>
+                <listitem>
+                    <function>strtod(..)</function> does not interpret any
+                    name of Scilab predefined or user-defined variables or special
+                    strings for <literal>%inf</literal> or <literal>%nan</literal>.
+                    Hence we have:
+                    <programlisting role="example"><![CDATA[
+s = ["-0.034" "- 0.034"  "+1234.5678" "1234 5678"
+     "-.764"  "+.432"    "12,231.7"   "-5.458,871"
+     "1e43"   "-3.5d-12" "-1.2+i"     "i+1.2"
+     ""       "%inf"     "Inf"        "-Inf"
+     "%i"     "%pi"      "%e"         "%eps"
+     "%F"     "0x19B"    "#14C4"      "o5745"
+     ]
+strtod(s)
+]]>             </programlisting>
+                <screen><![CDATA[  s  =
+!-0.034  - 0.034   +1234.5678  1234 5678   !
+!-.764   +.432     12,231.7    -5.458,871  !
+!1e43    -3.5d-12  -1.2+i      i+1.2       !
+!        %inf      Inf         -Inf        !
+!%i      %pi       %e          %eps        !
+!%F      0x19B     #14C4       o5745       !
+
+--> strtod(s)
+ ans  =
+  -0.034       Nan         1234.5678   1234.
+  -0.764       0.432       12.        -5.458
+   1.000D+43  -3.500D-12  -1.2         Nan
+   Nan         Nan         Nan         Nan
+   Nan         Nan         Nan         Nan
+   Nan         0.          Nan         Nan
+]]></screen>
+                </listitem>
+                <listitem>
+                    <function>strtod(..)</function> does not interpret
+                    escape sequences <literal>"\n"</literal>, <literal>"\t"</literal>,
+                    etc.
+                </listitem>
+                <listitem>
+                    This function is based on the strtod C function which
+                    causes different behaviors on Windows and Linux. In fact, on
+                    Windows, it is possible to use "d" or "D" for exponents,
+                    but it is not possible to use hexadecimal numbers.
+                </listitem>
+            </itemizedlist>
+        </warning>
     </refsection>
-    <refsection>
-        <title>Remarks</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    This function is based on the strtod C function which causes different behaviors on Windows and Linux. In fact, on Windows, it is possible to use
-                    d or D for exponents, but it is not possible to use hexadecimal numbers.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-                    Note that <literal>strtod("%inf")</literal> returns <literal>Nan</literal>.
-                </para>
-            </listitem>
-        </itemizedlist>
-    </refsection>
-    
-    <refsection>
+
+    <refsection role="examples">
         <title>Examples</title>
-        <programlisting role="example"><![CDATA[ 
-strtod('123.556This is a sample real')
-strtod('123,556This is a sample real', ",")
-[d,endstr] = strtod('123.556This is a sample real')
-strtod(['123.556This is a sample real','888.666 here'])
-[d,endstr] =strtod(['123.556This is a sample real','888.666 here'])
-[d,endstr] =strtod(['123.556This is a sample real','888,666 here'], ",")
+        <programlisting role="example"><![CDATA[
+s = ["123.556 abc " ".543"      "#58B" "0x73 " "%inf"
+     "-1.47e-71"    "67,432.57" " 23,5" "-,57" "Inf" ]
+[num, trail] = strtod(s);
+num, "/"+trail+"/"
+
+// With "," as decimal separator:
+[num, trail] = strtod(s, ",");
+num, "/"+trail+"/"
  ]]></programlisting>
     </refsection>
-    <refsection>
+    <refsection role="see also">
+        <title>See Also</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="evstr">evstr</link>
+            </member>
+            <member>
+                <link linkend="isnum">isnum</link>
+            </member>
+            <member>
+                <link linkend="isdigit">isdigit</link>
+            </member>
+            <member>
+                <link linkend="bin2dec">bin2dec</link>
+            </member>
+            <member>
+                <link linkend="oct2dec">oct2dec</link>
+            </member>
+            <member>
+                <link linkend="hex2dec">hex2dec</link>
+            </member>
+        </simplelist>
+    </refsection>
+    <refsection role="history">
         <title>History</title>
         <revhistory>
             <revision>
                 <revnumber>5.5.0</revnumber>
                 <revremark>
-                    New optional input: decimalseparator (SEP 97).
+                    Option decimalseparator introduced (SEP 97).
                 </revremark>
             </revision>
             <revision>
                 <revnumber>5.4.1</revnumber>
                 <revremark>
-                    If <varname>str</varname> does not contain any numerical value then <varname>d</varname> equals <literal>Nan</literal> instead of <literal>0</literal> in previous versions.
+                    If <varname>str</varname> does not contain any numerical value,
+                    <varname>d</varname> now returns <literal>Nan</literal>
+                    instead of <literal>0</literal>.
                 </revremark>
             </revision>
         </revhistory>
diff --git a/scilab/modules/string/help/fr_FR/strtod.xml b/scilab/modules/string/help/fr_FR/strtod.xml
new file mode 100644 (file)
index 0000000..fdfcd0c
--- /dev/null
@@ -0,0 +1,214 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) INRIA -
+ * Copyright (C) 2016 - Samuel GOUGEON
+ * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ *
+ * This file is hereby licensed under the terms of the GNU GPL v2.0,
+ * pursuant to article 5.3.4 of the CeCILL v.2.1.
+ * This file was originally licensed under the terms of the CeCILL v2.1,
+ * and continues to be available under such terms.
+ * For more information, see the COPYING file which you should have received
+ * along with this program.
+ *
+ -->
+<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="strtod" xml:lang="fr">
+    <refnamediv>
+        <refname>strtod</refname>
+        <refpurpose>convertit chaque nombre décimal littéral (texte) en sa valeur numérique</refpurpose>
+    </refnamediv>
+    <refsynopsisdiv>
+        <title>Syntaxe</title>
+        <synopsis>
+            d =  strtod(str [,decimalseparator])
+            [d, tails] = strtod(str [,decimalseparator])
+        </synopsis>
+    </refsynopsisdiv>
+    <refsection role="arguments">
+        <title>Arguments</title>
+        <variablelist>
+            <varlistentry>
+                <term>str</term>
+                <listitem>
+                    <para>
+                        texte unique, ou vecteur ou matrice de textes.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>decimalseparator</term>
+                <listitem>
+                    <para>
+                        caractère "." (par défaut) ou "," : séparateur décimal reconnu
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>d</term>
+                <listitem>
+                    <para>
+                        scalaire, vecteur ou matrice de nombres décimaux.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>tails</term>
+                <listitem>
+                    <para>
+                        matrice texte de taille identique à celle de
+                        <varname>str</varname> : <literal>tails(i)</literal> est
+                        la fin (éventuelle) de <literal>str(i)</literal> non prise
+                        en compte pour établir <literal>d(i)</literal>, ou "" par
+                        défaut.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection role="description">
+        <title>Description</title>
+        <para>
+            <code>[d, tails] = strtod(str)</code> interprète chaque élément de
+            <varname>str</varname> et tente de reconnaître un nombre décimal :
+            <itemizedlist>
+                <listitem>Si elle y parvient, au moins pour la partie initiale de
+                    <varname>str(i)</varname>, la valeur numérique décimale
+                    correspondante est enregistrée dans <varname>d(i)</varname>.
+                    Si d'autres caractères suivent la partie initiale interprétée
+                    de <varname>str(i)</varname>, ils sont alors ignorés et
+                    sont indiqués dans <varname>tails(i)</varname> ; sinon,
+                    <varname>tails(i)</varname> retourne "".
+                </listitem>
+                <listitem>
+                    Si aucun nombre décimal n'est reconnu, <varname>d(i)</varname>
+                    retourne <literal>%nan</literal>, et <varname>tails(i)</varname>
+                    retourne <varname>str(i)</varname>.
+                </listitem>
+            </itemizedlist>
+        </para>
+        <warning>
+            <itemizedlist>
+                <listitem>
+                    Nombres complexes : <function>strtod(..)</function> reconnaît
+                    et retourne uniquement leur partie réelle (pour peu qu'elle
+                    soit écrite avant la partie imaginaire). Les symboles "i" ou
+                    "j" ne sont pas reconnus.
+                </listitem>
+                <listitem>
+                    <function>strtod(..)</function> ne reconnaît aucun séparateur
+                    de milliers ou de millièmes, ni " ", ni "," ni aucun autre.
+                </listitem>
+                <listitem>
+                    Seuls les nombres représentés en base 10 sont recherchés par
+                    <function>strtod(..)</function>. Les nombres représentés
+                    en binaire, octal, hexadécimal ou autre base de numération
+                    ne sont pas reconnus.
+                </listitem>
+                <listitem>
+                    <function>strtod(..)</function> ne reconnaît le nom d'aucune
+                    variable numérique prédéfinie de Scilab ou de l'utilisateur,
+                    ni aucune représentation de <literal>%inf</literal>.
+                    Ainsi aurons-nous :
+                    <programlisting role="example"><![CDATA[
+s = ["-0.034" "- 0.034"  "+1234.5678" "1234 5678"
+     "-.764"  "+.432"    "12,231.7"   "-5.458,871"
+     "1e43"   "-3.5d-12" "-1.2+i"     "i+1.2"
+     ""       "%inf"     "Inf"        "-Inf"
+     "%i"     "%pi"      "%e"         "%eps"
+     "%F"     "0x19B"    "#14C4"      "o5745"
+     ]
+strtod(s)
+]]>             </programlisting>
+                    <screen><![CDATA[  s  =
+!-0.034  - 0.034   +1234.5678  1234 5678   !
+!-.764   +.432     12,231.7    -5.458,871  !
+!1e43    -3.5d-12  -1.2+i      i+1.2       !
+!        %inf      Inf         -Inf        !
+!%i      %pi       %e          %eps        !
+!%F      0x19B     #14C4       o5745       !
+
+--> strtod(s)
+ ans  =
+  -0.034       Nan         1234.5678   1234.
+  -0.764       0.432       12.        -5.458
+   1.000D+43  -3.500D-12  -1.2         Nan
+   Nan         Nan         Nan         Nan
+   Nan         Nan         Nan         Nan
+   Nan         0.          Nan         Nan
+]]></screen>
+                </listitem>
+                <listitem>
+                    <function>strtod(..)</function> n'interprète aucun caractère
+                    spécial protégé tel que <literal>"\n"</literal> ou
+                    <literal>"\t"</literal>, etc.
+                </listitem>
+                <listitem>
+                    Cette fonction est basée sur sa version existante en langage C,
+                    laquelle se comporte différemment sous Windows et sous Linux :
+                    Sous Windows, les caractères "d" ou "D" peuvent indifféremment
+                    être utilisés pour les exposants.
+                </listitem>
+            </itemizedlist>
+        </warning>
+    </refsection>
+    
+    <refsection role="examples">
+        <title>Exemples</title>
+        <programlisting role="example"><![CDATA[
+s = ["123.556 abc " ".543"      "#58B" "0x73 " "%inf"
+     "-1.47e-71"    "67,432.57" " 23,5" "-,57" "Inf" ]
+[num, trail] = strtod(s);
+num, "/"+trail+"/"
+
+// Avec "," comme séparateur décimal :
+[num, trail] = strtod(s, ",");
+num, "/"+trail+"/"
+ ]]></programlisting>
+    </refsection>
+    <refsection role="see also">
+        <title>Voir aussi</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="evstr">evstr</link>
+            </member>
+            <member>
+                <link linkend="isnum">isnum</link>
+            </member>
+            <member>
+                <link linkend="isdigit">isdigit</link>
+            </member>
+            <member>
+                <link linkend="bin2dec">bin2dec</link>
+            </member>
+            <member>
+                <link linkend="oct2dec">oct2dec</link>
+            </member>
+            <member>
+                <link linkend="hex2dec">hex2dec</link>
+            </member>
+        </simplelist>
+    </refsection>
+    <refsection role="history">
+        <title>Historique</title>
+        <revhistory>
+            <revision>
+                <revnumber>5.5.0</revnumber>
+                <revremark>
+                    Introduction de l'option "decimalseparator" (SEP 97).
+                </revremark>
+            </revision>
+            <revision>
+                <revnumber>5.4.1</revnumber>
+                <revremark>
+                    Si <varname>str(i)</varname> ne représente aucune valeur numérique,
+                    <varname>d(i)</varname> vaut désormais <literal>Nan</literal>
+                    au lieu de <literal>0</literal>.
+                </revremark>
+            </revision>
+        </revhistory>
+    </refsection>
+</refentry>
diff --git a/scilab/modules/string/help/ja_JP/strtod.xml b/scilab/modules/string/help/ja_JP/strtod.xml
deleted file mode 100644 (file)
index 887b7fc..0000000
+++ /dev/null
@@ -1,234 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) INRIA - 
- * 
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * This file is hereby licensed under the terms of the GNU GPL v2.0,
- * pursuant to article 5.3.4 of the CeCILL v.2.1.
- * This file was originally licensed under the terms of the CeCILL v2.1,
- * and continues to be available under such terms.
- * For more information, see the COPYING file which you should have received
- * along with this program.
- *
- -->
-
-<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="strtod" xml:lang="ja">
-    
-    <refnamediv>
-        
-        <refname>strtod</refname>
-        
-        <refpurpose>文字列を倍精度実数に変換.</refpurpose>
-        
-    </refnamediv>
-    
-    <refsynopsisdiv>
-        
-        <title>呼び出し手順</title>
-        
-        <synopsis>
-            
-            d =  strtod(str [,decimalseparator])
-            
-            [d, endstr] = strtod(str [,decimalseparator])
-            
-        </synopsis>
-        
-    </refsynopsisdiv>
-    
-    <refsection>
-        
-        <title>引数</title>
-        
-        <variablelist>
-            
-            <varlistentry>
-                
-                <term>str</term>
-                
-                <listitem>
-                    
-                    <para>
-                        
-                        文字列または文字列の行列
-                        
-                    </para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-            <varlistentry>
-                
-                <term>decimalseparator</term>
-                
-                <listitem>
-                    
-                    <para>
-                        
-                        選択した10進数セパレータ: "." (デフォルト) または ",".
-                        
-                    </para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-            <varlistentry>
-                
-                <term>d</term>
-                
-                <listitem>
-                    
-                    <para>
-                        
-                        実数または実数の行列
-                        
-                    </para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-            <varlistentry>
-                
-                <term>endstr</term>
-                
-                <listitem>
-                    
-                    <para>
-                        
-                        文字列または文字列の行列 
-                        
-                        (<varname>str</varname>の中で数値の後に続く文字).
-                        
-                    </para>
-                    
-                </listitem>
-                
-            </varlistentry>
-            
-        </variablelist>
-        
-    </refsection>
-    
-    <refsection>
-        
-        <title>説明</title>
-        
-        <para>
-            
-            <code>[d, endstr] = strtod(str)</code> は,
-            
-            文字列<varname>str</varname> を
-            
-            パースし,その内容を浮動小数点数として解釈して,
-            
-            その値を実数として返します.
-            
-            <varname>str</varname>に数値が含まれていない場合,
-            
-            <varname>d</varname> は <literal>Nan</literal>となります.
-            
-        </para>
-        
-    </refsection>
-    
-    <refsection>
-        
-        <title>注意</title>
-        
-        <itemizedlist>
-            
-            <listitem>
-                
-                <para>
-                    
-                    この関数はWindowsとLinuxで動作が異なるstrtod C関数に基づきます.
-                    
-                    実際, Windows では指数部にd または D を使用できますが,
-                    
-                    16進数を使用することはできません.
-                    
-                </para>
-                
-            </listitem>
-            
-            <listitem>
-                
-                <para>
-                    
-                    <literal>strtod("%inf")</literal> は <literal>Nan</literal>を
-                    
-                    返すことに注意してください.
-                    
-                </para>
-                
-            </listitem>
-            
-        </itemizedlist>
-        
-    </refsection>
-    
-    
-    
-    <refsection>
-        
-        <title>例</title>
-        
-        <programlisting role="example"><![CDATA[
-strtod('123.556This is a sample real')
-strtod('123,556This is a sample real', ",")
-[d,endstr] = strtod('123.556This is a sample real')
-strtod(['123.556This is a sample real','888.666 here'])
-[d,endstr] =strtod(['123.556This is a sample real','888.666 here'])
-[d,endstr] =strtod(['123.556This is a sample real','888,666 here'], ",")
- ]]></programlisting>
-        
-    </refsection>
-    
-    <refsection>
-        
-        <title>履歴</title>
-        
-        <revhistory>
-            
-            <revision>
-                
-                <revnumber>5.5.0</revnumber>
-                
-                <revremark>
-                    
-                    新しいオプション入力: decimalseparator (SEP 97).
-                    
-                </revremark>
-                
-            </revision>
-            
-            <revision>
-                
-                <revnumber>5.4.1</revnumber>
-                
-                <revremark>
-                    
-                    <varname>str</varname> に数値が含まれていない場合,
-                    
-                    <varname>d</varname> は以前のバージョンのように
-                    
-                    <literal>0</literal>ではなく,
-                    
-                    <literal>Nan</literal>となります.
-                    
-                </revremark>
-                
-            </revision>
-            
-        </revhistory>
-        
-    </refsection>
-    
-</refentry>
-
diff --git a/scilab/modules/string/help/pt_BR/strtod.xml b/scilab/modules/string/help/pt_BR/strtod.xml
deleted file mode 100644 (file)
index 21e44a4..0000000
+++ /dev/null
@@ -1,69 +0,0 @@
-<?xml version="1.0" encoding="windows-1251"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) INRIA - 
- * 
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * This file is hereby licensed under the terms of the GNU GPL v2.0,
- * pursuant to article 5.3.4 of the CeCILL v.2.1.
- * This file was originally licensed under the terms of the CeCILL v2.1,
- * and continues to be available under such terms.
- * For more information, see the COPYING file which you should have received
- * along with this program.
- *
- -->
-<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="strtod" xml:lang="pt">
-    <refnamediv>
-        <refname>strtod</refname>
-        <refpurpose>converte um string para um double</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Seq&#252;&#234;ncia de Chamamento</title>
-        <synopsis>d =  strtod(str)
-            [d,endstr] = strtod(str)
-        </synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Par&#226;metros</title>
-        <variablelist>
-            <varlistentry>
-                <term>str</term>
-                <listitem>
-                    <para>string ou matriz de strings</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>d</term>
-                <listitem>
-                    <para>escalar real ou matriz de reais</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>endstr</term>
-                <listitem>
-                    <para>string ou matriz de strings (pr&#243;ximo caractere em str
-                        ap&#243;s o valor num&#233;rico).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Descri&#231;&#227;o</title>
-        <para>
-            <literal>[d,endstr] = strtod(str)</literal> analisa o string str
-            interpretando o seu conte&#250;do como um n&#250;mero de ponto flutuante e
-            retorna o seu valor como um real.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Exemplos</title>
-        <programlisting role="example"><![CDATA[ 
-strtod('123.556Este &#233; um real de amostra')
-[d,endstr] = strtod('123.556Este &#233; um real de amostra)
-strtod(['123.556Este &#233; um real de amostra','888.666 aqui'])
-[d,endstr] =strtod(['123.556Este &#233; um real de amostra','888.666 aqui'])
- ]]></programlisting>
-    </refsection>
-</refentry>
index d7dcc54..6810ac2 100644 (file)
@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) INRIA - 
- * 
+ * Copyright (C) INRIA -
+ * Copyright (C) 2016 - Samuel GOUGEON
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * along with this program.
  *
  -->
-<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="strtod" xml:lang="ru">
+<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="strtod" xml:lang="ru">
     <refnamediv>
         <refname>strtod</refname>
-        <refpurpose>
-            преобразование строки в число удвоенной точности
-        </refpurpose>
+        <refpurpose>проверка синтаксиса и преобразование строк литеральных чисел в десятичные числа</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Синтаксис</title>
         <synopsis>
-            d =  strtod(str)
-            [d, endstr] = strtod(str)
+            d =  strtod(str [,decimalseparator])
+            [d, tails] = strtod(str [,decimalseparator])
         </synopsis>
     </refsynopsisdiv>
-    <refsection>
+    <refsection role="arguments">
         <title>Аргументы</title>
         <variablelist>
             <varlistentry>
                 <term>str</term>
                 <listitem>
                     <para>
-                        символьная строка или матрица символьных строк.
+                        текстовый (строковый) одиночный элемент, вектор или матрица.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>decimalseparator</term>
+                <listitem>
+                    <para>
+                        выбранный десятичный разделитель: "." (по умолчанию) или ",".
                     </para>
                 </listitem>
             </varlistentry>
                 <term>d</term>
                 <listitem>
                     <para>
-                        вещественное число или матрица вещественных чисел.
+                        скаляр, вектор или матрица десятичных чисел.
                     </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
-                <term>endstr</term>
+                <term>tails</term>
                 <listitem>
                     <para>
-                        символьная строка или матрица символьных строк
-                        (следующий символ в <varname>str</varname> после
-                        числового значения).
+                        строка или матрица строк: оставшиеся части <varname>str</varname> после
+                        начал чисел (если есть).
                     </para>
                 </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
-    <refsection>
+    <refsection role="description">
         <title>Описание</title>
         <para>
-            <code>[d, endstr] = strtod(str)</code> анализирует строки
-            <varname>str</varname>, интерпретируя их содержимое как числа с
-            плавающей запятой, и возвращает их значения в виде вещественных
-            чисел.
+            Инструкция <code>[d, tails] = strtod(str)</code> проверяет синтаксис каждого строкового
+            значения  <varname>str</varname> и пытается интерпретировать его содержимое как десятичное число:
+            <itemizedlist>
+                <listitem>
+                    Если это удалось, по крайней мере для головной части <varname>str(i)</varname>,
+                    то соответствующее число возвращается в <varname>d(i)</varname>. Если возможно,
+                    завершающая часть <varname>str(i)</varname> игнорируется и возвращается в
+                    <varname>tails(i)</varname>; в противном случае <varname>tails(i)</varname> возвращает "".
+               </listitem>
+                <listitem>
+                    В противном случае <varname>d(i)</varname> возвращает <literal>%nan</literal>,
+                    а <varname>tails(i)</varname> полностью равна <varname>str(i)</varname>.
+                </listitem>
+            </itemizedlist>
         </para>
+        <warning>
+            <itemizedlist>
+                <listitem>
+                    Комплексные числа: функция <function>strtod(..)</function> проверяет
+                    синтаксис и возвращает только их вещественную часть при условии, что она записана перед
+                    мнимой частью.
+                </listitem>
+                <listitem>
+                    <function>strtod(..)</function> не признаёт никаких разделителей тысяч, ни " ", ни ",",
+                    ни каких иных.
+                </listitem>
+                <listitem>
+                    <function>strtod(..)</function> проверяет синтаксис строк только по десятичным числам.
+                    Она не интерпретирует строки шестнадцатеричных, восмеричных или иных чисел.
+                </listitem>
+                <listitem>
+                    <function>strtod(..)</function> не интерпретирует никаких имён переменных, предопределённых
+                    в Scilab или предопределённых пользователем, или специальных строк <literal>%inf</literal>
+                    или <literal>%nan</literal>. Следовательно:
+                    <programlisting role="example"><![CDATA[
+s = ["-0.034" "- 0.034"  "+1234.5678" "1234 5678"
+     "-.764"  "+.432"    "12,231.7"   "-5.458,871"
+     "1e43"   "-3.5d-12" "-1.2+i"     "i+1.2"
+     ""       "%inf"     "Inf"        "-Inf"
+     "%i"     "%pi"      "%e"         "%eps"
+     "%F"     "0x19B"    "#14C4"      "o5745"
+     ]
+strtod(s)
+]]>             </programlisting>
+                <screen><![CDATA[  s  =
+!-0.034  - 0.034   +1234.5678  1234 5678   !
+!-.764   +.432     12,231.7    -5.458,871  !
+!1e43    -3.5d-12  -1.2+i      i+1.2       !
+!        %inf      Inf         -Inf        !
+!%i      %pi       %e          %eps        !
+!%F      0x19B     #14C4       o5745       !
+--> strtod(s)
+ ans  =
+  -0.034       Nan         1234.5678   1234.
+  -0.764       0.432       12.        -5.458
+   1.000D+43  -3.500D-12  -1.2         Nan
+   Nan         Nan         Nan         Nan
+   Nan         Nan         Nan         Nan
+   Nan         0.          Nan         Nan
+]]></screen>
+                </listitem>
+                <listitem>
+                    <function>strtod(..)</function> не интерпретирует эскейп-последовательности  <literal>"\n"</literal>,
+                    <literal>"\t"</literal> и др.
+                </listitem>
+                <listitem>
+                    Эта функция основана на Си-функции strtod, которая по-разному ведёт себя в  Windows и Linux.
+                    На самом деле в Windows можно использовать "d" и "D" для экспонент, но нельзя использовать
+                    шестнадцатеричные числа.
+                </listitem>
+            </itemizedlist>
+        </warning>
     </refsection>
-    <refsection>
+    <refsection role="examples">
         <title>Примеры</title>
-        <programlisting role="example"><![CDATA[ 
-strtod('123.556Это вещественное число для примера')
-[d,endstr] = strtod('123.556Это вещественное число для примера')
-strtod(['123.556This is a sample real','888.666 здесь'])
-[d,endstr] =strtod(['123.556Это вещественное число для примера','888.666 здесь'])
+        <programlisting role="example"><![CDATA[
+s = ["123.556 abc " ".543"      "#58B" "0x73 " "%inf"
+     "-1.47e-71"    "67,432.57" " 23,5" "-,57" "Inf" ]
+[num, trail] = strtod(s);
+num, "/"+trail+"/"
+// С "," в качестве десятичного разделителя:
+[num, trail] = strtod(s, ",");
+num, "/"+trail+"/"
  ]]></programlisting>
     </refsection>
+    <refsection role="see also">
+        <title>Смотрите также</title>
+        <simplelist type="inline">
+            <member>
+                <link linkend="evstr">evstr</link>
+            </member>
+            <member>
+                <link linkend="isnum">isnum</link>
+            </member>
+            <member>
+                <link linkend="isdigit">isdigit</link>
+            </member>
+            <member>
+                <link linkend="bin2dec">bin2dec</link>
+            </member>
+            <member>
+                <link linkend="oct2dec">oct2dec</link>
+            </member>
+            <member>
+                <link linkend="hex2dec">hex2dec</link>
+            </member>
+        </simplelist>
+    </refsection>
+    <refsection role="history">
+        <title>История</title>
+        <revhistory>
+            <revision>
+                <revnumber>5.5.0</revnumber>
+                <revremark>
+                    Введена опция decimalseparator (SEP 97).
+                </revremark>
+            </revision>
+            <revision>
+                <revnumber>5.4.1</revnumber>
+                <revremark>
+                    Если <varname>str</varname> не содержит никаких числовых значений, то теперь
+                    <varname>d</varname> возвращает <literal>Nan</literal> вместо <literal>0</literal>.
+                </revremark>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>