FileHandle
The FileHandle
class has functions that allow you to sequentially read from or append contents to an opened File
object. Un manejador de archivo puede acceder a cualquier parte de un 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. Por lo tanto, con los gestores de archivos no hay que preocuparse por el cierre de los documentos.
Los recursos de los objetos, como los documentos, se liberan cuando ya no existen referencias en la memoria, lo que ocurre, por ejemplo, al final de la ejecución del método para las variables locales. If you want to "force" the release of object resources at any moment, you can nullify its references.
Ejemplo
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
Los objetos manejadores de archivos no pueden ser compartidos.
.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 ](#readblob) 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
Historia
Lanzamiento | Modificaciones |
---|---|
19 R7 | Añadidos |
.breakModeRead : Text
Descripción
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). Por defecto es "native".
The
.breakModeRead
property always contains a text value, even if the.open()
option was set using a number (constant).
Esta propiedad es de solo lectura.
.breakModeWrite
Historia
Lanzamiento | Modificaciones |
---|---|
19 R7 | Añadidos |
.breakModeWrite : Text
Descripción
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). Por defecto es "native".
The
.breakModeWrite
property always contains a text value, even if the.open()
option was set using a number (constant).
Esta propiedad es de solo lectura.
.charset
Historia
Lanzamiento | Modificaciones |
---|---|
19 R7 | Añadidos |
.charset : Text
Descripción
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 defecto es "UTF-8".
Esta propiedad es de solo lectura.
.eof
Historia
Lanzamiento | Modificaciones |
---|---|
19 R7 | Añadidos |
.eof : Boolean
Descripción
The .eof
property returns True is the offset
has reached the end of the file, and False otherwise.
Esta propiedad es de solo lectura.
.file
.file : 4D.File
Descripción
The .file
property returns the 4D.File object on which the handle has been created.
Esta propiedad es de solo lectura.
.getSize()
Historia
Lanzamiento | Modificaciones |
---|---|
19 R7 | Añadidos |
.getSize() : Real
Parámetros | Tipo | Descripción | |
---|---|---|---|
Result | Real | <- | Tamaño del documento en bytes |
Descripción
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.
Ver también
.mode
Historia
Lanzamiento | Modificaciones |
---|---|
19 R7 | Añadidos |
.mode : Text
Descripción
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. Por defecto es "leer".
Esta propiedad es de solo lectura.
.offset
Historia
Lanzamiento | Modificaciones |
---|---|
19 R7 | Añadidos |
.offset : Real
Descripción
The .offset
property returns the current offset of the data stream (position inside the document). El valor del desplazamiento se actualiza automáticamente después de las operaciones de lectura y escritura.
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).
Esta propiedad es lectura-escritura.
Cuando se crea un file handle, el valor .offset
es un 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. Según el conjunto de caracteres del archivo, un caracter corresponde a uno o varios 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 ejemplo:
// 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()
Historia
Lanzamiento | Modificaciones |
---|---|
19 R7 | Añadidos |
.readBlob( bytes : Real ) : 4D.Blob
Parámetros | Tipo | Descripción | |
---|---|---|---|
bytes | Real | -> | Número de bytes a leer |
Result | 4D.Blob | <- | Bytes leídos del archivo |
Descripción
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.