Saltar para o conteúdo principal
Versão: 20 R5 BETA

FileHandle

The FileHandle class has functions that allow you to sequentially read from or append contents to an opened File object. O manuseamento de um arquivo pode acessar a qualquer parte de um documento.

File handle objects are created with the file.open() function.

To read or write a whole document at once, you might consider using the file.getText() and file.setText() functions.

Thanks to the standard 4D object refcounting, a file handle is automatically deleted when it is no longer referenced and thus, the requested File object is automatically closed. Consequentemente, com os handles dos arquivos não precisa de se preocupar com o encerramento de documentos.

nota

Os recursos de um objeto, como documentos, são liberados quando não existem mais referências na memória, que acontece, por exemplo, no final do método de execução das variáveis locais. If you want to "force" the release of object resources at any moment, you can nullify its references.

Exemplo

var $f : 4D.File
var $fhandle : 4D.FileHandle
$f:=Folder(Database folder).file("example.txt")

//Writing line by line from the start
$fhandle:=$f.open("write")
$text:="Hello World"
For ($line; 1; 4)
$fhandle.writeLine($text+String($line))
End for

//Writing line by line from the end
$fhandle:=$f.open("append")
$text:="Hello New World!"
For ($line; 1; 4)
$fhandle.writeLine($text+String($line))
End for

//Reading using a stop character and an object parameter
$o:=New object()
$o.mode:="read"
$o.charset:="UTF-8"
$o.breakModeRead:=Document with CRLF
$stopChar:="!"
$fhandle:=$f.open($o)
$text:=$fhandle.readText($stopChar)

//Reading line by line
$lines:=New collection
$fhandle:=$f.open("read")
While (Not($fhandle.eof))
$lines.push($fhandle.readLine())
End while

Objeto FileHandle

Os objectos handle de arquivos não podem ser partilhados.

.breakModeRead : Text
the processing mode for line breaks used when reading the file
.breakModeWrite : Text
the processing mode for line breaks used when writing to the file
.charset : Text
the charset used when reading from or writing to the file
.eof : Boolean
True is the offset has reached the end of the file, and False otherwise
.file : 4D.File
the 4D.File object on which the handle has been created
.getSize() : Real
returns the current size of the document, expressed in bytes
.mode : Text
the mode in which the file handle was created: "read", "write", or "append"
.offset : Real
the current offset of the data stream (position inside the document)
.readBlob( bytes : Real ) : [4D.Blob](BlobClass)
returns a blob a bytes size from the file, starting from the current position
.readLine() : Text
returns a line of text from the current position until an end-of-line delimiter is encountered or the end of the document is reached
.readText( { stopChar : Text } ) : Text
returns text from the file, starting from the current position until the first stopChar string is encountered (if passed) or the end of file is reached
.setSize( size : Real )
sets a new size in bytes for the document
.writeBlob( blob : 4D.Blob )
writes blob into the file, starting from the current position
.writeLine( lineOfText : Text )
writes lineOfText content at the current position and inserts an end-of-line delimiter
.writeText( textToWrite : Text )
writes textToWrite content at the current position and does not insert a final end-of-line delimiter

.breakModeRead

História
ReleaseMudanças
18 R6Adicionado

.breakModeRead : Text

Descrição

The .breakModeRead property returns the processing mode for line breaks used when reading the file.

The .breakModeRead property can be defined at the handle creation with the file.open() function (see the .open() function for more information). O padrão é "nativo".

The .breakModeRead property always contains a text value, even if the .open() option was set using a number (constant).

Essa propriedade é somente leitura.

.breakModeWrite

História
ReleaseMudanças
18 R6Adicionado

.breakModeWrite : Text

Descrição

The .breakModeWrite property returns the processing mode for line breaks used when writing to the file.

The .breakModeWrite property can be defined at the handle creation with the file.open() function (see the .open() function for more information). O padrão é "nativo".

The .breakModeWrite property always contains a text value, even if the .open() option was set using a number (constant).

Essa propriedade é somente leitura.

.charset

História
ReleaseMudanças
18 R6Adicionado

.charset : Text

Descrição

The .charset property returns the charset used when reading from or writing to the file.

The charset can be defined at the handle creation with the file.open() function. Por padrão é "UTF-8".

Essa propriedade é somente leitura.

.eof

História
ReleaseMudanças
18 R6Adicionado

.eof : Boolean

Descrição

The .eof property returns True is the offset has reached the end of the file, and False otherwise.

Essa propriedade é somente leitura.

.file

.file : 4D.File

Descrição

The .file property returns the 4D.File object on which the handle has been created.

Essa propriedade é somente leitura.

.getSize()

História
ReleaseMudanças
18 R6Adicionado

.getSize() : Real

ParâmetroTipoDescrição
ResultadosReal<-Tamanho do documento em bytes

Descrição

The .getSize() function returns the current size of the document, expressed in bytes.

This function returns the same value as the (.size) property of the File class.

Veja também

.setSize(), file.size

.mode

História
ReleaseMudanças
18 R6Adicionado

.mode : Text

Descrição

The .mode property returns the mode in which the file handle was created: "read", "write", or "append".

The mode can be defined at the handle creation with the file.open() function. O padrão é "read".

Essa propriedade é somente leitura.

.offset

História
ReleaseMudanças
18 R6Adicionado

.offset : Real

Descrição

