fread_stringT_fread_stringFreadStringFreadStringfread_string (Operator)

Name

fread_stringT_fread_stringFreadStringFreadStringfread_string — Read a string from a text file.

Signature

fread_string( : : FileHandle : OutString, IsEOF)

Herror T_fread_string(const Htuple FileHandle, Htuple* OutString, Htuple* IsEOF)

void FreadString(const HTuple& FileHandle, HTuple* OutString, HTuple* IsEOF)

HString HFile::FreadString(Hlong* IsEOF) const

static void HOperatorSet.FreadString(HTuple fileHandle, out HTuple outString, out HTuple isEOF)

string HFile.FreadString(out int isEOF)

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

Description

The operator fread_stringfread_stringFreadStringFreadStringFreadStringfread_string reads a string 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.

A string begins with the first character that is not a separator, i.e., that is no white space or line break: all other characters, mainly letters, numbers, and all other printable characters, but also all other control characters that are no separators are added to the output string. The string ends at the first separator character after one or more accepted characters, or when the end of the file was reached. The terminating separator character is not added to the output string, but the file position indicator remains after it. Thus, a subsequent read operation on the file would start after the terminating separator character. The read character sequence is returned in parameter OutStringOutStringOutStringOutStringoutStringout_string. If needed, the output string is transcoded into the current encoding of the HALCON library (the default is UTF-8).

The range of characters that are handled as separator depends on the file encoding, which can be specified when the file is opened. The character ' '" "" "" "" "" " (space) and the standard ASCII whitespace control characters '\t'"\t""\t""\t""\t""\t" (tab), '\f'"\f""\f""\f""\f""\f" (form feed), '\n'"\n""\n""\n""\n""\n" (line feed), '\r'"\r""\r""\r""\r""\r" (carriage return), and '\v'"\v""\v""\v""\v""\v" (vertical tab) are all accepted as separator on all locales or when the encoding has to be ignored. Other encodings may provide additional separator characters, e.g., Latin-1 defines '0xA0'"0xA0""0xA0""0xA0""0xA0""0xA0" (no-break space) or Shift-JIS (as many other Asian encodings) defines '0x8140'"0x8140""0x8140""0x8140""0x8140""0x8140" (ideographic space) as valid separator. UTF-8 handles these characters also as a separator just as all other code points which in the Unicode standard are defined as white spaces in the categories space separators Zs, line separators Zl, and paragraph separators Zp.

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

The operator fread_stringfread_stringFreadStringFreadStringFreadStringfread_string 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 OutStringOutStringOutStringOutStringoutStringout_string 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.

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

Read character sequence.

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

Reached end of file before any character was added to the output string.

Example (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)

Example (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);

Example (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)

Example (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)

Example (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)

Result

If a file is open and a suitable string is read, fread_stringfread_stringFreadStringFreadStringFreadStringfread_string returns the value 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, read_stringread_stringReadStringReadStringReadStringread_string, fread_linefread_lineFreadLineFreadLineFreadLinefread_line

See also

open_fileopen_fileOpenFileOpenFileOpenFileopen_file, close_fileclose_fileCloseFileCloseFileCloseFileclose_file, fread_charfread_charFreadCharFreadCharFreadCharfread_char, fread_linefread_lineFreadLineFreadLineFreadLinefread_line

Module

Foundation