FileHandle
A classe FileHandle
tem funções que lhe permitem ler sequencialmente ou anexar conteúdos a um objeto aberto File
. O manuseamento de um arquivo pode acessar a qualquer parte de um documento.
Os objetos File handle são criados usando a função file.open()
.
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.
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 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
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.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
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.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
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.charset : Text
Descrição
The .charset
property returns the charset used when reading from or writing to the file.
O conjunto de caracteres pode ser definido na criação do identificador com a função file.open()
. Por padrão é "UTF-8".
Essa propriedade é somente leitura.
.eof
História
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.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
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.getSize() : Real
Parâmetro | Tipo | Descrição | |
---|---|---|---|
Resultados | Real | <- | Tamanho do documento em bytes |
Descrição
The .getSize()
function returns the current size of the document, expressed in bytes.
Essa função retorna o mesmo valor que a propriedade (.size) da classe
File
.
Veja também
.mode
História
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.mode : Text
Descrição
The .mode
property returns the mode in which the file handle was created: "read", "write", or "append".
O modo pode ser definido na criação do identificador com a função file.open()
. O padrão é "read".
Essa propriedade é somente leitura.
.offset
História
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.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.
- Se o valor passado for negativo, o
.offset
é definido para o início do arquivo (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).
Essa propriedade é leitura/escrita.
Quando um identificador de arquivo é criado, o valor .offset
é um número de 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. Dependendo do conjunto de caracteres do arquivo, um caractere corresponde a um ou mais bytes. Dependendo do conjunto de caracteres do arquivo, um caractere corresponde a um ou mais bytes. 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
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.readBlob( bytes : Real ) : 4D.Blob
Parâmetro | Tipo | Descrição | |
---|---|---|---|
bytes | Real | -> | Número de bytes a ler |
Resultados | 4D.Blob | <- | Bytes lidos do arquivo |
Descrição
The .readBlob()
function returns a blob a bytes size from the file, starting from the current position .
Quando esta função é executada, a posição atual (.offset) é atualizada após a leitura do último byte.
Veja também
.readLine()
História
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.readLine() : Text
Parâmetro | Tipo | Descrição | |
---|---|---|---|
Resultados | Text | <- | 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.
Quando essa função é executada, a posição atual (.offset
) é atualizada.
Essa função assume que a propriedade .offset
é um número de caracteres, não um número de bytes. Para obter mais informações, consulte descrição de .offset.
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()
História
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.readText( { stopChar : Text } ) : Text
Parâmetro | Tipo | Descrição | |
---|---|---|---|
stopChar | Text | -> | Caracter no qual parar a leitura |
Resultados | Text | <- | 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.
A string de caracteres stopChar não está incluída no texto devolvido. Se omitir o parâmetro stopChar, todo o texto do documento é devolvido.
Quando essa função é executada, o (.offset) é colocado logo após a string stopChar.
Essa função assume que a propriedade .offset
é um número de caracteres, não um número de bytes. Para obter mais informações, consulte descrição de .offset.
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
.setSize()
História
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.setSize( size : Real )
Parâmetro | Tipo | Descrição | |
---|---|---|---|
size | Real | -> | 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
.writeBlob()
História
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.writeBlob( blob : 4D.Blob )
Parâmetro | Tipo | Descrição | |
---|---|---|---|
blob | 4D.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
.writeLine()
História
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.writeLine( lineOfText : Text )
Parâmetro | Tipo | Descrição | |
---|---|---|---|
lineOfText | Text | -> | 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
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.writeText( textToWrite : Text )
Parâmetro | Tipo | Descrição | |
---|---|---|---|
textToWrite | Text | -> | 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.