[doc] broken linkend fixed
[scilab.git] / scilab / modules / spreadsheet / help / en_US / csvWrite.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Copyright (C) 2010-2011 - INRIA - Allan CORNET
4  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  *
7  * This file is hereby licensed under the terms of the GNU GPL v2.0,
8  * pursuant to article 5.3.4 of the CeCILL v.2.1.
9  * This file was originally licensed under the terms of the CeCILL v2.1,
10  * and continues to be available under such terms.
11  * For more information, see the COPYING file which you should have received
12  * along with this program.
13  -->
14 <refentry version="5.0-subset Scilab" xml:id="csvWrite" xml:lang="en"
15         xmlns="http://docbook.org/ns/docbook"
16         xmlns:xlink="http://www.w3.org/1999/xlink"
17         xmlns:svg="http://www.w3.org/2000/svg"
18         xmlns:ns3="http://www.w3.org/1999/xhtml"
19         xmlns:mml="http://www.w3.org/1998/Math/MathML"
20         xmlns:db="http://docbook.org/ns/docbook">
21     <refnamediv>
22         <refname>csvWrite</refname>
23         <refpurpose>Write comma-separated value file</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             csvWrite(M, filename)
29             csvWrite(M, filename, separator)
30             csvWrite(M, filename, separator, decimal)
31             csvWrite(M, filename, separator, decimal, precision)
32             csvWrite(M, filename, separator, decimal, precision, comments)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>filename</term>
40                 <listitem>
41                     <para>a 1-by-1 matrix of strings, the file path.</para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>M</term>
46                 <listitem>
47                     <para>a m-by-n matrix of strings or double (complex
48                         supported).
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>separator</term>
54                 <listitem>
55                     <para>a 1-by-1 matrix of strings, the column separator mark.</para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>decimal</term>
60                 <listitem>
61                     <para>a 1-by-1 matrix of strings, the decimal mark. The available
62                         values are "." or ",".
63                     </para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>precision</term>
68                 <listitem>
69                     <para>a 1-by-1 matrix of strings, the C format.</para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>comments</term>
74                 <listitem>
75                     <para>a m-by-1 matrix of strings, the comments stored at the
76                         beginning of the file. This option may be used, for example, to put
77                         a licence header in a data file.
78                     </para>
79                 </listitem>
80             </varlistentry>
81         </variablelist>
82     </refsection>
83     <refsection>
84         <title>Description</title>
85         <para>This function writes matrix M into filename as comma-separated
86             values.
87         </para>
88         <para>The default value of the optional input arguments are defined by the
89             <literal>csvDefault</literal> function.
90         </para>
91         <para>Any optional input argument equal to the empty matrix
92             <literal>[]</literal> is set to its default value.
93         </para>
94         <para>
95             If the file <literal>filename</literal> already exists, it is
96             overwritten.
97         </para>
98         <para>
99             If relevant (ie with 'special' characters), the file will be saved as UTF-8.
100         </para>
101     </refsection>
102     <refsection>
103         <title>Examples</title>
104         <para>In the following example, we combine the
105             <literal>csvWrite</literal> and <literal>csvRead</literal>
106             functions.
107         </para>
108         <programlisting role="example"><![CDATA[// Save a matrix as csv file format
109 M = [1:10] * 0.1;
110 filename = fullfile(TMPDIR, "data.csv");
111 csvWrite(M, filename);
112
113 // Read as text
114 mgetl(filename)
115
116 r = csvRead(filename);
117         ]]></programlisting>
118         <para>In the following example, we use various options of the
119             <literal>csvWrite</literal> function.
120         </para>
121         <programlisting role="example"><![CDATA[// Save a matrix as csv file format
122 M = rand(2,3);
123 filename = fullfile(TMPDIR, "data.csv");
124 //
125 // Use tabs as the separator
126 csvWrite(M, filename,ascii(9));
127 mgetl(filename)
128 //
129 // Use the "," as the decimal point
130 // (and blank space as the separator).
131 csvWrite(M, filename," ",",");
132 mgetl(filename)
133 //
134 // Configure the precision.
135 // Caution: this lower precision may generate
136 // errors in a write-read cycle!
137 csvWrite(M, filename,[],[],"%.8e");
138 mgetl(filename)
139 //
140 // Configure the comments
141 comments = [
142 "// Copyright (C) INRIA"
143 ];
144 csvWrite(M, filename,[],[],[],comments);
145 mgetl(filename)
146         ]]></programlisting>
147         <para>The following examples are more advanced uses of the
148             <literal>csvWrite</literal> function.
149         </para>
150         <programlisting role="example"><![CDATA[A = [
151 1 0 200 %inf 0
152 1 1.e-300 200 %inf 0
153 9.99999999999990010e-001 9.99999999999999980e-201 200 3.15e300 102
154 9.99999999899999990e-001 1.e-100 200 296 117
155 1 %inf -%inf %nan 0
156 ];
157
158 // Write into a file
159 filename=fullfile(TMPDIR,"foo.csv");
160 csvWrite ( A , filename );
161 edit(filename)
162     ]]></programlisting>
163     </refsection>
164     <refsection role="see also">
165         <title>See also</title>
166         <simplelist type="inline">
167             <member>
168                 <link linkend="csvRead">csvRead</link>
169             </member>
170             <member>
171                 <link linkend="csvTextScan">csvTextScan</link>
172             </member>
173             <member>
174                 <link linkend="csvDefault">csvDefault</link>
175             </member>
176         </simplelist>
177     </refsection>
178     <refsection>
179         <title>History</title>
180         <revhistory>
181             <revision>
182                 <revnumber>5.4.0</revnumber>
183                 <revremark>Function introduced. Based on the 'csv_readwrite' module.</revremark>
184             </revision>
185         </revhistory>
186     </refsection>
187 </refentry>