\(\text{FileReadString}\)

You can use the the \(\text{FileReadString}\) function to read a UTF-8 encoded text string from a file.

You can use the \filereadstring backslash command to insert this function.

The following variants of this function are available:

• \(\text{tuple } \text{FileReadString} \left ( \text{<file number>} \right )\)

• \(\text{tuple } \text{FileReadString} \left ( \text{<file number>}, \text{<length>} \right )\)

• \(\text{tuple } \text{FileReadString} \left ( \text{<file number>}, \text{<length>}, \text{<utf-8>} \right )\)

The \(\text{<file number>}\) parameter is an integer value returned by one of the \(\text{FileOpen}\ldots\) functions. The \(\text{<length>}\) parameter indicates how many bytes or characters should be read. The \(\text{<utf-8>}\) indicates if the \(\text{<length>}\) parameter indicates a count of UTF-8 characters or a count of bytes.

If the \(\text{<length>}\) parameter is negative, then all remaining content from the file will be read. In this mode, the \(\text{<utf-8}\) parameter is ignored.

If the \(\text{<length>}\) parameter is zero, then the contents up-to and including a newline character will be read. In this mode, the newline character will be removed from the text string. In this mode, the \(\text{<utf-8>}\) parameter is ignored.

If the \(\text{<length>}\) parameter is positive, then the length indicates the number of bytes or UTF-8 characters to be read. In this mode, if the \(\text{<utf-8>}\) parameter is true or excluded, then the \(\text{<length>}\) parameter represents the number of UTF-8 characters. If the \(\text{<utf-8>}\) parameter is false, then the \(\text{<length>}\) parameter indicates the number of bytes to be read.

The \(\text{FileReadString}\) function will return a tuple containing two entries:

• A tuple holding the read string.

• A boolean holding true on success or false on error.

The Figure 139 shows how you can use the \(\text{FileReadString}\) function.

Figure 139 Example Use Of The FileReadString Function