fread_lineT_fread_lineFreadLineFreadLinefread_line (Operator)

Name

fread_lineT_fread_lineFreadLineFreadLinefread_line — Read a character line from a text file.

Signature

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)

def fread_line(file_handle: HHandle) -> Tuple[str, int]

Description

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

The read line is returned in parameter OutLineOutLineOutLineOutLineoutLineout_line. 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_fileOpenFileOpenFileOpenFileopen_file. The standard line break characters are '\n'"\n""\n""\n""\n""\n" (line feed), '\r'"\r""\r""\r""\r""\r" (carriage return), and '\f'"\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""\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""\n" in the output string. In UTF-8 encoded files, the following Unicode control code points will also terminate the read line: U+0085 (next line), U+2028 (line separator), and U+2029 (paragraph separator).

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

The operator fread_linefread_lineFreadLineFreadLineFreadLinefread_line 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 OutLineOutLineOutLineOutLineoutLineout_line 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""locale" (see set_system(::'filename_encoding','locale':)set_system("filename_encoding","locale")SetSystem("filename_encoding","locale")SetSystem("filename_encoding","locale")SetSystem("filename_encoding","locale")set_system("filename_encoding","locale")).

Execution Information

Parameters

FileHandleFileHandleFileHandleFileHandlefileHandlefile_handle (input_control)  file HFile, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

File handle.

OutLineOutLineOutLineOutLineoutLineout_line (output_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Read line.

IsEOFIsEOFIsEOFIsEOFisEOFis_eof (output_control)  integer HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Reached end of file before any character was read.

Example (C)

do {
  fread_line(FileHandle,&Line,&IsEOF);
} while(IsEOF==0);

Result

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

Possible Predecessors

open_fileopen_fileOpenFileOpenFileOpenFileopen_file

Possible Successors

close_fileclose_fileCloseFileCloseFileCloseFileclose_file

Alternatives

fread_charfread_charFreadCharFreadCharFreadCharfread_char, fread_stringfread_stringFreadStringFreadStringFreadStringfread_string

See also

open_fileopen_fileOpenFileOpenFileOpenFileopen_file, close_fileclose_fileCloseFileCloseFileCloseFileclose_file, fread_charfread_charFreadCharFreadCharFreadCharfread_char, fread_stringfread_stringFreadStringFreadStringFreadStringfread_string

Module

Foundation