fread_charT_fread_charFreadCharFreadCharfread_char (Operator)

Name

fread_charT_fread_charFreadCharFreadCharfread_char — Read one character from a text file.

Signature

fread_char( : : FileHandle : Char)

Herror T_fread_char(const Htuple FileHandle, Htuple* Char)

void FreadChar(const HTuple& FileHandle, HTuple* Char)

HString HFile::FreadChar() const

static void HOperatorSet.FreadChar(HTuple fileHandle, out HTuple charVal)

string HFile.FreadChar()

def fread_char(file_handle: HHandle) -> str

Description

The operator fread_charfread_charFreadCharFreadCharFreadCharfread_char reads a character from the input file defined by FileHandleFileHandleFileHandleFileHandlefileHandlefile_handle. The input file must have been opened with open_fileopen_fileOpenFileOpenFileOpenFileopen_file in text format.

The read character or the control character sequence 'eof' is returned in parameter CharCharCharCharcharValchar. The operator fread_charfread_charFreadCharFreadCharFreadCharfread_char respects the encoding of the characters, unless the file was opened with the option 'ignore_encoding'"ignore_encoding""ignore_encoding""ignore_encoding""ignore_encoding""ignore_encoding" (see open_fileopen_fileOpenFileOpenFileOpenFileopen_file). Thus, when opened with the correct encoding the operator fread_charfread_charFreadCharFreadCharFreadCharfread_char returns multi-byte characters at once. If necessary, the character is transcoded into the current encoding of the HALCON library (see set_system(::'filename_encoding',<encoding>:)set_system("filename_encoding",<encoding>)SetSystem("filename_encoding",<encoding>)SetSystem("filename_encoding",<encoding>)SetSystem("filename_encoding",<encoding>)set_system("filename_encoding",<encoding>)).

When the file was opened with encoding mode 'ignore_encoding'"ignore_encoding""ignore_encoding""ignore_encoding""ignore_encoding""ignore_encoding", CharCharCharCharcharValchar always returns one byte without any interpretation or transcoding. This is useful for reading a file with special control bytes in a kind of raw mode. If no character can be read because the end of the file is reached, fread_charfread_charFreadCharFreadCharFreadCharfread_char returns the control character sequence 'eof'"eof""eof""eof""eof""eof" in CharCharCharCharcharValchar.

The operator fread_charfread_charFreadCharFreadCharFreadCharfread_char emits a low-level error message, when the next byte or byte sequence does not represent a valid code point in the specified encoding. Despite of the low-level error message, the operator will not fail and CharCharCharCharcharValchar will contain the next byte. Furthermore, the operator also emits a low-level error message, when the read character cannot be transcoded without loss of information into the current encoding of the HALCON library. 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.

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

Read character, which can be multi-byte or the control string 'eof'"eof""eof""eof""eof""eof".

Example (HDevelop)

* Read a text file character by character.
open_file (FileName, 'input', FileHandle)
repeat
    fread_char (FileHandle, Char)
until (Char == 'eof')
close_file (FileHandle)

Result

If an input file is open, the operator fread_charfread_charFreadCharFreadCharFreadCharfread_char returns 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_stringfread_stringFreadStringFreadStringFreadStringfread_string, read_stringread_stringReadStringReadStringReadStringread_string, fread_linefread_lineFreadLineFreadLineFreadLinefread_line

See also

open_fileopen_fileOpenFileOpenFileOpenFileopen_file, close_fileclose_fileCloseFileCloseFileCloseFileclose_file, fread_stringfread_stringFreadStringFreadStringFreadStringfread_string, fread_linefread_lineFreadLineFreadLineFreadLinefread_line

Module

Foundation