File-Objekt - Methoden & Eigenschaften

Ermöglicht eine Schnittstelle für Datei-Ein-/Ausgabe. FileOpen() gibt ein Objekt dieses Typs zurück.

Inhaltsverzeichnis

Methoden

Read

Liest eine Zeichenkette aus der Datei und rückt dabei den Dateizeiger vor.

Zkette := File.Read(ZeichenAnzahl)

ZeichenAnzahl: Die maximale Anzahl der zu lesenden Zeichen. Lässt man diesen Parameter weg, wird der Rest der Datei gelesen und als einzelne Zeichenkette zurückgegeben. Falls das File-Objekt von einem Handle, das auf ein nicht-suchendes Device wie Konsolenpuffer oder Pipe verweist, erzeugt wurde, kann das Weglassen dieses Parameters dazu führen, dass die Methode fehlschlägt oder nur die aktuell verfügbaren Daten zurückgibt.

Der Rückgabewert ist eine Zeichenkette.

Write

Schreibt eine Zeichenkette in die Datei und rückt dabei den Dateizeiger vor.

File.Write(Zkette)

Zkette: Eine Zeichenkette, die geschrieben werden soll.

Der Rückgabewert ist die Anzahl der Bytes (nicht Zeichen), die geschrieben wurden.

ReadLine

Liest eine Textzeile aus der Datei und rückt dabei den Dateizeiger vor.

TextZeile := File.ReadLine()

Der Rückgabewert ist eine Textzeile. Die Textzeile kann `n, `r`n oder `r enthalten, je nachdem, welche EOL-Flags beim Öffnen der Datei verwendet wurden.

Es können Zeilen mit einer Länge von bis zu 65534 Zeichen gelesen werden. Wenn eine Zeile diese Länge überschreitet, wird der Rest der Zeile durch nachfolgende Aufrufe dieser Methode zurückgegeben.

WriteLine

