FileHandle
La classe FileHandle
possède des fonctions qui vous permettent de lire séquentiellement ou d'ajouter du contenu à un objet File
ouvert. Un handle de fichier peut accéder à n'importe quelle partie d'un document.
Les objets de type File handle sont créés avec la fonction file.open()
.
Pour lire ou écrire un document entier en une seule fois, vous pouvez envisager d'utiliser les fonctions file.getText() et file.setText().
Grâce au refcounting standard d'objets de 4D, un handle de fichier est automatiquement supprimé lorsqu'il n'est plus référencé et ainsi, le File
demandé est automatiquement fermé. Par conséquent, avec les file handles, vous n'avez pas à vous soucier de la fermeture des documents.
Les ressources d'un objet, telles que les documents, sont libérées lorsqu'il n'y a plus de références en mémoire, ce qui se produit par exemple à la fin de l'exécution de la méthode pour les variables locales. Si vous souhaitez "forcer" la libération des ressources de l'objet à tout moment, vous pouvez nullifier ses références.
Exemple
var $f : 4D.File
var $fhandle : 4D.FileHandle
$f:=Folder(Database folder).file("example.txt")
//Écrire ligne par ligne depuis le début
$fhandle:=$f.open("write")
$text:="Hello World"
For ($line; 1 ; 4)
$fhandle.writeLine($text+String($line))
Fin pour
//Ecriture ligne par ligne à partir de la fin
$fhandle:=$f.open("append")
$text:="Hello New World !"
For ($line; 1 ; 4)
$fhandle.writeLine($text+String($line))
Fin pour
//Lecture en utilisant un caractère d'arrêt et un paramètre objet
$o:=Nouvel objet()
$o.mode:="read"
$o.charset:="UTF-8"
$o.breakModeRead:=Document avec CRLF
$stopChar:=" !"
$fhandle:=$f.open($o)
$text:=$fhandle.readText($stopChar)
//Lecture ligne par ligne
$lines:=Nouvelle collection
$fhandle:=$f.open("read")
While (Not($fhandle.eof))
$lines.push($fhandle.readLine())
End while
Objet FileHandle
Les objets de type File handle ne peuvent pas être partagés.
.breakModeRead : Text le mode de traitement des sauts de ligne utilisé lors de la lecture du fichier |
.breakModeWrite : Text le mode de traitement des sauts de ligne utilisé lors de l'écriture dans le fichier |
.charset : Text le jeu de caractères utilisé lors de la lecture ou de l'écriture dans le fichier |
.eof : Boolean True si l' offset a atteint la fin du fichier, et False sinon |
.file : 4D.File l'objet 4D.File sur lequel le handle a été créé |
.getSize() : Real renvoie la taille courante du document, exprimée en octets |
.mode : Text le mode dans lequel le handle de fichier a été créé : "read", "write" ou "append" |
.offset : Real l'offset courant du flux de données (position à l'intérieur du document) |
[.readBlob( bytes : Real ) : 4D.Blob ](#readblob) renvoie un blob d'une taille de bytes octets depuis le fichier, à partir de la position courante |
.readLine() : Text renvoie une ligne de texte à partir de la position courante jusqu'à ce qu'un délimiteur de fin de ligne soit rencontré ou que la fin du document soit atteinte |
.readText( { stopChar : Text } ) : Text renvoie le texte du fichier, à partir de la position courante jusqu'à ce que la première chaîne stopChar soit rencontrée (si elle est passée) ou que la fin du fichier soit atteinte |
.setSize( size : Real ) définit une nouvelle taille de size octets pour le document |
.writeBlob( blob : 4D.Blob ) écrit blob dans le fichier, à partir de la position courante |
.writeLine( lineOfText : Text ) écrit le contenu de lineOfText à la position courante et insère un délimiteur de fin de ligne |
.writeText( textToWrite : Text ) écrit le contenu de textToWrite à la position courante et n'insère pas de délimiteur de fin de ligne final |
.breakModeRead
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.breakModeRead : Text
Description
La propriété .breakModeRead
contient le mode de traitement des sauts de ligne utilisé lors de la lecture du fichier.
La propriété .breakModeRead
peut être définie lors de la création du handle à l'aide de la fonction file.open()
(voir la fonction .open()
pour plus d'informations). La valeur par défaut est "native".
La propriété
.breakModeRead
contient toujours une valeur texte, même si l'option de.open()
a été définie à l'aide d'un nombre (constante).
Cette propriété est en lecture seule.
.breakModeWrite
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.breakModeWrite : Text
Description
La propriété .breakModeWrite
contient le mode de traitement des sauts de ligne utilisé lors de l'écriture dans le fichier.
La propriété .breakModeWrite
peut être définie lors de la création du handle à l'aide de la fonction file.open()
(voir la fonction .open()
pour plus d'informations). La valeur par défaut est "native".
La propriété
.breakModeWrite
contient toujours une valeur texte, même si l'option de.open()
a été définie à l'aide d'un nombre (constante).
Cette propriété est en lecture seule.
.charset
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.charset : Text
Description
La propriété .charset
contient le jeu de caractères utilisé lors de la lecture ou de l'écriture dans le fichier.
Le jeu de caractères peut être défini lors de la création du handle avec la fonction file.open()
. La valeur par défaut est "UTF-8".
Cette propriété est en lecture seule.
.eof
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.eof : Boolean
Description
La propriété .eof
contient True si l'offset
a atteint la fin du fichier, et False sinon.
Cette propriété est en lecture seule.
.file
.file : 4D.File
Description
La propriété .file
contient l'objet 4D.File sur lequel le handle a été créé.
Cette propriété est en lecture seule.
.getSize()
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.getSize() : Real
Paramètres | Type | Description | |
---|---|---|---|
Résultat | Real | <- | Taille du document en octets |
Description
La fonction .getSize()
renvoie la taille courante du document, exprimée en octets.
Cette fonction renvoie la même valeur que la propriété (.size) de la classe
File
.
Voir également
.mode
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.mode : Text
Description
La propriété .mode
contient le mode dans lequel le handle de fichier a été créé : "read", "write" ou "append".
Le mode peut être défini lors de la création du handle avec la fonction file.open()
. La valeur par défaut est "read".
Cette propriété est en lecture seule.
.offset
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.offset : Real
Description
La propriété .offset
contient l'offset courant du flux de données (position à l'intérieur du document). La valeur de l'offset est automatiquement mise à jour après les opérations de lecture et d'écriture.
Le fait de modifier .offset
changera sa valeur courante au moment de la prochaine opération de lecture ou d'écriture.
- Si la valeur passée est négative,
.offset
est fixé au début du fichier (zéro). - Si la valeur passée est supérieure à la taille du fichier,
.offset
est fixé à la fin du fichier (taille du fichier).
Cette propriété est en lecture/écriture.
Lorsqu'un file handle est créé, la valeur .offset
est un nombre d'octets. Cependant, l'unité de mesure du décalage diffère selon la fonction de lecture : avec readBlob()
, .offset
est un nombre d'octets, alors qu'avec readText()
/readLine()
, c'est un nombre de caractères. Selon le jeu de caractères du fichier, un caractère correspond à un ou plusieurs octets. Ainsi, si vous commencez la lecture avec readBlob()
et que vous appelez ensuite readText()
, la lecture du texte commencera à une position incohérente. Il est donc essentiel de définir vous-même la propriété .offset
si vous passez de la lecture/écriture de blob à la lecture/écriture de texte dans le même filehandle. Par exemple :
// Ouvrir un fichier texte européen en utilisant l'encodage utf-16 (2 octets par caractère)
// Nous voulons lire les 10 premiers caractères en octets, puis le reste en tant que texte.
$fh:=File("/RESOURCES/sample_utf_16.txt").open()
// lire les 20 premiers octets (i.e. 10 caractères)
$b:=$fh.readBlob(20) // $fh.offset=20
// lire alors tout le texte en ignorant les 10 premiers caractères que nous venons de lire dans le blob
// parce que nous lisons maintenant du texte au lieu d'octets, la signification de 'offset' n'est pas la même.
// Nous devons le traduire d'octets en caractères.
$fh.offset:=10 // demande de sauter 10 caractères utf-16 (20 octets)
$s:=$fh.readText()
.readBlob()
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.readBlob( bytes : Real ) : 4D.Blob
Paramètres | Type | Description | |
---|---|---|---|
bytes | Real | -> | Nombre d'octets à lire |
Résultat | 4D.Blob | <- | Octets lus depuis le fichier |
Description
La fonction .readBlob()
renvoie un blob d'une taille de bytes octets depuis le fichier, à partir de la position courante.
Lorsque cette fonction est exécutée, la position courante (.offset) est mise à jour après le dernier octet lu.
Voir également
.readLine()
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.readLine() : Text
Paramètres | Type | Description | |
---|---|---|---|
Résultat | Text | <- | Ligne de texte |
Description
La fonction .readLine()
renvoie une ligne de texte à partir de la position courante jusqu'à ce qu'un délimiteur de fin de ligne soit rencontré ou que la fin du document soit atteinte.
Lorsque cette fonction est exécutée, la position courante (.offset
) est mise à jour.
Cette fonction suppose que la propriété .offset
est un nombre de caractères et non un nombre d'octets. Pour plus d'informations, voir la description de .offset.
Lorsque cette fonction est exécutée pour la première fois sur un file handle, le contenu entier du document est chargé dans un buffer.
Voir également
.readText()
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.readText( { stopChar : Text } ) : Text
Paramètres | Type | Description | |
---|---|---|---|
stopChar | Text | -> | Caractère(s) au(x)quel(s) arrêter la lecture |
Résultat | Text | <- | Texte du fichier |
Description
La fonction .readText()
renvoie le texte du fichier, à partir de la position courante jusqu'à ce que la première chaîne stopChar soit rencontrée (si elle est passée) ou que la fin du fichier soit atteinte.
La chaîne de caractères stopChar n'est pas incluse dans le texte retourné. Si vous omettez le paramètre stopChar, le texte du document entier est renvoyé.
Lorsque cette fonction est exécutée, le (.offset) est placé juste après la chaîne stopChar.
Cette fonction suppose que la propriété .offset
est un nombre de caractères et non un nombre d'octets. Pour plus d'informations, voir la description de .offset.
Si le paramètre stopChar est passé et non trouvé, .readText()
renvoie une chaîne vide et le .offset n'est pas modifié.
Lorsque cette fonction est exécutée pour la première fois sur un file handle, le contenu entier du document est chargé dans un buffer.
Voir également
.setSize()
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.setSize( size : Real )
Paramètres | Type | Description | |
---|---|---|---|
size | Real | -> | Nouvelle taille du document en octets |
Description
La fonction .setSize()
définit une nouvelle taille de size octets pour le document.
Si la valeur de size est inférieure à la taille courante du document, le contenu du document est tronqué depuis le début pour obtenir la nouvelle taille size.
Voir également
.writeBlob()
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.writeBlob( blob : 4D.Blob )
Paramètres | Type | Description | |
---|---|---|---|
blob | 4D.Blob | -> | Blob à écrire dans le fichier |
Description
La fonction .writeBlob()
écrit blob dans le fichier, à partir de la position courante.
Lorsque cette fonction est exécutée, la position courante (.offset) est mise à jour après le dernier octet écrit.
Voir également
.writeLine()
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.writeLine( lineOfText : Text )
Paramètres | Type | Description | |
---|---|---|---|
lineOfText | Text | -> | Texte à écrire |
Description
La fonction .writeLine()
écrit le contenu de lineOfText à la position courante et insère un délimiteur de fin de ligne (contrairement à la fonction .writeText()). Par défaut, un délimiteur de fin de ligne natif est utilisé, mais vous pouvez définir un autre délimiteur lors de la création du file handle en définissant la propriété .breakModeWrite
.
Lorsque cette fonction est exécutée, la position courante (.offset) est mise à jour après le d élimiteur de fin de ligne.
Voir également
.breakModeWrite, .readLine(), .writeText()
.writeText()
Historique
Release | Modifications |
---|---|
19 R7 | Ajout |
.writeText( textToWrite : Text )
Paramètres | Type | Description | |
---|---|---|---|
textToWrite | Text | -> | Texte à écrire |
Description
La fonction .writeText()
écrit le contenu de textToWrite à la position courante et n'insère pas de délimiteur de fin de ligne final (contrairement à la fonction .writeLine()). Par défaut, le délimiteur natif est utilisé, mais vous pouvez définir un autre délimiteur lors de la création du file handle en définissant la propriété .breakModeWrite
.
Lorsque cette fonction est exécutée, la position courante (.offset) est mise à jour après le prochain délimiteur de fin de ligne.