man-roxygen/safe_read_csv.R

In jeanmathieupotvin/cargo: Data containers, schemas and prototypes

# safe_read_csv.R


#' @title
#' Safe and fast reading of CSV files
#'
#' @description
#' A convenient wrapper to [data.table::fread()] enabling a safe reading mode
#' while still being fast.
#'
#' @param x a character. A file path pointing to a CSV file.
#' @param ... additional arguments. For [safe_read_ops()], these will either
#' be added to the list or override default values. For [safe_read_csv()], these
#' will be first passed to [safe_read_csv()] and then to [data.table::fread()].
#'
#' @return
#' Function [safe_read_csv()] returns a
#' [`data.table`][data.table::data.table()]. There is one exception: if the
#' `data.table` option of [data.table::fread()] is passed to [safe_read_csv()]
#' with a `FALSE` value, a `data.frame` will be returned.
#'
#' Function [safe_read_ops()] returns a named list.
#'
#' @details
#' Function [safe_read_csv()] implements 4 tests on `x`:
#' * it checks that it is a character of length 1;
#' * it checks that it points to a valid file that exists without being a
#' directory;
#' * it checks that its extension is effectively CSV (and nothing else);
#' * it checks that a binary connection can be created for reading.
#'
#' If all tests are passed, then the file will be read with some pre-defined
#' convenient [data.table::fread()] parameters. Any error and/or warning
#' messages encountered by this function will be conveyed to the user.
#'
#' The user can consult the list of default values passed to
#' [data.table::fread()] by calling [safe_read_ops()]. These options can be
#' overriden through argument `...` of [safe_read_csv()].