FileHandle
FileHandle クラスは、開かれた File オブジェクトから内容を順次読み出したり、追加したりするための関数を備えています。 FileHandle は、ドキュメントのどの部分にもアクセスすることができます。
FileHandle オブジェクトは file.open() 関数によって作成されます。
ドキュメント全体を一括で読み書きするには、file.getText() と file.setText() 関数の使用を検討されるとよいでしょう。
標準的な 4Dオブジェクトの 参照カウント により、FileHandle は参照されなくなると自動的に削除され、要求された File オブジェクトも自動的に閉じられます。 つまり、FileHandle を使えば、ドキュメントを閉じる必要がなくなります。
ドキュメントなどのオブジェクトリソースは、メモリ上で参照がなくなると解放されます。これはたとえば、メソッド実行終了時のローカル変数などで起こります。 任意の時点でオブジェクトリソースを "強制的に" 解放したい場合は、その参照を無効化 することができます。
例題
var $f : 4D.File
var $fhandle : 4D.FileHandle
$f:=Folder(Database folder).file("example.txt")
// 先頭から 1行ずつ書き込みます
$fhandle:=$f.open("write")
$text:="Hello World"
For ($line; 1; 4)
$fhandle.writeLine($text+String($line))
End for
// 終端から 1行ずつ追加で書き込みます
$fhandle:=$f.open("append")
$text:="Hello New World!"
For ($line; 1; 4)
$fhandle.writeLine($text+String($line))
End for
// オブジェクト引数を使い、読み取り停止文字を指定して読み取ります
$o:=New object()
$o.mode:="read"
$o.charset:="UTF-8"
$o.breakModeRead:=Document with CRLF
$stopChar:="!"
$fhandle:=$f.open($o)
$text:=$fhandle.readText($stopChar)
// 1行ずつ読み取ります
$lines:=New collection
$fhandle:=$f.open("read")
While (Not($fhandle.eof))
$lines.push($fhandle.readLine())
End while
FileHandle オブジェクト
FileHandle オブジェクトは共有できません。
| .breakModeRead : Text ファイル読み取り時に使用される改行の処理モードを返します |
| .breakModeWrite : Text ファイル書き込み時に使用される改行の処理モードを返します |
| .charset : Text ファイルの読み取りや書き込みに使用される文字セットを返します |
.eof : Booleanoffset がファイルの終端に達した場合に true、それ以外は false を返します |
| .file : 4D.File 作成された FileHandle の対象である 4D.File オブジェクトを格納します |
| .getSize() : Real ドキュメントの現在のサイズをバイト単位で返します |
| .mode : Text FileHandle が作成されたモード ("read"、"write"、"append" のいずれか) を返します |
| .offset : Real データストリームの現在のオフセット (ドキュメント内の位置) を返します |
| [.readBlob( bytes : Real ) : 4D.Blob ](#readblob) ファイルの現在の位置から bytes サイズの Blob を返します |
| .readLine() : Text 現在の位置から次の改行文字まで、あるいはドキュメントの終端に到達するまでのテキストを返します |
| .readText( { stopChar : Text } ) : Text 現在の位置から、最初の stopChar 文字列まで (渡された場合)、あるいはファイルの終端に達するまでのテキストを返します |
| .setSize( size : Real ) ドキュメントの新しいサイズをバイト単位で設定します |
| .writeBlob( blob : 4D.Blob ) ファイルの現在の位置から blob に渡した Blob を書き込みます |
| .writeLine( lineOfText : Text ) 現在の位置に lineOfText の内容を書き込み、改行文字を挿入します |
| .writeText( textToWrite : Text ) 現在の位置に textToWrite の内容を書き込み、改行文字は挿入しません |
.breakModeRead
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.breakModeRead : Text
説明
.breakModeRead プロパティは、ファイル読み取り時に使用される改行の処理モードを返します。
.breakModeRead プロパティは、FileHandle 作成時に file.open() 関数で定義できます (詳細については .open() 関数 を参照ください)。 デフォルトは "native" です。
.breakModeReadプロパティは、.open()のオプションが数値 (定数) を使って設定されていたとしても、常にテキスト値を格納します。
このプロパティは 読み取り専用 です。
.breakModeWrite
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.breakModeWrite : Text
説明
.breakModeWrite プロパティは、ファイル書き込み時に使用される改行の処理モードを返します。
.breakModeWrite プロパティは、FileHandle 作成時に file.open() 関数で定義できます (詳細については .open() 関数 を参照ください)。 デフォルトは "native" です。
.breakModeWriteプロパティは、.open()のオプションが数値 (定数) を使って設定されていたとしても、常にテキスト値を格納します。
このプロパティ は 読み取り専用 です。
.charset
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.charset : Text
説明
.charset プロパティは、ファイルの読み取りや書き込みに使用される文字セットを返します。
文字セットは、FileHandle 作成時に file.open() 関数で定義できます。 デフォルト値: "UTF-8"
このプロパティは 読み取り専用 です。
.eof
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.eof : Boolean
説明
.eof プロパティは、offset がファイルの終端に達した場合に true、それ以外は false を返します。
このプロパティは 読み取り専用 です。
.file
.file : 4D.File
説明
.file プロパティは、作成された FileHandle の対象である 4D.File オブジェクトを格納します。
このプロパティは 読み取り専用 です。
.getSize()
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.getSize() : Real
| 引数 | 型 | 説明 | |
|---|---|---|---|
| 戻り値 | 実数 | <- | ドキュメントのサイズ (バイト単位) |
説明
.getSize() 関数は、ドキュメントの現在のサイズをバイト単位で返します。
この関数は、
Fileクラスの .size プロパティと同じ値を返します。
参照
.mode
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.mode : Text
説明
.mode プロパティは、FileHandle が作成されたモード ("read"、"write"、"append" のいずれか) を返します。
モードは、FileHandle 作成時に file.open() 関数で定義できます。 デフォルトは "read" です。
このプロパティは 読み取り専用 です。
.offset
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.offset : Real
説明
.offset プロパティは、データストリームの現在のオフセット (ドキュメント内の位置) を返します。 オフセット値は、読み取りおよび書き込み操作の後に自動的に更新されます。
.offset を設定すると、次の読み取り・書き取り操作の際に、その現在値が変更されます。
- 負の値が渡された場合、
.offsetはファイルの先頭 (ゼロ) に設定されます。 - ファイルサイズより大きい値が渡された場合、
.offsetはファイルの終端 (ファイルサイズ) に設定されます。
読み書き可能 プロパティです。
FileHandle の作成時、.offset の値はバイト数です。 しかしながら、オフセットの単位は読み取り関数によって異なります。readBlob() の場合、.offset はバイト数ですが、readText()/readLine() の場合は文字数になります。 ファイルの文字セットに応じて、1文字は 1バイトまたは複数バイトに対応します。 したがって、readBlob() で読み取りを開始してから readText() を呼び出すと、テキストの読み取りは一貫性のない位置から開始されます。 そのため、同じ FileHandle内で、BLOB の読み取り/書き込みからテキストの読み取り/書き込みに切り替える場合には、.offset プロパティを自分で設定することが不可欠です。 例:
// utf-16エンコーディング (1文字につき 2バイト) を使用して、ヨーロッパのテキストファイルを開きます
// 最初の 10文字をバイトとして、残りをテキストとして読み込みます
$fh:=File("/RESOURCES/sample_utf_16.txt").open()
// 最初の 20バイト (=10文字) を読み取ります
$b:=$fh.readBlob(20) // $fh.offset=20
// 次にすでに読み取った 10文字を飛ばして残りのテキストをすべて読み取ります
// バイトからテキストの読み取りへと切り替えるため、オフセットの単位が変わります
// そのため、オフセットをバイトから文字数に変換する必要があります
$fh.offset:=10 // 最初の 10文字 (20バイト) の utf-16文字をスキップさせます
$s:=$fh.readText()
.readBlob()
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.readBlob( bytes : Real ) : 4D.Blob
| 引数 | 型 | 説明 | |
|---|---|---|---|
| bytes | 実数 | -> | 読み取るバイト数 |
| 戻り値 | 4D.Blob | <- | ファイルから読み取ったバイト |
説明
.readBlob() 関数は、ファイルの現在の位置から bytes サイズの Blob を返します。
この関数を実行すると、現在の位置 (.offset) が、最後に読み取ったバイトの後に更新されます。
参照
.readLine()
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.readLine() : Text
| 引数 | 型 | 説明 | |
|---|---|---|---|
| 戻り値 | テキスト | <- | 1行のテキスト |
説明
.readLine() 関数は、現在の位置から次の改行文字まで、あるいはドキュメントの終端に到達するまでのテキストを返します。
この関数を実行すると、現在の位置 (.offset) が更新されます。
この関数は、.offset プロパティがバイト数ではなく文字数であることを前提としています。 詳細については、.offset の説明 を参照ください。
この関数が FileHandle を対象に初めて実行されると、ドキュメント全体がバッファーに読み込まれます。
参照
.readText()
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.readText( { stopChar : Text } ) : Text
| 引数 | 型 | 説明 | |
|---|---|---|---|
| stopChar | テキスト | -> | 読み取りを停止する文字 |
| 戻り値 | テキスト | <- | ファイルのテキスト |
説明
.readText() 関数は、現在の位置から、最初の stopChar 文字列まで (渡された場合)、あるいはファイルの終端に達するまでのテキストを返します。
stopChar の文字列は、返されるテキストに含まれません。 stopChar を省略した場合、ドキュメント全体のテキストが返されます。
この関数を実行すると、.offset が stopChar 文字列の直後に移動します。
この関数は、.offset プロパティがバイト数ではなく文字数であることを前提としています。 詳細については、.offset の説明 を参照ください。
渡した stopChar が見つからない場合、.readText() は空の文字列を返し、.offset は更新されません。
この関数が FileHandle を対象に初めて実行されると、ドキュメント全体がバッファーに読み込まれます。
参照
.setSize()
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.setSize( size : Real )
| 引数 | 型 | 説明 | |
|---|---|---|---|
| size | 実数 | -> | ドキュメントの新しいサイズ (バイト単位) |
説明
.setSize() 関数は、ドキュメントの新しいサイズをバイト単位で設定します。
size の値が現在のドキュメントサイズより小さい場合、内容は先頭から切り捨てられ、新しい size が取得されます。
参照
.writeBlob()
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.writeBlob( blob : 4D.Blob )
| 引数 | 型 | 説明 | |
|---|---|---|---|
| blob | 4D.Blob | -> | ファイルに書き込む Blob |
説明
.writeBlob() 関数は、ファイルの現在の位置から blob に渡した Blob を書き込みます。
この関数を実行すると、現在の位置 (.offset) が、最後に書き込んだバイトの後に更新されます。
参照
.writeLine()
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.writeLine( lineOfText : Text )
| 引数 | 型 | 説明 | |
|---|---|---|---|
| lineOfText | テキスト | -> | 書き込むテキスト |
説明
.writeLine() 関数は、現在の位置に lineOfText の内容を書き込み、改行文字を挿入します (.writeText() 関数とは異なります)。 デフォルトではネイティブの改行文字が使用されますが、FileHandle を開く際に、.breakModeWrite プロパティを設定することで、別の改行文字を定義することができます。
この関数を実行すると、現在の位置 (.offset) が、最後に書き込んだ改行文字の後に更新されます。
参照
.breakModeWrite, .readLine(), .writeText()
.writeText()
履歴
| リリース | 内容 |
|---|---|
| 19 R7 | 追加 |
.writeText( textToWrite : Text )
| 引数 | 型 | 説明 | |
|---|---|---|---|
| textToWrite | テキスト | -> | 書き込むテキスト |
説明
.writeText() 関数は、現在の位置に textToWrite の内容を書き込み、改行文字は挿入しません (.writeLine() 関数とは異なります)。 デフォルトではネイティブの改行文字が使用されますが、FileHandle を開く際に、.breakModeWrite プロパティを設定することで、別の改行文字を定義することができます。
この関数を実行すると、現在の位置 (.offset) は、次の改行文字の後に更新されます。