File-Objekt [AHK_L 42+]

Bietet eine Schnittstelle für die Ein- und Ausgabe einer Datei. FileOpen() gibt ein Objekt dieses Typs zurück.

Inhaltsverzeichnis

Methoden

Read

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

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

Gibt eine Zeichenkette zurück.

Write

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

File.Write(Zkette)
Zkette
Eine Zeichenkette, die geschrieben werden soll.

Gibt die Anzahl der geschriebenen Bytes (nicht Zeichen) zurück.

ReadLine

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

TextZeile := File.ReadLine()

Gibt eine Textzeile zurück. Die Textzeile kann `n, `r`n oder `r enthalten, abhängig von der Datei und den EOL-Flags, die zum Ö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 endet, abhängig von den EOL-Flags, die zum Öffnen der Datei verwendet wurden. Rückt den Dateizeiger vor.

File.WriteLine(Zkette)
Zkette
Eine optionale Zeichenkette, die geschrieben werden soll.

Gibt die Anzahl der geschriebenen Bytes (nicht Zeichen) zurück.

ReadZahlTyp

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

Zahl := File.ReadZahlTyp()

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

Gibt bei Erfolg eine Zahl und bei Misserfolg eine leere Zeichenkette zurück.

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 von ZahlTyp größer als die Anzahl der gelesenen Bytes ist. Stattdessen werden die fehlenden Bytes als Null behandelt.

WriteZahlTyp

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

File.WriteZahlTyp(Zahl)
Zahl
Eine Zahl, die geschrieben werden soll.

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

Gibt die Anzahl der geschriebenen Bytes zurück. Zum Beispiel gibt WriteUInt bei Erfolg 4 zurück.

RawRead

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

File.RawRead(VarOderAdresse, Bytes)
VarOderAdresse
Eine Variable oder Speicheradresse, wohin die Daten kopiert werden sollen. Die Nutzung ähnelt der von NumGet(). Wenn eine Variable angegeben ist, wird sie automatisch erweitert, falls nötig.
Bytes
Die maximale Anzahl der Bytes, die gelesen werden sollen.

Gibt die Anzahl der gelesenen Bytes zurück.

Wenn eine Try-Anweisung aktiv ist und Bytes ungleich 0 ist, aber keine Bytes gelesen wurden, wird eine Ausnahme ausgelöst. Dies lässt sich mit AtEOF vermeiden, falls nötig.

RawWrite

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

File.RawWrite(VarOderAdresse, Bytes)
VarOderAdresse
Eine Variable, die die Daten oder die Adresse der Daten im Speicher enthält. Die Nutzung ähnelt der von NumPut().
Bytes
Die maximale Anzahl der Bytes, die geschrieben werden sollen.

Gibt die Anzahl der geschriebenen Bytes zurück.

Seek

Verschiebt den Dateizeiger.

File.Seek(Distanz , Startpunkt := 0)
File.Position := Distanz
File.Pos := Distanz
Distanz
Die Anzahl der Bytes, um die verschoben werden soll. Je kleiner der Wert, desto näher befindet sich 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.

Wenn Startpunkt weggelassen wird, wird standardmäßig SEEK_END verwendet, wenn Distanz negativ ist, andernfalls SEEK_SET.

Gibt bei Erfolg einen Wert ungleich 0 und bei Misserfolg eine 0 zurück.

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 Cache auf die Festplatte und hebt Freigabesperren auf.

File.Close()

Obwohl die Datei beim Freigeben des Objekts automatisch geschlossen wird, ist es ratsam, die Datei so früh wie möglich zu schließen.

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 echten Datei verwendet werden. Wenn das File-Objekt von einem Handle erzeugt wurde, das auf ein Pipe verweist, kann Length die Menge der Daten zurückgeben, die gerade im internen Pufferspeicher des Pipe verfügbar sind, aber dieses Verhalten ist nicht garantiert.

AtEOF

Ermittelt einen Wert ungleich 0, wenn der Dateizeiger das Ende der Datei erreicht hat, andernfalls 0.

IsAtEOF := File.AtEOF

Diese Eigenschaft sollte nur mit einer echten Datei verwendet werden. Wenn das File-Objekt von einem Handle erzeugt wurde, das auf ein nicht-suchendes Device wie Konsolenpuffer oder Pipe verweist, kann der Rückgabewert bedeutungslos sein, da solche Devices logischerweise kein "End of File" haben.

Encoding

Ermittelt oder setzt die Textkodierung des File-Objekts.

ErmittelteKodierung := File.Encoding
File.Encoding := NeueKodierung

ErmittelteKodierung und NeueKodierung ist ein numerischer Codepageidentifikator (siehe Microsoft Docs) oder eine der folgenden Zeichenketten:

ErmittelteKodierung kann nie ein Wert mit dem Suffix -RAW sein, unabhängig davon, wie die Datei geöffnet wurde oder ob sie eine Byte-Order-Markierung (BOM) enthält. NeueKodierung bewirkt nicht, dass eine BOM hinzugefügt oder entfernt wird, da eine BOM normalerweise beim Erstellen der Datei hinzugefügt wird.

[v1.1.15.04+]: Das Setzen von NeueKodierung 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-Kodierung, wodurch alle ASCII-fremden Zeichen verworfen wurden. Dies gilt nur für File.Encoding, nicht für FileOpen().

Handle [v1.1.35+]

Alias von __Handle.

File.Handle

__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. Enthält der Pufferspeicher Daten, die aus einer Datei gelesen wurden, werden diese verworfen und der Dateizeiger auf die logische Position (widergespiegelt von File.Pos) zurückgesetzt.