このライブラリ file.TextFile は、汎用的なテキストファイル入出力の機能を提供します。
特に、CSV形式やTSV形式のファイル入出力をサポートします。
そもそもVCSSLでは、最初期のバージョンから、CSV形式やTSV形式を含む、基礎的なテキストファイル入出力機能が標準でサポートされています。
しかし、初期のVCSSLが専ら数値計算を目的とした言語であった事から、これらの機能も数値データファイルの入出力を前提とした仕様となっており、汎用的な用途においては不便な点もあります。
例えば、VCSSLの標準機能である System.open(string filePath, string mode) 関数でCSV形式やTSV形式のファイルを開く事ができますが、これは数値データファイルの操作を想定して設計された機能であるため、非常に単純な動作を行います。特別な記号のエスケープや、値を必要に応じてダブルクォーテーションで囲むなどの処理は行われません。
( その代わり、数値データファイルの入出力では高速に動作します。 )
そこで、このモジュールでは、数値データファイルのみならず、より汎用的なテキストファイル入出力機能を提供する事を目的としています。
例えば書き込みにおいては、値がカンマ(CSV時)やタブ(TSV時)などの区切り文字を含む場合、値全体がダブルクォーテーションで囲まれます。値が改行を含む場合も同様です。
読み込み時においても、ダブルクォーテーションで囲まれた部分は、まとめて一つの値として読み込まれ、その中に区切り文字や改行を含んでいても問題ありません。
また、書き込む値がダブルクォーテーションを含む場合は、連続したダブルクォーテーションにエスケープされます。
読み込み時においても、連続したダブルクォーテーションはエスケープされているものとして扱われます。
なお、このモジュールでは、一般的なCSV形式やTSV形式だけでなく、区切り文字(デリミタ)や引用符(エンクロージャ)の記号を明示的に指定する事も可能です。
定義 - Signature |
struct TextFile |
詳細 - Details |
テキストファイル構造体です。ファイルIDなどのシステムリソースや、区切り文字情報などを保持します。 |
定義 - Signature |
const string READ |
詳細 - Details |
汎用テキストファイルの「読み込み」モードです。区切り文字(デリミタ)及び引用符記号(エンクロージャ)は設定されません。引用符の挙動は ENCLOSED_NONE が適用されます。 |
定義 - Signature |
const string WRITE |
詳細 - Details |
汎用テキストファイルの「書き込み」モードです。区切り文字(デリミタ)及び引用符記号(エンクロージャ)は設定されません。引用符の挙動は ENCLOSED_NONE が適用されます。 |
定義 - Signature |
const string APPEND |
詳細 - Details |
汎用テキストファイルの「追記」モードです。区切り文字(デリミタ)及び引用符記号(エンクロージャ)は設定されません。引用符の挙動は ENCLOSED_NONE が適用されます。 |
定義 - Signature |
const string READ_TSV |
詳細 - Details |
TSV形式ファイルの「読み込み」モードです。区切り文字(デリミタ)はタブ記号、引用符記号(エンクロージャ)はダブルクォーテーションに設定されます。引用符の挙動は ENCLOSED_IF_NECESSARY が適用されます。 |
定義 - Signature |
const string WRITE_TSV |
詳細 - Details |
TSV形式ファイルの「書き込み」モードです。区切り文字(デリミタ)はタブ記号、引用符記号(エンクロージャ)はダブルクォーテーションに設定されます。引用符の挙動は ENCLOSED_IF_NECESSARY が適用されます。 |
定義 - Signature |
const string APPEND_TSV |
詳細 - Details |
TSV形式ファイルの「追記」モードです。区切り文字(デリミタ)はタブ記号、引用符記号(エンクロージャ)はダブルクォーテーションに設定されます。引用符の挙動は ENCLOSED_IF_NECESSARY が適用されます。 |
定義 - Signature |
const string READ_CSV |
詳細 - Details |
CSV形式ファイルの「読み込み」モードです。区切り文字(デリミタ)はカンマ記号、引用符記号(エンクロージャ)はダブルクォーテーションに設定されます。引用符の挙動は ENCLOSED_IF_NECESSARY が適用されます。 |
定義 - Signature |
const string WRITE_CSV |
詳細 - Details |
CSV形式ファイルの「書き込み」モードです。区切り文字(デリミタ)はカンマ記号、引用符記号(エンクロージャ)はダブルクォーテーションに設定されます。引用符の挙動は ENCLOSED_IF_NECESSARY が適用されます。 |
定義 - Signature |
const string APPEND_CSV |
詳細 - Details |
CSV形式ファイルの「追記」モードです。区切り文字(デリミタ)はカンマ記号、引用符記号(エンクロージャ)はダブルクォーテーションに設定されます。引用符の挙動は ENCLOSED_IF_NECESSARY が適用されます。 |
定義 - Signature |
const int ENCLOSED_ALL |
詳細 - Details |
全ての値を引用符記号(エンクロージャ)で囲むオプションです。 |
定義 - Signature |
const int ENCLOSED_IF_NECESSARY |
詳細 - Details |
必要な値のみ引用符記号(エンクロージャ)で囲むオプションです。CSV/TSV形式ファイルのデフォルト設定値です。 |
定義 - Signature |
const int ENCLOSED_NONE |
詳細 - Details |
どの値も引用符記号(エンクロージャ)で囲まないオプションです。汎用テキストファイルのデフォルト設定値です。 |
定義 - Signature |
TextFile openTextFile(string filePath, string mode) |
詳細 - Details |
ファイル名とモードを指定して、テキストファイルを開きます。モードは下記の定数から選択します。
|
引数 - Arguments |
filePath : ファイル名 mode : モード |
戻り値 - Return |
開いたファイルのテキストファイル構造体 |
定義 - Signature |
TextFile openTextFile(string filePath, string mode, string textEncoding) |
詳細 - Details |
ファイル名、モード、文字コードを指定して、テキストファイルを開きます。モードは下記の定数から選択します。
|
引数 - Arguments |
filePath : ファイル名 mode : モード encoding : 文字コード |
戻り値 - Return |
開いたファイルのテキストファイル構造体 |
定義 - Signature |
void close(TextFile &textFile) |
詳細 - Details |
テキストファイルへのアクセスを閉じます。特に書き込みアクセス後には、バッファされている内容を最後まで書き込み切るためにも、必ず呼び出す必要があります。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 |
定義 - Signature |
string getEndOfLineCode(TextFile &textFile) |
詳細 - Details |
ファイル入出力に使用する改行コードを取得します。読み込みモードでは、ファイルに使用されている改行コードを解析し、CR+LF, CR, LF の3つから適切と思われるものを返します。複数の改行コードが混在している場合は、優先度の高いほうから CR+LF, CR, LF の順番で判定します。それらのどれにも該当しない場合は NULL を返します。なお、setEndOfLineCode 関数で改行コードを明示指定した後は、その指定値が返されます。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 |
戻り値 - Return |
改行コード |
定義 - Signature |
void setEndOfLineCode(TextFile &textFile, string endOfLineCode) |
詳細 - Details |
ファイル入出力に使用する改行コードを指定します。改行コードの指定には、System ライブラリに定義されている、以下の定数を使用する事が推奨されます。
|
引数 - Arguments |
textFile : 対象のテキストファイル構造体 endOfLineCode : 改行コード |
定義 - Signature |
void setCommentLineCode(TextFile &textFile, string commentLineCode) |
詳細 - Details |
コメント行を表す行頭文字列を指定します。ここで指定した文字列で始まる行は、読み込み時に無視されます。また、commentln 関数でコメント行を出力する際に、ここで指定した文字列が使用されます。なお、読み込みモードの場合、この関数をコールした時点で、どこまでファイルを読み込んだかの情報は初期化されます。 この項目は、デフォルトでは何も設定されていないため、コメント行を考慮する際は必ず設定する必要があります。一般的によく用いられる行頭文字列は、以下のようなものがあります。
|
引数 - Arguments |
textFile : 対象のテキストファイル構造体 endOfLineCode : コメント行を表す行頭文字列 |
定義 - Signature |
string getCommentLineCode(TextFile &textFile) |
詳細 - Details |
コメント行を表す行頭文字列を返します。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 |
戻り値 - Return |
コメント行を表す行頭文字列 |
定義 - Signature |
bool isReadable(TextFile &textFile) |
詳細 - Details |
ファイルが読み込み可能な状態であるか確認します。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 |
戻り値 - Return |
読み込み可能なモードであればtrue |
定義 - Signature |
bool isWritable(TextFile &textFile) |
詳細 - Details |
ファイルが読み込み可能な状態であるか確認します。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 |
戻り値 - Return |
読み込み可能なモードであればtrue |
定義 - Signature |
void setDelimiter(TextFile &textFile, string delimiter) |
詳細 - Details |
値の区切り文字(デリミタ)を設定します。区切り文字を設定すると、 read 関数やreadln 関数が、値を区切って配列として返すようになります。一般的によく用いられる区切り文字は、以下のようなものがあります。また、write 関数やwritelnが、書き込み時に値を区切り文字で区切るようになります。
|
引数 - Arguments |
textFile : 対象のテキストファイル構造体 delimiter : 値の区切り文字(デリミタ) |
定義 - Signature |
void setEnclosure(TextFile &textFile, string enclosure, string enclosureEscapeCharacter, int enclosingOption) |
詳細 - Details |
値を囲む引用符記号(エンクロージャ)を設定します。引用符記号を設定すると、write 関数やwritelnが、書き込み時に値を引用符記号で囲むようになります。また、read 関数やreadln 関数が、読み込み時に引用符記号を解釈するようになります。 引用符記号は、enclosure に指定します。引数一般によく用いられる引用符記号は、以下のようなものがあります。
|
引数 - Arguments |
enclosure : 値を囲む引用符文字(エンクロージャ) enclosureEscapeCharacter : 値に引用符文字(エンクロージャ)が含まれる場合にエスケープする文字 enclosingOption : 囲み方のオプション |
定義 - Signature |
void write(TextFile &textFile, ... string value[ ]) |
詳細 - Details |
テキストファイルに文字列を書き込みます。複数の内容を指定した場合、区切り文字(デリミタ)が設定されていれば、間に区切り文字を挟んで書き出します。また、必要に応じて値を引用符で囲んで書き出します。引用符でどのように囲むかの設定は、setEnclosure で行います。 なお、最後の書き込み内容の末尾に、区切り文字は付加されません。従って、連続的に呼び出して書き込みを行う場合、必要に応じてdelimit 関数で区切り文字を挟む必要があります。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 value : 書き込む文字列(可変長引数のため複数指定可能) |
定義 - Signature |
void writeln(TextFile &textFile, ... string value[ ]) |
詳細 - Details |
テキストファイルに文字列を書き込み、改行します。複数の内容を指定した場合、区切り文字が設定されていれば、間に区切り文字を挟んで書き出します。また、必要に応じて値を引用符で囲んで書き出します。引用符でどのように囲むかの設定は、setEnclosure で行います。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 value : 書き込む文字列(可変長引数のため複数指定可能) |
定義 - Signature |
void delimit(TextFile &textFile) |
詳細 - Details |
テキストファイルに区切り文字を書き込みます。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 |
定義 - Signature |
void commentln(TextFile &textFile, string comment) |
詳細 - Details |
テキストファイルにコメント行を書き込みます。この関数をコールするよりも前に、setCommentLineCode 関数で、コメント行の行頭文字列を設定する必要があります。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 comment : コメント |
定義 - Signature |
string[ ] readln(TextFile &textFile) |
詳細 - Details |
テキストファイルから、一行分の内容を読み込みます。区切り文字(デリミタ)が設定されている場合、内容を区切り文字で区切り、配列として返します。ただし引用符(エンクロージャ)が設定されている場合、引用符で囲まれた内部にある区切り文字や改行は、値に含まれると解釈されます(ENCLOSED_NONEオプション時は除く)。引用符をどのように解釈するかの設定は、setEnclosure で行います。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 |
戻り値 - Return |
読み込んだ内容 |
定義 - Signature |
string[ ] read(TextFile &textFile) |
詳細 - Details |
テキストファイルから、全ての内容を読み込みます。区切り文字(デリミタ)が設定されている場合、内容を区切り文字または改行で区切り、配列として返します。ただし引用符(エンクロージャ)が設定されている場合、引用符で囲まれた内部にある区切り文字や改行は、値に含まれると解釈されます(ENCLOSED_NONEオプション時は除く)。引用符をどのように解釈するかの設定は、setEnclosure で行います。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 |
戻り値 - Return |
読み込んだ内容 |
定義 - Signature |
string loadln(TextFile &textFile) |
詳細 - Details |
ファイルから一行を読み込み、そのまま返します。ただし、引用符記号が設定されていて、引用符記号で囲まれた内部に改行がある場合、それは行末とは見なされません。ファイル内に複数の改行コードが混在している場合は、getEndOfLineCode 関数が返すものと同じ改行コードに統一されます。また、コメント行の行頭文字が設定されている場合、コメント行は読み飛ばされます。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 |
戻り値 - Return |
読み込んだ行の内容 |
定義 - Signature |
string load(TextFile &textFile) |
詳細 - Details |
ファイルから全行を読み込み、そのまま返します。ただし、コメント行の行頭文字が設定されている場合、コメント行は読み飛ばされます。なお、ファイル内に複数の改行コードが混在している場合は統一されます。ファイル内に複数の改行コードが混在している場合は、getEndOfLineCode 関数が返すものと同じ改行コードに統一されます。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 |
戻り値 - Return |
読み込んだ行の内容 |
定義 - Signature |
int countln(TextFile &textFile) |
詳細 - Details |
テキストファイルの有効行数をカウントします。引用符記号が設定されていない場合、有効行数はファイルの行数に一致します。引用符記号が設定されている場合は、引用符記号で囲まれた内部にある改行はカウントされません。つまり、CSV/TSV形式ファイルにおいては、値に含まれる改行はカウントされません。readln関数でCSV/TSV形式ファイルを読み込む場合、まずこの関数で有効行数を取得して下さい。この関数が返す有効行数を超えてreadln関数をコールする事はできません。 |
引数 - Arguments |
textFile : 対象のテキストファイル構造体 |
戻り値 - Return |
テキストファイルの有効行数 |