[doc] mputstr() page overhauled
[scilab.git] / scilab / modules / fileio / help / en_US / mputstr.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) 2008 - INRIA
5  * ...
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  * Copyright (C) 2020 - Samuel GOUGEON
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="mputstr">
20     <refnamediv>
21         <refname>mputstr</refname>
22         <refpurpose>write a single text in an open file</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             mputstr(str)
28             mputstr(str, fid)
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>fid</term>
36                 <listitem>
37                     <para>
38                         integer: file identifier returned by <literal>mopen(…)</literal>.
39                         <literal>-1</literal> (default) stands for the last opened file.
40                     </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>str</term>
45                 <listitem>
46                     <para>
47                         Single text to write in the file. Multilingual UTF-8 characters are accepted.
48                         <varname>str</varname> can include special formatting characters
49                         like ascii(9) (tab), ascii(10) (newline) and ascii(13) (carriage return).
50                         Sequences like "\t", "\n" and "\r" have no special meaning and are written as is.
51                     </para>
52                 </listitem>
53             </varlistentry>
54         </variablelist>
55     </refsection>
56     <refsection>
57         <title>Description</title>
58         <para>
59             <literal>mputstr(…)</literal> writes a character string <varname>str</varname>
60             in a binary or text file. <varname>str</varname> is buffered: It is actually
61             written in the file only when closing this one.
62         </para>
63     </refsection>
64     <refsection>
65         <title>Examples</title>
66         <programlisting role="example"><![CDATA[
67 myFile = tempname();
68 fid = mopen(myFile, "wt");
69
70 mputstr("Scilab", fid);
71 mgetl(myFile) // => []. "Scilab" has been buffered
72 mputstr(" and Xcos", fid);
73 mgetl(myFile) // => still []. " and Xcos" added to the buffer
74
75 // Only one text can be sent at a once:
76 mputstr(["Science" ; "Innovation"], fid);     // => error
77
78 mclose(fid);
79 mgetl(myFile) // => "Scilab and Xcos"
80 mdelete(myFile);
81      ]]></programlisting>
82         <para/>
83         <screen><![CDATA[
84 --> mputstr("Scilab", fid);
85 --> mgetl(myFile) // => []. "Scilab" has been buffered
86  ans  =
87     []
88
89 --> mputstr(" and Xcos", fid);
90 --> mgetl(myFile) // => still []. " and Xcos" added to the buffer
91  ans  =
92     []
93
94 --> // Only one text can be sent:
95 --> mputstr(["Science" ; "Innovation"], fid);    // => error
96 mputstr: Argument #1: Scalar (1 element) expected.
97
98 --> mclose(fid);
99 --> mgetl(myFile)
100  ans  =
101   "Scilab and Xcos"
102 ]]></screen>
103         <para/>
104         <para>
105             Use UTF-8 and special formatting characters:
106         </para>
107         <programlisting role="example"><![CDATA[
108 [tab, nl] = (ascii(9), ascii(10));
109 myFile = tempname();
110 fid = mopen(myFile, "wt");
111
112 mputstr("Επιστήμη", fid);
113 mputstr(ascii(10), fid);      // Line feed
114 mputstr("Τεχνολογία" + nl, fid);
115 mputstr(tab, fid);           // Heading tab
116 mputstr("innovation", fid);
117 mputstr(nl + "Science" + nl + tab + "technology", fid);
118 mclose(fid);
119 mgetl(myFile)
120
121 mdelete(myFile);
122  ]]></programlisting>
123     <screen><![CDATA[
124 --> mputstr("Επιστήμη", fid);
125 --> mputstr(ascii(10), fid);      // Line feed
126 --> mputstr("Τεχνολογία" + nl, fid);
127 --> mputstr(tab, fid);           // Heading tab
128 --> mputstr("innovation", fid);
129 --> mputstr(nl + "Science" + nl + tab + "technology", fid);
130 --> mclose(fid);
131 --> mgetl(myFile)
132  ans  =
133   "Επιστήμη"
134   "Τεχνολογία"
135   "        innovation"
136   "Science"    
137   "        technology"
138 ]]></screen>
139     </refsection>
140     <refsection role="see also">
141         <title>See also</title>
142         <simplelist type="inline">
143             <member>
144                 <link linkend="mgetstr">mgetstr</link>
145             </member>
146             <member>
147                 <link linkend="mputl">mputl</link>
148             </member>
149             <member>
150                 <link linkend="mgetl">mgetl</link>
151             </member>
152             <member>
153                 <link linkend="mput">mput</link>
154             </member>
155             <member>
156                 <link linkend="mfprintf">mfprintf</link>
157             </member>
158             <member>
159                 <link linkend="save">save</link>
160             </member>
161             <member>
162                 <link linkend="write">write</link>
163             </member>
164             <member>
165                 <link linkend="csvWrite">csvWrite</link>
166             </member>
167         </simplelist>
168     </refsection>
169 </refentry>