Schreibt eine Zeichenkette, die mit `n oder `r`n enden wird, je nachdem, welche EOL-Flags beim Öffnen der Datei verwendet wurden. Der Dateizeiger wird dabei vorgerückt.

File.WriteLine(Zkette)

Zkette: Eine optionale Zeichenkette, die geschrieben werden soll.

Der Rückgabewert ist die Anzahl der Bytes (nicht Zeichen), die geschrieben wurden.

ReadZahlentyp

Liest eine Zahl aus der Datei und rückt dabei den Dateizeiger vor.

Zahl := File.ReadZahlentyp()

Zahlentyp ist entweder UInt, Int, Int64, Short, UShort, Char, UChar, Double oder Float. Diese Typennamen haben die gleiche Bedeutung wie bei DllCall().

Der Rückgabewert ist bei Erfolg eine Zahl und bei Misserfolg eine leere Zeichenkette.

Wenn eine Try-Anweisung aktiv ist und keine Bytes gelesen wurden, wird eine Ausnahme ausgelöst. Es wird keine Ausnahme ausgelöst, wenn mindestens ein Byte gelesen wurde, selbst wenn die Größe des angegebenen Zahlentyps größer als die Anzahl der gelesenen Bytes ist. Stattdessen werden die fehlenden Bytes als Null angesehen.

WriteZahlentyp

Schreibt eine Zahl in die Datei und rückt dabei den Dateizeiger vor.

File.WriteZahlentyp(Zahl)

Zahl: Eine Zahl, die geschrieben werden soll.

Zahlentyp ist entweder UInt, Int, Int64, Short, UShort, Char, UChar, Double oder Float. Diese Typennamen haben die gleiche Bedeutung wie bei DllCall().

Der Rückgabewert ist die Anzahl der Bytes, die geschrieben wurden. Zum Beispiel wird WriteUInt bei Erfolg eine 4 zurückgeben.

RawRead

Liest rohe Binärdaten aus der Datei in den Speicher und rückt dabei den Dateizeiger vor.

File.RawRead(VarOderAdresse, Bytes)

VarOderAdresse: Eine Variable oder Speicheradresse, in der die Daten kopiert werden. Die Verwendungsweise ähnelt der von NumGet(). Falls eine Variable angegeben ist, wird sie je nach Bedarf automatisch erweitert.
Bytes: Die maximale Anzahl der zu lesenden Bytes.

Der Rückgabewert ist die Anzahl der Bytes, die gelesen wurden.

Wenn eine Try-Anweisung aktiv ist und Bytes ungleich Null ist, aber keine Bytes gelesen wurden, wird eine Ausnahme ausgelöst. Mit AtEOF kann dies, falls erforderlich, verhindert werden.

RawWrite

Schreibt rohe Binärdaten in die Datei und rückt dabei den Dateizeiger vor.

File.RawWrite(VarOderAdresse, Bytes)

VarOderAdresse: Eine Variable, die die Daten oder die Adresse der Daten im Speicher enthält. Die Verwendungsweise ähnelt der von NumPut().
Bytes: Die maximale Anzahl der zu schreibenden Bytes.

Der Rückgabewert ist die Anzahl der Bytes, die geschrieben wurden.

Seek

Verschiebt den Dateizeiger.

File.Seek(Distanz , Startpunkt := 0)
File.Position := Distanz
File.Pos := Distanz

Distanz

Die Anzahl der Bytes, die zurückgelegt werden sollen. Je niedriger der Wert, desto näher ist der Dateizeiger am Anfang der Datei.

Startpunkt

Von wo aus der Dateizeiger verschoben werden soll. Muss einer der folgenden Werte sein:

0 (SEEK_SET): Anfang der Datei. Distanz muss 0 oder größer sein.
1 (SEEK_CUR): Aktuelle Position des Dateizeigers.
2 (SEEK_END): Ende der Datei. Distanz sollte normalerweise negativ sein.

Lässt man diesen Parameter weg, wird als Startpunkt standardmäßig SEEK_END verwendet, wenn Distanz negativ ist, ansonsten SEEK_SET.

Der Rückgabewert ist bei Erfolg ein Wert ungleich 0 und bei Misserfolg eine 0.

Tell

Gibt die aktuelle Position des Dateizeigers zurück, wobei 0 der Anfang der Datei ist.

Pos := File.Tell()
Pos := File.Position
Pos := File.Pos

Close

Schließt die Datei, entleert alle Daten im Zwischenspeicher auf die Festplatte und hebt Freigabesperrungen auf.

File.Close()

Obwohl die Datei beim Freigeben des Objekts automatisch geschlossen wird, ist es empfehlenswert, die Datei sofort zu schließen, wenn sie nicht mehr benötigt wird.

Eigenschaften

Length

Ermittelt oder setzt die Größe der Datei.

Dateigröße := File.Length

File.Length := NeueGröße

Dateigröße und NeueGröße ist die Größe der Datei in Bytes.

Diese Eigenschaft sollte nur mit einer realen Datei verwendet werden. Falls das File-Objekt von einem Handle, das auf ein Pipe verweist, erzeugt wurde, wird es möglicherweise die derzeitig verfügbare Datenmenge im internen Pufferspeicher des Pipes zurückgeben, doch dieses Verhalten trifft nicht immer zu.

AtEOF

Ermittelt ein Wert ungleich 0, wenn der Dateizeiger das Ende der Datei erreicht hat, ansonsten 0.

IsAtEOF := File.AtEOF

Diese Eigenschaft sollte nur mit einer realen Datei verwendet werden. Falls das File-Objekt von einem Handle, das auf ein nicht-suchendes Device wie Konsolenpuffer oder Pipe verweist, erzeugt wurde, hat der Rückgabewert möglicherweise keine Bedeutung, da solche Devices logischerweise kein "End of File" haben.

Encoding

Ermittelt oder setzt die Textcodierung des File-Objekts.

ErmittelteCodierung := File.Encoding

File.Encoding := NeueCodierung

ErmittelteCodierung und NeueCodierung ist ein numerischer Zeichensatzidentifikator (siehe MSDN) oder eine der folgenden Zeichenketten:

UTF-8: Unicode UTF-8, äquivalent zu CP65001.
UTF-16: Unicode UTF-16 mit Little-Endian-Byte-Order, äquivalent zu CP1200.
CPnnn: Ein Zeichensatz mit dem numerischen Identifikator nnn.

ErmittelteCodierung ist nie ein Wert mit dem Suffix -RAW, egal wie die Datei geöffnet wurde oder ob es eine Byte-Order-Markierung (BOM) enthält. Das Setzen von NeueCodierung bewirkt nicht, dass ein BOM hinzugefügt oder entfernt wird. Normalerweise wird das BOM bereits beim Erstellen der Datei hinzugefügt.

[v1.1.15.04+]: Das Setzen von NeueCodierung auf UTF-8-RAW oder UTF-16-RAW ist erlaubt, aber das Suffix -RAW wird ignoriert. In älteren Versionen verhielten sich UTF-8-RAW und UTF-16-RAW wie eine ungültige 8-Bit-Codierung, was dazu führte, dass alle ASCII-fremden Zeichen verworfen wurden. Dies gilt nur für File.Encoding, nicht für FileOpen().

__Handle

Gibt ein System-Datei-Handle zurück, das für DllCall() verwendet werden kann. Siehe CreateFile.

File.__Handle

File-Objekte puffern intern Lese- und Schreibvorgänge. Daten, die in den internen Pufferspeicher des Objekts geschrieben wurden, werden auf die Festplatte übertragen, bevor das Handle zurückgegeben wird. Wenn der Pufferspeicher gelesene Daten aus einer Datei enthält, werden diese verworfen und der Dateizeiger auf die logische Position (widergespiegelt von File.Pos) zurückgesetzt.

File-Objekt [AHK_L 42+]