File-Objekt - Methoden & Eigenschaften

Ermöglicht eine Schnittstelle für die Dateibearbeitung. FileOpen() gibt ein Objekt dieses Typs zurück.

Objektelemente

Read

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

Zeichenkette := File.Read(Zeichen)

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

Rückgabewert ist eine Zeichenkette.

Write

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

File.Write(Zeichenkette)

Zeichenkette: Eine Zeichenkette, die geschrieben werden soll.

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

Rückgabewert ist eine Textzeile. Sie enthält `n, `r`n oder `r, abhängig von der Datei und den EOL-Flags, die zum Öffnen der Datei verwendet wurden.

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

WriteLine

Schreibt eine Zeichenfolge gefolgt von `n oder `r`n, abhängig von den EOL-Flags, die zum Öffnen der Datei verwendet wurden. Der Dateizeiger wird dabei vorgerückt.

File.WriteLine(Zeichenkette)

Zeichenkette: Eine optionale Zeichenkette, die geschrieben werden soll.

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 die von DllCall().

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 ist als die Anzahl der gelesenen Bytes. 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 die von DllCall().

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 Verwendung hat Ähnlichkeit mit NumGet(). Falls eine Variable angegeben ist, dann wird sie je nach Bedarf automatisch erweitert.
Bytes: Die maximale Anzahl der zu lesenden Bytes.

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 man das verhindern, wenn nötig.

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 Verwendung hat Ähnlichkeit mit NumPut().
Bytes: Die maximale Anzahl der zu schreibenden Bytes.

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

Seek

Verschiebt den Dateizeiger.

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

Distanz

Die Anzahl der Bytes, die zurückgelegt werden sollen. Niedrigere Werte sind näher an den Anfang der Datei.

Ausgangspunkt

Startpunkt zum Verschieben des Dateizeigers. Kann nur eine der folgenden Angaben 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 Ausgangspunkt standardmäßig SEEK_END verwendet, wenn die Distanz negativ ist, ansonsten SEEK_SET.

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

Length

Ermittelt oder bestimmt 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. Allerdings ist dieses Verhalten nicht sichergestellt.

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 (z. B. ein Konsolenpuffer oder Pipe) verweist, erstellt wurde, könnte der Rückgabewert ohne Bedeutung sein, da solche Devices logischerweise kein "End of File" haben.

Close

Schließt die Datei, löscht alle Daten im Zwischenspeicher auf der Festplatte und hebt die Sperrungen auf.

File.Close()

Obwohl die Datei beim Freigeben des Objekts automatisch geschlossen wird, ist es empfehlenswert, die Datei so schnell wie möglich zu schließen.

Encoding

Ermittelt oder setzt die Textcodierung für das File-Objekt.

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, entspricht CP65001.
UTF-16: Unicode UTF-16 mit Little-Endian-Byte-Order, entspricht 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+]: Man kann NeueCodierung auf UTF-8-RAW oder UTF-16-RAW setzen, allerdings wird der Suffix -RAW ignoriert. In älteren Versionen verhielten sich UTF-8-RAW und UTF-16-RAW wie eine ungültige 8-Bit-Codierung, woraufhin 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 geschriebene und gelesene Daten. Daten im internen Pufferspeicher des Objekts werden auf das Laufwerk übertragen, bevor das Handle zurückgegeben wird. Enthält der Pufferspeicher gelesene Daten von der Datei, werden diese Daten verworfen und der aktuelle Dateizeiger auf die logische Position (gekennzeichnet durch File.Pos) zurückgesetzt.

File-Objekt [AHK_L 42+]