fread_lineT_fread_lineFreadLineFreadLine (Operator)


fread_lineT_fread_lineFreadLineFreadLine — Read a character line from a text file.


fread_line( : : FileHandle : OutLine, IsEOF)

Herror T_fread_line(const Htuple FileHandle, Htuple* OutLine, Htuple* IsEOF)

void FreadLine(const HTuple& FileHandle, HTuple* OutLine, HTuple* IsEOF)

HString HFile::FreadLine(Hlong* IsEOF) const

static void HOperatorSet.FreadLine(HTuple fileHandle, out HTuple outLine, out HTuple isEOF)

string HFile.FreadLine(out int isEOF)


The operator fread_linefread_lineFreadLineFreadLineFreadLine reads a whole line (including the line break character) from the input file defined by the handle FileHandleFileHandleFileHandleFileHandlefileHandle. The input file must have been opened with open_fileopen_fileOpenFileOpenFileOpenFile in text format.

The read line is returned in parameter OutLineOutLineOutLineOutLineoutLine. It starts at the current file position and ends at the end of the file or with the first line break character found. A subsequent read operation on the file would start after the line break, i.e., at the beginning of the next line. If needed, the output string is transcoded into the current encoding of the HALCON library (the default is UTF-8).

The range of control characters that are handled as line break depends on the file encoding, which can be specified when the file is opened with open_fileopen_fileOpenFileOpenFileOpenFile. The standard line break characters are '\n'"\n""\n""\n""\n" (line feed), '\r'"\r""\r""\r""\r" (carriage return), and '\f'"\f""\f""\f""\f" (form feed). These characters are accepted on all encodings or when the encoding has to be ignored. The line break sequence '\r\n'"\r\n""\r\n""\r\n""\r\n" (carriage return + line feed), which is the default line break under Windows, is handled (on all systems) as one line break and returned as '\n'"\n""\n""\n""\n" in the output string. In UTF-8 encoded files, the following Unicode control code points will also terminate the read line: 'U+0085'"U+0085""U+0085""U+0085""U+0085" (next line), 'U+2028'"U+2028""U+2028""U+2028""U+2028" (line separator), and 'U+2029'"U+2029""U+2029""U+2029""U+2029" (paragraph separator).

If the end of the file is reached before any character was written to the output string, the parameter IsEOFIsEOFIsEOFIsEOFisEOF returns the value 1, otherwise 0.

The operator fread_linefread_lineFreadLineFreadLineFreadLine emits a low-level error message, when it encounters bytes that do not represent a valid code point in the specified encoding. Despite of the low-level error message, the operator will not fail and OutLineOutLineOutLineOutLineoutLine will contain potentially invalid bytes (invalid within the specified encoding). Furthermore, the operator also emits a low-level error message, when the output string cannot be transcoded without loss of information into the current encoding of the HALCON library. For a correctly encoded string this can only happen when the file is UTF-8 encoded and the current encoding of the HALCON library is 'locale'"locale""locale""locale""locale" (see set_system(::'filename_encoding','locale':)set_system("filename_encoding","locale")SetSystem("filename_encoding","locale")SetSystem("filename_encoding","locale")SetSystem("filename_encoding","locale")).

Execution Information


FileHandleFileHandleFileHandleFileHandlefileHandle (input_control)  file HFile, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

File handle.

OutLineOutLineOutLineOutLineoutLine (output_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Read line.

IsEOFIsEOFIsEOFIsEOFisEOF (output_control)  integer HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Reached end of file before any character was read.

Example (C)

do {
} while(IsEOF==0);


If the file is open and a suitable line is read, fread_linefread_lineFreadLineFreadLineFreadLine returns the value 2 (H_MSG_TRUE). Otherwise, an exception is raised. Encoding errors have no influence on the result state.

Possible Predecessors


Possible Successors



fread_charfread_charFreadCharFreadCharFreadChar, fread_stringfread_stringFreadStringFreadStringFreadString

See also

open_fileopen_fileOpenFileOpenFileOpenFile, close_fileclose_fileCloseFileCloseFileCloseFile, fread_charfread_charFreadCharFreadCharFreadChar, fread_stringfread_stringFreadStringFreadStringFreadString