FileHandle

La classe FileHandle contient 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, l'objet 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")

//Ecriture ligne par ligne depuis le début
$fhandle:=$f.open("write")
$text:="Hello World"
For ($line; 1 ; 4)
    $fhandle.writeLine($text+String($line))
End for

//Ecriture ligne par ligne depuis la fin
$fhandle:=$f.open("append")
$text:="Hello New World !"
For ($line; 1 ; 4)
    $fhandle.writeLine($text+String($line))
End for

//Lecture en utilisant un caractère d'arrêt et un paramètre objet
$o:=New object()
$o.mode:="read"
$o.charset:="UTF-8"
$o.breakModeRead:=Document with CRLF
$stopChar:=" !" $fhandle:=$f.open($o)
$text:=$fhandle.readText($stopChar)

//Lecture ligne par ligne
$lines:=New 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és 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    Vrai si l'offset a atteint la fin du fichier, et Faux sinon
.file : 4D.File    l'objet 4D.File sur lequel le handle a été créé
.getSize() : Real     retourne la taille courante du document, exprimée en octets
.mode : Text    le mode dans lequel l'identifiant de fichier a été créé : "read", "write", ou "append"
.offset : Real    l'offset courant du flux de données (position dans le document)
.readBlob( bytes : Real ) : 4D.Blob     renvoie un blob de taille bytes octets à partir du fichier, en commençant par 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 le 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 retourne le mode de traitement des sauts de ligne utilisé lors de la lecture du fichier.

La propriété .breakModeRead peut être définie à la création du handle avec 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 retourne le mode de traitement des sauts de ligne utilisés 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 retourne 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 retourne Vrai si l'offset a atteint la fin du fichier, et Faux sinon.

Cette propriété est en lecture seule.

.file

.file : 4D.File

Description

La propriété .file renvoie 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() retourne 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 renvoie le mode dans lequel l'identifiant 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 renvoie l'offset courant du flux de données (position dans le 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, tandis qu'avec readText()/readLine() il s'agit d'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 le codage utf-16 (deux octets par caractère)
  // Nous voulons lire les 10 premiers caractères sous forme d'octets, puis les autres sous forme de texte.
$fh:=File("/RESOURCES/sample_utf_16.txt").open()
  // lire les 20 premiers octets (soit 10 caractères)
$b:=$fh.readBlob(20) // $fh.offset=20
  // puis lire tout le texte en sautant les 10 premiers caractères que nous venons de lire dans le blob précédent
  // 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 dans le fichier

|

Description

La fonction .readBlob() renvoie un blob de taille bytes octets à partir du fichier, en commençant par 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.

Avertissement

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.

Avertissement

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