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.

note

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

.setSize(), file.size

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

caution

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

.writeBlob()

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

Attention

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

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

Attention

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

.readLine(), .writeText()

.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

.getSize(), file.size

.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

.readBlob()

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

Voir également

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