set_eof_check: Set EOF (End-of-file) handling for this connection

Description

When the end-of-file is reached and values are requested from the connection, how should a read call check and react?

Usage

set_eof_check(con, eof_check = "error")

Value

Modified connection object

Arguments

con

Connection object or raw vector. Connection objects can be created with file(), url(), rawConnection() or any of the other many connection creation functions.

eof_check

Default EOF checking behaviour. One of: 'ignore', 'warn', 'error' Default: 'error'.

ignore: No explicit checks will be made for EOF. The underlying R functions (e.g. readBin(), writeBin()) may still do checking.

warn

Explicit checks will be made for reading data at EOF. If this occurs, then a warning() will be issued.

error

Explicit checks will be made for reading data at EOF. If any are found, then a error will be raised.

Details

Note: R's readBin() does not necessarily react when the end-of-file is reached, and in many situations all that will happen is that fewer data values will be returned than what was requested.

By setting this option on the connection, work is done to check the count of returned values after every call to try and detect when the end-of-file has been reached.

Examples

Run this code

if (FALSE) { # interactive()
# Open a connection and configure it so reading past the end-of-file 
# ignored, and operations simply return fewer values than requested
con <- rawConnection(as.raw(1:8), "rb")
con <- set_eof_check(con, eof_check = "ignore")

# There are only 8 bytes in the connection. 
# Attempting to read 12 bytes will reach the end of the file.
# Because "eof_check" has been set to "ignore", there will just be
# silent truncation of the data
read_uint8(con, n = 12)

# The connection can be configured to raise an error or warning
# when EOF is reached
con <- set_eof_check(con, eof_check = "warn")
read_uint8(con, n = 12)

close(con)
}