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 objectos de manipulação de arquivos são criados com 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 objecto padrão 4D refcounting, um handle de arquivo é automaticamente apagado quando deixa de ser referenciado e, por conseguinte, o objeto solicitado arquivo é automaticamente fechado. 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. Se você deseja "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")

//Escrever linha por linha do início
$fhandle:=$f.open("write")
$text:="Hello World" For ($line; 1; 4)
    $fhandle.writeLine($text+String($line))
End for

//Escrever linha por linha do final
$fhandle:=$f.open("append")
$text:="Hello New World!"
For ($line; 1; 4)
    $fhandle.writeLine($text+String($line))
End for

//Leitura usando um carácter de paragem e um parâmetro objecto 
$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 para quebras de linha utilizado na leitura do arquivo
.breakModeWrite : Text    o modo de processamento para quebras de linha utilizado quando se escreve no arquivo
.charset : Text    o charset utilizado na leitura ou na escrita do arquivo
.eof : Boolean    Verdadeiro se offset chegou ao fim do arquivo, e Falso caso contrário
.file: 4D.File    o objeto 4D.File no qual o identificador foi criado
.getSize() : Real     devolve o tamanho atual do documento, expresso em bytes
.mode : Text    o modo em que foi criado o tratamento do arquivo: "ler", "escrever", ou "anexar".
.offset : Real    o offset aual do fluxo de dados (posição no interior do documento)
.readBlob( bytes : Real ) : [4D. Blob](BlobClass)     devolve um blob a bytes tamanho do arquivo, a partir da posição atual
.readLine() : Text     devolve uma linha de texto da posição atual até ser encontrado um delimitador de fim de linha ou até ser alcançado o fim do documento
.readText( { stopChar : Text } ) : Text     devolve texto do arquivo, a partir da posição atual até à primeira stopChar string ser encontrada (se passada) ou o fim do arquivo ser alcançado
.setSize( size : Real )    estabelece um novo tamanho ** em bytes para o documento
[
.writeLine( lineOfText : Text )     escreve lineOfText conteúdo na posição atual e insere um delimitador de fim de linha
.writeText( textToWrite : Text )    escreve textToWrite conteúdo na posição atual e não insere um delimitador final de fim de linha

.breakModeRead

Histórico

Versão	Mudanças
v19 R7	Adicionado

.breakModeRead : Text

Descrição

A propriedade .breakModeRead devolve o modo de processamento para quebras de linha utilizado na leitura do arquivo.

A propriedade .breakModeWrite pode ser definida na criação do handle com a função file.open() (ver a função .open() função para mais informações). O padrão é "nativo".

A propriedade .breakModeRead contém sempre um valor de texto, mesmo que a opção .open() tenha sido definida usando um número (constante).

Essa propriedade é apenas leitura.

.breakModeWrite

Histórico

Versão	Mudanças
v19 R7	Adicionado

.breakModeWrite : Text

Descrição

A propriedade .breakModeWrite devolve o modo de processamento para quebras de linha utilizado quando se escreve no arquivo.

A propriedade .breakModeRead pode ser definida na criação do cabo com a função file.open() (ver o .open() function para mais informações). O padrão é "nativo".

A propriedade .breakModeWrite contém sempre um valor de texto, mesmo que a opção .open() tenha sido definida utilizando um número (constante).

Essa propriedade é apenas leitura.

.charset

Histórico

Versão	Mudanças
v19 R7	Adicionado

.charset : Text

Descrição

O .charset devolve propriedades o charset utilizado na leitura ou na escrita do arquivo.

O charset pode ser definido na criação do cabo com a função file.open() . Por padrão é "UTF-8".

Essa propriedade é apenas leitura.

.eof

Histórico

Versão	Mudanças
v19 R7	Adicionado

.eof : Boolean

Descrição

A propriedade .eof devolve Verdadeiro se offset chegou ao fim do arquivo, e Falso caso contrário.

Essa propriedade é apenas leitura.

.file

.file: 4D.File

Descrição

A propriedade .file devolve o objeto 4D.File no qual o identificador foi criado.

Essa propriedade é apenas leitura.

.getSize()

Histórico

Versão	Mudanças
v19 R7	Adicionado

.getSize() : Real

Parâmetro	Tipo		Descrição
Resultados	Real	<-	Tamanho do documento em bytes

|

Descrição

A função .getSize() devolve o tamanho atual do documento, expresso em bytes.

Esta função devolve o mesmo valor que a propriedade (.size) da classe File .

Veja também

.setSize(), file.size

.mode

Histórico

Versão	Mudanças
v19 R7	Adicionado

.mode : Text

Descrição

A propriedade .mode devolve o modo em que foi criado o tratamento do arquivo: "ler", "escrever", ou "anexar"..

O modo pode ser definido na criação do punho com a função file.open() . O padrão é "read".

Essa propriedade é apenas leitura.

.offset

Histórico

Versão	Mudanças
v19 R7	Adicionado

.offset : Real

Descrição

A propriedade .offset devolve o offset aual do fluxo de dados (posição no interior do 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 arquivo .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).

Esta propriedade é 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. 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 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()
  // lê os 20 primeiros bytes (i.e. 10 caracteres)
$b:=$fh.readBlob(20) // $fh.offset=20
  // depois lê todo o texto saltando os primeiros 10 caracteres que acabámos de ler no blob anterior
  // porque agora estamos a ler texto em vez de bytes, o significado de 'offset' não é o mesmo.
  // Precisamos de o traduzir de bytes para caracteres.
$fh.offset:=10 // demande de sauter 10 caractères utf-16 (20 octets)
$s:=$fh.readText()

.readBlob()

Histórico

Versão	Mudanças
v19 R7	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() devolve um blob a bytes tamanho do arquivo, a partir 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

.writeBlob()

.readLine()

Histórico

Versão	Mudanças
v19 R7	Adicionado

.readLine() : Text

Parâmetro	Tipo		Descrição
Resultados	Text	<-	Linha de texto

|

Descrição

A função .readLine() devolve uma linha de texto da posição atual até ser encontrado um delimitador de fim de linha ou até ser alcançado o fim do documento.

Quando esta função é executada, a posição atual (.offset) é atualizada.

Alerta

This function assumes that the .offset property is a number of characters, not a number of bytes. Para saber mais, veja a 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(), .writeLine()

.readText()

Histórico

Versão	Mudanças
v19 R7	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() devolve texto do arquivo, a partir da posição atual até à primeira stopChar string ser encontrada (se passada) ou o fim do arquivo ser alcançado.

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 esta função é executada, o (.offset) é colocado logo após a string stopChar.

Alerta

This function assumes that the .offset property is a number of characters, not a number of bytes. Para saber mais, veja a descrição de .offset.

Se o parâmetro stopChar for passado e não for encontrado, .readText() devolve uma string vazia e o .offset é deixado 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

.readLine(), .writeText()

.setSize()

Histórico

Versão	Mudanças
v19 R7	Adicionado

.setSize( size : Real )

Parâmetro	Tipo		Descrição
size	Real	->	Novo tamanho do documento em bytes

|

Descrição

A função .setSize() estabelece um novo tamanho ** em bytes para o documento.

Se o tamanho for inferior ao tamanho atual do documento, o conteúdo do documento é truncado desde o início para obter o novo tamanho .

Veja também

.getSize(), file.size

.writeBlob()

Histórico

Versão	Mudanças
v19 R7	Adicionado

|

Parâmetro	Tipo		Descrição
blob	4D. Blob	->	Blob para escrever no arquivo

|

Descrição

A função .writeBlob() escreve blob no arquivo, a partir da posição atual .

Quando esta função é executada, a posição atual (.offset) é atualizada após o delimitador de fim de linha.

Veja também

.readBlob()

.writeLine()

Histórico

Versão	Mudanças
v19 R7	Adicionado

.writeLine( lineOfText : Text )

Parâmetro	Tipo		Descrição
lineOfText	Text	->	Texto para string

|

Descrição

A função .writeLine() escreve lineOfText conteúdo na posição atual e insere um delimitador de fim de linha (ao contrário da função .writeText()). Como padrão, é utilizado um delimitador nativo de fim de linha, mas pode definir outro delimitador quando abrir o handle do arquivo definindo a propriedade .breakModeWrite .

Quando esta função for executada, a posição atual (.offset) é atualizada depois do último byte escrito.

Veja também

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

.writeText()

Histórico

Versão	Mudanças
v19 R7	Adicionado

.writeText( textToWrite : Text )

Parâmetro	Tipo		Descrição
textToWrite	Text	->	Texto para string

|

Descrição

A função .writeText() escreve textToWrite conteúdo na posição atual e não insere um delimitador final de fim de linha (ao contrário da função .writeLine()). Esta função substitui todos os delimitadores de fim de linha originais.

Quando esta função for executada, a posição atual (.offset) é atualizada após o próximo delimitador de fim de linha.

Veja também

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