[doc] broken linkend fixed
[scilab.git] / scilab / modules / spreadsheet / help / ja_JP / csvRead.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="csvRead" xml:lang="ja"
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>csvRead</refname>
23         <refpurpose>CSVファイルを読み込む</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>呼び出し手順</title>
27         <synopsis>
28             M = csvRead(filename)
29             M = csvRead(filename, separator)
30             M = csvRead(filename, separator, decimal)
31             M = csvRead(filename, separator, decimal, conversion)
32             M = csvRead(filename, separator, decimal, conversion, substitute)
33             M = csvRead(filename, separator, decimal, conversion, substitute, regexpcomments, range)
34             M = csvRead(filename, separator, decimal, conversion, substitute, regexpcomments, range, header)
35             [M, comments] = csvRead(filename, separator, decimal, conversion, substitute, regexpcomments, range, header)
36         </synopsis>
37     </refsynopsisdiv>
38     <refsection>
39         <title>引数</title>
40         <variablelist>
41             <varlistentry>
42                 <term>filename</term>
43                 <listitem>
44                     <para>1行1列の文字列行列で,ファイルパスです.</para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>separator</term>
49                 <listitem>
50                     <para>1行1列の文字列行列で,
51                         使用されるフィールドセパレータ.
52                     </para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>decimal</term>
57                 <listitem>
58                     <para>
59                         1行1列の文字列行列で,使用される小数点.
60                     </para>
61                     <para>
62                         <literal>decimal</literal> が <literal>[]</literal>
63                         と異なり
64                         <literal>conversion</literal> が <literal>string</literal>に
65                         設定された場合,小数点変換が行われます.
66                     </para>
67                 </listitem>
68             </varlistentry>
69             <varlistentry>
70                 <term>conversion</term>
71                 <listitem>
72                     <para>
73                         1行1列の文字列行列で,出力<literal>M</literal>の型.
74                         利用可能な値は "string" または "double"
75                         (デフォルト)です.
76                     </para>
77                     <para>
78                         <link linkend="read_csv">read_csv</link> では "string" がデフォルトであることに
79                         注意してください.
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>substitute</term>
85                 <listitem>
86                     <para>
87                         m行2列の文字列行列で,
88                         置換マップ(デフォルト = [], 置換処理なし).
89                         最初の列
90                         <literal>substitute(:,1)</literal> は
91                         検索する文字列を有し,
92                         2番目の列
93                         <literal>substitute(:,2)</literal> は置換文字列を
94                         有します.
95                         ファイル中に指定された文字列が現れる度に
96                         置換が行われます.
97                     </para>
98                 </listitem>
99             </varlistentry>
100             <varlistentry>
101                 <term>rexgepcomments</term>
102                 <listitem>
103                     <para>文字列: 一致する行を削除するための正規表現.
104                         (デフォルト:
105                         [])
106                     </para>
107                 </listitem>
108             </varlistentry>
109             <varlistentry>
110                 <term>range</term>
111                 <listitem>
112                     <para>1行4列の浮動小数点の整数行列で,
113                         読み込む列および行の範囲です
114                         (デフォルトの範囲は [] で,全ての行と列を意味します).
115                         <literal>[R1 C1 R2 C2]</literal>の形式で範囲を
116                         指定してください.
117                         ただし,(R1,C1)は読み込むデータの左上隅,
118                         (R2,C2)は右下隅です.
119                     </para>
120                     <para>
121                         <note>
122                             ファイルが正しく整形されていることに注意してください.
123                             この範囲はパースされた要素についてメモリ上で実行されます.
124                         </note>
125                     </para>
126                 </listitem>
127             </varlistentry>
128             <varlistentry>
129                 <term>header</term>
130                 <listitem>
131                     <para>
132                         1行1列の行列の浮動小数点整数, ファイルの先頭で無視される行の数.
133                     </para>
134                 </listitem>
135             </varlistentry>
136             <varlistentry>
137                 <term>M</term>
138                 <listitem>
139                     <para>m行n列の文字列またはdouble行列.</para>
140                 </listitem>
141             </varlistentry>
142             <varlistentry>
143                 <term>comments</term>
144                 <listitem>
145                     <para>正規表現にマッチしたm行n列の文字列行列.</para>
146                 </listitem>
147             </varlistentry>
148         </variablelist>
149     </refsection>
150     <refsection>
151         <title>説明</title>
152         <para>
153             カンマ区切りの値をフィールドとするアスキーファイルを指定すると,
154             この関数は対応する文字列またはdoubleのScilab行列を返します.
155         </para>
156         <para>
157             例えば,.csvデータファイルは
158             表計算ソフトウェアにより"テキスト及びカンマ"形式で
159             作成されたものとすることができます.
160         </para>
161         <para>
162             列はカンマ以外で区切られたものとすることもできます.
163             この場合, 別のセパレータを指定する
164             csvRead(filename, separator) を使用してください.
165         </para>
166         <para>
167             オプションの入力引数のデフォルト値は,
168             <literal>csvDefault</literal> 関数で定義されます.
169         </para>
170         <para>
171             オプションの入力引数に空の行列<literal>[]</literal>を指定すると,
172             デフォルト値が設定されます.
173         </para>
174         <para>
175             入力引数 "conversion" が "double" の時,
176             .csvの中の数値以外のフィールド(例:文字列)は NaNに変換されます.
177         </para>
178         <para>csvRead は UTF-8 および ASCII テキストファイルを読み込むことができます.
179         </para>
180     </refsection>
181     <refsection>
182         <title>例</title>
183         <para>
184             以下のスクリプトは,
185             <literal>csvRead</literal>関数のいくつかの基本的な使用例を示します.
186         </para>
187         <programlisting role="example"><![CDATA[// タブ区切りのデータを含むファイルを生成
188 M = 1:50;
189 filename = fullfile(TMPDIR, "data.csv");
190 csvWrite(M, filename, ascii(9), '.');
191 // csvファイルを読み込む
192 M1 = csvRead(filename,ascii(9), [], 'string')
193 // doubleを返す
194 M2 = csvRead(filename,ascii(9), '.', 'double')
195 // 元のデータを結果と比較
196 and(M == M2)
197 // 特殊なデータファイルを管理するために
198 // 置換用引数を使用
199 content = [
200 "1"
201 "Not-A-Number"
202 "2"
203 "Not-A-Number"
204 ];
205 substitute = [
206 "Not-A-Number" "Nan"
207 ];
208 mputl(content,filename);
209 M = csvRead(filename,",",".","double",substitute)
210 isnan(M(2,1)) // Expected=%t
211 isnan(M(4,1)) // Expected=%t
212         ]]></programlisting>
213         <para>
214             以下のスクリプトは,
215             <literal>csvRead</literal>関数のより実用的な使用例を示します.
216         </para>
217         <programlisting role="example"><![CDATA[// 文字列の行列を定義
218 Astr = [
219 "1" "8" "15" "22" "29" "36" "43" "50"
220 "2" "9" "16" "23" "30" "37" "44" "51"
221 "3" "10" "17" "6+3*I" "31" "38" "45" "52"
222 "4" "11" "18" "25" "32" "39" "46" "53"
223 "5" "12" "19" "26" "33" "40" "47" "54"
224 "6" "13" "20" "27" "34" "41" "48" "55"
225 "+0" "-0" "Inf" "-Inf" "Nan" "1.D+308" "1.e-308" "1.e-323"
226 ];
227 // カンマ区切りのデータを有するファイルを作成
228 filename = fullfile(TMPDIR , 'foo.csv');
229 sep = ",";
230 fd = mopen(filename,'wt');
231 for i = 1 : size(Astr,"r")
232         mfprintf(fd,"%s\n",strcat(Astr(i,:),sep));
233 end
234 mclose(fd);
235 // ファイルを参照するには: edit(filename)
236 // このファイルを読み込む
237 Bstr = csvRead ( filename )
238 // 特殊なセパレータを有するファイルを作成: ここでは ";"
239 filename = fullfile(TMPDIR , 'foo.csv');
240 sep = ";";
241 fd = mopen(filename,'wt');
242 for i = 1 : size(Astr,"r")
243         mfprintf(fd,"%s\n",strcat(Astr(i,:),sep));
244 end
245 mclose(fd);
246 //
247 // セパレータを指定してファイルを読み込む
248 csvRead ( filename , sep )
249         ]]></programlisting>
250         <para>
251             以下のスクリプトは
252             <literal>csvRead</literal> 関数のregexp引数により
253             行を削除する例を示します.
254         </para>
255         <programlisting role="example"><![CDATA[
256 CSV = ["// tata"; ..
257 "1,0,0,0,0"; ..
258 "// titi"; ..
259 "0,1,0,0,0"; ..
260 "// toto"; ..
261 "0,0,1,0,0"; ..
262 "// tutu"];
263 filename = fullfile(TMPDIR , 'foo.csv');
264 mputl(CSV, filename);
265 // @ で始まる行を削除
266 [M, comments] = csvRead(filename, [], [], [], [], '/\/\//')
267         ]]></programlisting>
268     </refsection>
269     <refsection>
270         <para>空のフィールドはcsvReadで管理されます</para>
271         <programlisting role="example"><![CDATA[
272 csvWrite(['1','','3';'','','6'], TMPDIR + "/example.csv")
273 csvRead(TMPDIR + "/example.csv", [], [], "string")
274 csvRead(TMPDIR + "/example.csv", [], [], "double")
275         ]]></programlisting>
276     </refsection>
277     <programlisting role="example"><![CDATA[
278 // 文字列の行列を定義
279 Astr = [
280 "1" "8" "15" "22" "29" "36" "43" "50"
281 "2" "9" "16" "23" "30" "37" "44" "51"
282 "3" "10" "17" "6+3*I" "31" "38" "45" "52"
283 "4" "11" "18" "25" "32" "39" "46" "53"
284 "5" "12" "19" "26" "33" "40" "47" "54"
285 "6" "13" "20" "27" "34" "41" "48" "55"
286 "+0" "-0" "Inf" "-Inf" "Nan" "1.D+308" "1.e-308" "1.e-323"
287 ];
288 // カンマ区切りのデータを有するファイルを作成
289 filename = fullfile(TMPDIR , 'foo.csv');
290 sep = ",";
291 fd = mopen(filename,'wt');
292 for i = 1 : size(Astr,"r")
293         mfprintf(fd,"%s\n",strcat(Astr(i,:),sep));
294 end
295 mclose(fd);
296 // ファイルを参照するには: edit(filename)
297 // このファイルを読み込む
298 Bstr = csvRead ( filename )
299 // 特殊なセパレータを有するファイルを作成: ここでは ";"
300 filename = fullfile(TMPDIR , 'foo.csv');
301 sep = ";";
302 fd = mopen(filename,'wt');
303 for i = 1 : size(Astr,"r")
304         mfprintf(fd,"%s\n",strcat(Astr(i,:),sep));
305 end
306 mclose(fd);
307 //
308 // セパレータを指定してファイルを読み込む
309 csvRead ( filename , sep )
310     ]]></programlisting>
311     <refsection>
312         <para>
313             以下のスクリプトでは, ファイル "filename" は
314             5000行単位のブロックで読みこまれます.
315             実際に読み込まれたファイルの行数が5000行に
316             満たない時, すなわち, ファイルの終端に達した時,
317             このアルゴリズムは中断します.
318         </para>
319         <programlisting role="example"><![CDATA[blocksize = 5000;
320 C1 = 1;
321 C2 = 3;
322 iblock = 1
323 while (%t)
324 R1 = (iblock-1) * blocksize + 1;
325 R2 = blocksize + R1-1;
326 irange = [R1 C1 R2 C2];
327 mprintf("Block #%d, rows #%d to #%d\n",iblock,R1,R2);
328 tic();
329 M=csvRead(filename , [] , [] , [] , [] , [] , irange );
330 t = toc();
331 nrows = size(M,"r");
332 ncols = size(M,"c");
333 if ( nrows &gt; 0 ) then
334 p = t/(nrows*ncols)*1.e6;
335 mprintf("  Actual #rows=%d\n",nrows);
336 mprintf("  T=%.3f (s)\n",t);
337 mprintf("  T=%.1f (ms/cell)\n",p);
338 end
339 if ( nrows &lt; blocksize ) then
340 mprintf("... End of the file.\n");
341 break
342 end
343 iblock = iblock + 1;
344 end
345         ]]></programlisting>
346         <para>出力は以下のようになります :</para>
347         <programlisting role="no-scilab-exec"><![CDATA[Block #1, rows #1 to #5000
348 Actual #rows=5000
349 T=3.135 (s)
350 T=209.0 (ms/cell)
351 Block #2, rows #5001 to #10000
352 Actual #rows=5000
353 T=3.139 (s)
354 T=209.3 (ms/cell)
355 Block #3, rows #10001 to #15000
356 Actual #rows=5000
357 T=3.151 (s)
358 T=210.1 (ms/cell)
359 etc....
360         ]]></programlisting>
361         範囲を有する例
362         <programlisting role="example"><![CDATA[
363 CSV = ["1,0,0,0,0"; ..
364 "0,1,0,0,0"; ..
365 "0,0,1,0,0"; ..
366 "4,4,1,2,0"; ..
367 "4,63,1,2,0"; ..
368 "4,63,1,4,233"; ..
369 "42,3,23,2,23"; ..
370 ];
371 filename = fullfile(TMPDIR , 'foo.csv');
372 mputl(CSV, filename);
373 // csvファイルの一部を展開
374 csvRead(filename, [], [], "double", [], [], [5 3 7 6])
375     ]]></programlisting>
376         ヘッダを有する例
377         <programlisting role="example"><![CDATA[
378 comments = [
379 "// Copyright (C) INRIA"];
380 filename = fullfile(TMPDIR , 'foo.csv');
381 csvWrite(rand(2,3), filename, ascii(9), ",", [], comments);
382 header = 2;
383 [M, c] = csvRead(filename, ascii(9), ",", "double", [], [], [], header) // 最初の2行(ヘッダ)を無視
384     ]]></programlisting>
385     </refsection>
386     <refsection role="see also">
387         <title>参照</title>
388         <simplelist type="inline">
389             <member>
390                 <link linkend="csvTextScan">csvTextScan</link>
391             </member>
392             <member>
393                 <link linkend="csvWrite">csvWrite</link>
394             </member>
395             <member>
396                 <link linkend="csvDefault">csvDefault</link>
397             </member>
398         </simplelist>
399     </refsection>
400     <refsection>
401         <title>履歴</title>
402         <revhistory>
403             <revision>
404                 <revnumber>5.4.0</revnumber>
405                 <revremark>関数が導入されました.
406                     'csv_readwrite'モジュールに基づきます.
407                     <link linkend="read_csv">read_csv</link> と比べた場合の
408                     動作の唯一の差異は,
409                     read_csvが値を文字列として返す時,デフォルトで値をdoubleに変換しようとする
410                     ことです.
411                 </revremark>
412             </revision>
413             <revision>
414                 <revnumber>5.4.1</revnumber>
415                 <revremark>
416                     <literal>decimal</literal> が <literal>[]</literal> 以外で,
417                     <literal>conversion</literal> が <literal>string</literal>に設定された場合,
418                     小数点変換が行われます.
419                 </revremark>
420             </revision>
421             <revision>
422                 <revnumber>5.5</revnumber>
423                 <revremark>
424                     ヘッダを無視するために,入力引数"header"が追加されました.
425                 </revremark>
426             </revision>
427         </revhistory>
428     </refsection>
429 </refentry>