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().
Para ler ou escrever um documento inteiro de uma só vez, pode considerar a utilização das funções file.getText() e file.setText().
Graças ao objeto padrão 4D refcounting, um handle de arquivo é automaticamente apagado quando deixa de ser referenciado por conseguinte, o objeto File solicitado é automaticamente fechado. 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. Se você quiser "forçar" a liberação dos recursos do objeto a qualquer momento, você pode anular suas referências.
Exemplo
var $f : 4D.File
var $fhandle : 4D.FileHandle
$f:=Folder(Database folder).file("example.txt")
//Escrevendo linha por linha desde o início
$fhandle:=$f.open("write")
$text:="Hello World"
For ($line; 1; 4)
$fhandle.writeLine($text+String($line))
End for
//Escrevendo linha por linha a partir do final
$fhandle:=$f.open("append")
$text:="Hello New World!"
For ($line; 1; 4)
$fhandle.writeLine($text+String($line))
End for
//Leitura usando um caractere de parada e um parâmetro de objeto
$o:=New object()
$o.mode:="read"
$o.charset:="UTF-8"
$o.breakModeRead:=Document with CRLF
$stopChar:="!"
$fhandle:=$f.open($o)
$text:=$fhandle.readText($stopChar)
//Leitura linha a linha
$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 o modo de processamento de quebras de linha usado ao ler o arquivo |
| .breakModeWrite : Text o modo de processamento de quebras de linha usado ao escrever no arquivo |
| .charset : Text o conjunto de caracteres usado durante a leitura ou escrita para o arquivo |
| .eof : Boolean True é o offset chegou ao fim do arquivo, e False caso contrário |
| .file : 4D.File o objeto 4D.File no qual o identificador foi criado |
| .getSize() : Real retorna o tamanho atual do documento, expresso em bytes |
| .mode : Text o modo em que o identificador de arquivos foi criado: "read", "write", ou "append" |
| .offset : Real o deslocamento atual do fluxo de dados (posição no documento) |
| .readBlob( bytes : Real ) : 4D.Blob retorna um blob de tamanho bytes do arquivo, começando da posição atual |
| .readLine() : Text retorna uma linha de texto da posição atual até que um delimitador de fim de linha seja encontrado ou o final do documento seja alcançado |
| .readText( { stopChar : Text } ) : Text retorna texto do arquivo, a partir da posição atual até que a primeira string stopChar seja encontrada (se passada) ou o fim do arquivo seja alcançada |
| .setSize( size : Real ) define um novo tamanho de size em bytes para o documento |
| .writeBlob( blob : 4D.Blob ) escreve blob no arquivo, começando pela posição atual |
| .writeLine( lineOfText : Text ) escreve o conteúdo lineOfText na posição atual e insere um delimitador de linha |
| .writeText( textToWrite : Text ) escreve o conteúdo textToWrite na posição atual e não insere um delimitador final de fim-de-linha |
.breakModeRead
História
| Release | Mudanças |
|---|---|
| 18 R6 | Adicionado |
.breakModeRead : Text
Descrição
A propriedade .breakModeRead retorna o modo de processamento de quebras de linha usado ao ler o arquivo.
A propriedade .breakModeRead pode ser definida na criação do identificador com a função file.open() (consulte a função .open() para obter mais informações). O padrão é "nativo".
A propriedade
.breakModeReadcontém sempre um valor de texto, mesmo que a opção.open()tenha sido definida usando um número (constante).
Essa propriedade é somente leitura.
.breakModeWrite
História
| Release | Mudanças |
|---|---|
| 18 R6 | Adicionado |
.breakModeWrite : Text
Descrição
A propriedade .breakModeWrite retorna o modo de processamento de quebras de linha usado ao escrever no arquivo.
A propriedade .breakModeWrite pode ser definida na criação do identificador com a função file.open() (consulte a função .open() para obter mais informações). O padrão é "nativo".
A propriedade
.breakModeWritecontém sempre um valor de texto, mesmo que a opção.open()tenha sido definida utilizando um número (constante).
Essa propriedade é somente leitura.
.charset
História
| Release | Mudanças |
|---|---|
| 18 R6 | Adicionado |
.charset : Text
Descrição
A propriedade .charset retorna o conjunto de caracteres usado durante a leitura ou escrita para o arquivo.
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
A propriedade .eof retorna True é o offset chegou ao fim do arquivo, e False caso contrário.
Essa propriedade é somente leitura.
.file
.file : 4D.File
Descrição
A propriedade .file retorna o objeto 4D.File no qual o identificador foi criado.
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
A função .getSize() retorna o tamanho atual do documento, expresso em 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
A propriedade .mode retorna o modo em que o identificador de arquivos foi criado: "read", "write", ou "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
A propriedade .offset retorna o deslocamento atual do fluxo de dados (posição no documento). O valor do offset é automaticamente atualizado após as operações de leitura e escrita.
A modificação de .offset alterará seu valor atual no momento da próxima operação de leitura ou gravação.
- Se o valor passado for negativo, o
.offseté definido para o início do arquivo (zero). - Se o valor passado for superior ao tamanho do arquivo, o arquivo
.offseté definido para o fim do arquivo (tamanho do ficheiro).
Essa propriedade é leitura/escrita.
Quando um identificador de arquivo é criado, o valor .offset é um número de bytes. No entanto, a unidade de medida do deslocamento difere conforme a função de leitura: com readBlob(), .offset é um número de bytes, enquanto com readText()/readLine() ele é um número de caracteres. Dependendo do conjunto de caracteres do arquivo, um caractere corresponde a um ou mais bytes. Então, se você começar a ler com readBlob() e então chamar readText(), a leitura do texto começará em uma posição inconsistente. Portanto, é essencial definir a propriedade .offset caso você altere de leitura/escrita de blob para leitura/escrita de texto no mesmo filehandle. Por exemplo:
// Abra um arquivo de texto europeu usando a codificação utf-16 (dois bytes por caractere)
// Queremos ler os primeiros 10 caracteres como bytes, depois, o restante como texto.
$fh:=File("/RESOURCES/sample_utf_16.txt").open()
// leia os 20 primeiros bytes (i. . 10 caracteres)
$b:=$fh.readBlob(20) // $fh. ffset=20
// depois leia todo o texto ignorando os primeiros 10 caracteres que acabamos de ler em blob
// porque agora estamos lendo texto em vez de bytes, o significado de 'offset' não é o mesmo.
// Precisamos traduzi-lo de bytes para caracteres.
$fh.offset:=10 // peça para pular 10 utf-16 caracteres (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
A função .readBlob() retorna um blob de tamanho bytes do arquivo, começando da posição atual .
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
A função .readLine() retorna uma linha de texto da posição atual até que um delimitador de fim de linha seja encontrado ou o final do documento seja alcançado.
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
A função .readText() retorna texto do arquivo, a partir da posição atual até que a primeira string stopChar seja encontrada (se passada) ou o fim do arquivo seja alcançada.
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.
Se o parâmetro stopChar for passado e não for encontrado, .readText() retorna uma string vazia e o .offset permanecerá intocado.
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
A função .setSize() define um novo tamanho de size em bytes para o documento.
Se o valor de size for menor que o tamanho atual do documento, o conteúdo do documento será truncado desde o início para obter o novo 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
A função .writeBlob() escreve blob no arquivo, começando pela posição atual.
Quando esta função é executada, a posição atual (.offset) é atualizada após do último byte escrito.
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
A função .writeLine() escreve o conteúdo lineOfText na posição atual e insere um delimitador de linha (diferente da função .writeText()). Por padrão, um delimitador de fim de linha nativo é usado, mas você pode definir outro delimitador quando abrir o identificador do arquivo definindo a propriedade .breakModeWrite.
Quando esta função é executada, a posição atual (.offset) é atualizada após o delimitador de fim de linha.
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
A função .writeText() escreve o conteúdo textToWrite na posição atual e não insere um delimitador final de fim-de-linha (ao contrário da função .writeLine()). Por padrão, o delimitador nativo é usado, mas você pode definir outro delimitador quando abrir o identificador do arquivo definindo a propriedade .breakModeWrite.
Quando esta função é executada, a posição atual (.offset) é atualizada após o próximo delimitador de fim de linha.