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().

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. 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")

//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 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".

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

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".

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

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

.setSize(), file.size

.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.

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.

caution

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. 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

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

.writeBlob()

.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.

Aviso

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(), .writeLine()

.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.

Aviso

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

.readLine(), .writeText()

.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.

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

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

.readBlob()

.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.

Veja também

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