The .offset property returns the current offset of the data stream (position inside the document). O valor do offset é automaticamente atualizado após as operações de leitura e escrita.

Setting the .offset will change its current value at the moment of the next read or write operation.

  • If the passed value is negative, the .offset is set to the start of the file (zero).
  • If the passed value is higher than the size of the file, the .offset is set to the end of the file (size of file).

This property is read/write.

caution

When a file handle is created, the .offset value is a number of bytes. However, the unit of offset measurement differs according to the reading function: with readBlob(), .offset is a number of bytes, whereas with readText()/readLine() it is a number of characters. Dependendo do conjunto de caracteres do arquivo, um caractere corresponde a um ou mais bytes. So, if you start reading with readBlob() and then call readText(), text reading will start at an inconsistent position. It is therefore essential to set the .offset property yourself if you switch from reading/writing blob to reading/writing text in the same filehandle. Por exemplo:

  // Open a european text file using utf-16 encoding (two bytes per character)
// We want to read the first 10 characters as bytes, then the remaining as text.
$fh:=File("/RESOURCES/sample_utf_16.txt").open()
// read the 20 first bytes (i.e. 10 characters)
$b:=$fh.readBlob(20) // $fh.offset=20
// then read all text skipping the first 10 characters we just read in previous blob
// because we are now reading text instead of bytes, the meaning of 'offset' is not the same.
// We need to translate it from bytes to characters.
$fh.offset:=10 // ask to skip 10 utf-16 characters (20 bytes)
$s:=$fh.readText()

.readBlob()

História
ReleaseMudanças
18 R6Adicionado

.readBlob( bytes : Real ) : 4D.Blob

ParâmetroTipoDescrição
bytesReal->Número de bytes a ler
Resultados4D.Blob<-Bytes lidos do arquivo

Descrição

The .readBlob() function returns a blob a bytes size from the file, starting from the current position .

When this function is executed, the current position (.offset) is updated after the last byte read.

Veja também

.writeBlob()

.readLine()

História
ReleaseMudanças
18 R6Adicionado

.readLine() : Text

ParâmetroTipoDescrição
ResultadosText<-Linha de texto

Descrição

The .readLine() function returns a line of text from the current position until an end-of-line delimiter is encountered or the end of the document is reached.

When this function is executed, the current position (.offset) is updated.

Aviso

This function assumes that the .offset property is a number of characters, not a number of bytes. For more information, see the .offset description.

Quando esta função é executada pela primeira vez num handle de arquivo, todo o conteúdo do documento é carregado num buffer.

Veja também

.readText(), .writeLine()

.readText()

História
ReleaseMudanças
18 R6Adicionado

.readText( { stopChar : Text } ) : Text

ParâmetroTipoDescrição
stopCharText->Caracter no qual parar a leitura
ResultadosText<-Texto do arquivo

Descrição

The .readText() function returns text from the file, starting from the current position until the first stopChar string is encountered (if passed) or the end of file is reached.

The stopChar character string is not included in the returned text. If you omit the stopChar parameter, the whole document text is returned.

When this function is executed, the (.offset) is placed just after the stopChar string.

Aviso

This function assumes that the .offset property is a number of characters, not a number of bytes. For more information, see the .offset description.

If the stopChar parameter is passed and not found, .readText() returns an empty string and the .offset is left untouched.

Quando esta função é executada pela primeira vez num handle de arquivo, todo o conteúdo do documento é carregado num buffer.

Veja também

.readLine(), .writeText()

.setSize()

História
ReleaseMudanças
18 R6Adicionado

.setSize( size : Real )

ParâmetroTipoDescrição
sizeReal->Novo tamanho do documento em bytes

Descrição

The .setSize() function sets a new size in bytes for the document.

If the size value is less than the current document size, the document content is truncated from the beginning to get the new size .

Veja também

.getSize(), file.size

.writeBlob()

História
ReleaseMudanças
18 R6Adicionado

.writeBlob( blob : 4D.Blob )

ParâmetroTipoDescrição
blob4D.Blob->Blob para escrever no arquivo

Descrição

The .writeBlob() function writes blob into the file, starting from the current position .

When this function is executed, the current position (.offset) is updated after the last byte written.

Veja também

.readBlob()

.writeLine()

História
ReleaseMudanças
18 R6Adicionado

.writeLine( lineOfText : Text )

ParâmetroTipoDescrição
lineOfTextText->Texto para string

Descrição

The .writeLine() function writes lineOfText content at the current position and inserts an end-of-line delimiter (unlike the .writeText() function). By default, a native end-of-line delimiter is used, but you can define another delimiter when opening the file handle by setting the .breakModeWrite property.

When this function is executed, the current position (.offset) is updated after the end-of-line delimiter.

Veja também

.breakModeWrite, .readLine(), .writeText()

.writeText()

História
ReleaseMudanças
18 R6Adicionado

.writeText( textToWrite : Text )

ParâmetroTipoDescrição
textToWriteText->Texto para string

Descrição

The .writeText() function writes textToWrite content at the current position and does not insert a final end-of-line delimiter (unlike the .writeLine() function). By default, the native delimiter is used, but you can define another delimiter when opening the file handle by setting the .breakModeWrite property.

When this function is executed, the current position (.offset) is updated after the next end-of-line delimiter.

Veja também

.breakModeWrite, .readText(), .writeLine()