\(\text{FileReadInteger}\)

You can use the the \(\text{FileReadInteger}\) function to read a single integer value.

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

The following variants of this function are available:

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

  • \(\text{tuple } \text{FileReadInteger} \left ( \text{<file number>}, \text{<size/endian>} \right )\)

The \(\text{<file number>}\) parameter is an integer value returned by one of the \(\text{FileOpen}\ldots\) functions. The \(\text{<size/endian>}\) parameter indicates how the integer value to be read is encoded in the file.

If the \(\text{<size/endian>}\) value is not included or is zero, then the \(\text{FileReadInteger}\) function assumes that the integer is encoded as a string representing the integer value. The integer value can include an initial - character to indicate a negative value or can be prepended with 0x or 0b to indicate an unsigned base-16 or base-2 value. In this mode, the \(\text{FileReadInteger}\) function will read up-to but excluding the first non-digit character.

If the \(\text{<size/endian>}\) value is greater than zero, then the \(\text{FileReadInteger}\) function assumes that the integer is in a little-endian signed binary format. In this mode, the integer value will be interpreted as

\[\begin{split}r = \begin{cases} \displaystyle\sum_{i=0}^{N-1} 256 ^ i \cdot b _ { p + i } & \text{if } b _ { p + N - 1 } \leq 127 \\ 256 ^ N - \displaystyle\sum_{i=0}^{N-1} 256 ^ i \cdot b _ { p + i } & \text{otherwise} \end{cases}\end{split}\]

where \(r\) is the integer result, \(b\) represents the file bytes as an array of values, \(p\) represents the current file position, and \(N\) represents the \(\text{<size/endian>}\) value supplied to the function.

If the \(\text{<size/endian>}\) value is less than zero, then the \(\text{FileReadInteger}\) function assumes that the integer is in a big-endian signed binary format. In this mode, the integer value will be interpreted as

\[\begin{split}r = \begin{cases} \displaystyle\sum_{i=0}^{N-1} 256 ^ { N - i - 1 } \cdot b _ { p + i } & \text{if } b _ p \leq 127 \\ 256 ^ N - \displaystyle\sum_{i=0}^{N-1} 256 ^ { N - i - 1 } \cdot b _ { p + i } & \text{otherwise} \end{cases}\end{split}\]

The maximum size integer that can be read is 8 bytes. Specifying a \(\text{<size/endian>}\) value with a magnitude greater than 8 will cause only 8 bytes to be read in little-endian or big-endian format.

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

  • The integer value read from the file.

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

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