fread_stringT_fread_stringFreadStringFreadStringfread_string (Operator)

Name

fread_stringT_fread_stringFreadStringFreadStringfread_string — Einlesen einer Zeichenkette aus einer Textdatei.

Signatur

fread_string( : : FileHandle : OutString, IsEOF)

Beschreibung

fread_stringfread_stringFreadStringFreadStringfread_string liest aus der aktuellen Eingabedatei einen String ein. Die Eingabedatei ist durch das Handle FileHandleFileHandleFileHandlefileHandlefile_handle definiert und muss mit open_fileopen_fileOpenFileOpenFileopen_file im Textformat geöffnet worden sein.

Ein String beginnt mit dem ersten Zeichen, das kein Trennzeichen ist. Das sind alle druckbaren Zeichen, aber auch alle Sonderzeichen, die weder Leerzeichen noch Zeilenumbruch sind. Ein String endet vor dem ersten Trennzeichen (Leerzeichen oder Zeilenumbruch), nachdem mindestens ein Zeichen in die Ausgabe übernommen wurde, oder wenn das Dateiende erreicht wurde. Das Trennzeichen, das den String beendet, wird nicht in die Ausgabe übernommen. Der Dateizeiger bleibt jedoch auf dem Zeichen nach dem Trennzeichen stehen, so dass ein nachfolgender Lesebefehl auf der Datei nach dem Trennzeichen weiterlesen würde. Die eingelesene Zeichenkette wird im Parameter OutStringOutStringOutStringoutStringout_string zurückgegeben. Falls notwendig, wird die Zeichenkette zuvor in das aktuell von der HALCON-Bibliothek verwendete Encoding (standardmäßig UTF-8) umgewandelt.

Welche Zeichen als Trennzeichen interpretiert werden, hängt von dem String-Encoding ab, das beim Öffnen der Datei mit open_fileopen_fileOpenFileOpenFileopen_file angegeben wurde. Das normale Leerzeichen ' '" "" "" "" " (space) sowie die Standard-ASCII-Trennzeichen '\t'"\t""\t""\t""\t" (tab), '\f'"\f""\f""\f""\f" (form feed), '\n'"\n""\n""\n""\n" (line feed), '\r'"\r""\r""\r""\r" (carriage return) und '\v'"\v""\v""\v""\v" (vertical tab) werden unabhängig vom Encoding immer als Trennzeichen akzeptiert.

Abhängig vom Encoding können weitere Trennzeichen hinzukommen. Latin-1 definiert z.B. '0xA0'"0xA0""0xA0""0xA0""0xA0" (no-break space) und Shift-JIS enthält wie viele andere asiatische Encodings ein ideographisches Leerzeichen ('0x8140'"0x8140""0x8140""0x8140""0x8140", ideographic space). Neben diesen Zeichen definiert der Unicode-Standard noch weitere Trennzeichen in insgesamt drei Kategorien: Leerzeichen (Zs), Zeilentrenner (Zl) und Absatztrenner (Zp).

Wenn das Ende der Datei erreicht wurde, bevor mindestens ein Zeichen in die Ausgabe übernommen wurde, liefert der Parameter IsEOFIsEOFIsEOFisEOFis_eof den Wert 1, ansonsten 0.

Stößt der Operator fread_stringfread_stringFreadStringFreadStringfread_string beim Lesen auf Bytes, die im angegebenen Encoding kein gültiges Zeichen ergeben, wird ein Low-Level-Fehler ausgegeben. Unabhängig von dem Low-Level-Fehler wird fread_stringfread_stringFreadStringFreadStringfread_string jedoch normal beendet, wobei der Ausgabestring OutStringOutStringOutStringoutStringout_string ungültige Zeichen enthalten kann. Darüber hinaus wird ein Low-Level-Fehler erzeugt, wenn der eingelesene String nicht verlustfrei in das aktuelle Encoding der HALCON-Bibliothek umgewandelt werden kann. Dies kann für eine in der Datei korrekt kodierten Zeichenkette nur vorkommen, wenn die Datei UTF-8-kodiert ist und die HALCON-Bibliothek das lokale Encoding verwendet (s.a. set_system(::'filename_encoding','locale':)set_system("filename_encoding","locale")SetSystem("filename_encoding","locale")SetSystem("filename_encoding","locale")set_system("filename_encoding","locale")).

Ausführungsinformationen

Multithreading-Typ: reentrant (läuft parallel zu nicht-exklusiven Operatoren).
Multithreading-Bereich: global (kann von jedem Thread aufgerufen werden).
Wird ohne Parallelisierung verarbeitet.

Parameter

FileHandleFileHandleFileHandlefileHandlefile_handle (input_control) file → (handle)

Datei-Handle.

OutStringOutStringOutStringoutStringout_string (output_control) string → (string)

Eingelesene Zeichenkette.

IsEOFIsEOFIsEOFisEOFis_eof (output_control) integer → (integer)

Ende der Datei erreicht bevor mindestens ein Zeichen in die Ausgabe übernommen wurde.

Beispiel (HDevelop)

fwrite_string(FileHandle,'Please enter text and return: ..')
fread_string(FileHandle,String,IsEOF)
fwrite_string(FileHandle,['here it is again: ',String])
fnew_line(FileHandle)

Beispiel (C)

fwrite_string(FileHandle,"Please enter text and return: ..");
fread_string(FileHandle,&String,&IsEOF);
fwrite_string(FileHandle,"here it is again: ");
fwrite_string(FileHandle,String);
fnew_line(FileHandle);

Beispiel (HDevelop)

fwrite_string(FileHandle,'Please enter text and return: ..')
fread_string(FileHandle,String,IsEOF)
fwrite_string(FileHandle,['here it is again: ',String])
fnew_line(FileHandle)

Beispiel (HDevelop)

fwrite_string(FileHandle,'Please enter text and return: ..')
fread_string(FileHandle,String,IsEOF)
fwrite_string(FileHandle,['here it is again: ',String])
fnew_line(FileHandle)

Ergebnis

fread_stringfread_stringFreadStringFreadStringfread_string liefert den Wert 2 ( H_MSG_TRUE) , falls eine Datei geöffnet ist und ein geeigneter String eingelesen wird. Ansonsten wird eine Fehlerbehandlung durchgeführt. Encodingfehler haben keinen Einfluss auf den Rückgabewert.

Vorgänger

open_fileopen_fileOpenFileOpenFileopen_file

Nachfolger

close_fileclose_fileCloseFileCloseFileclose_file

Alternativen

fread_charfread_charFreadCharFreadCharfread_char, read_stringread_stringReadStringReadStringread_string, fread_linefread_lineFreadLineFreadLinefread_line

Siehe auch

open_fileopen_fileOpenFileOpenFileopen_file, close_fileclose_fileCloseFileCloseFileclose_file, fread_charfread_charFreadCharFreadCharfread_char, fread_linefread_lineFreadLineFreadLinefread_line

Modul

Foundation

Operatoren