Defensive Programming and Input Validation

The idea behind defensive programming is to move a failure as close as possible to its cause. A function that receives "300" where it wants a number can fail in three ways. It can fail late and far away: the first arithmetic on the string raises non-numeric argument to binary operator from inside some helper, and the message names an operator, not the argument that was wrong. It can fail silently: mean("300") returns NA with a warning that is easy to miss, and the NA then flows into a report. Or it can fail at once, at the top of the function, with a message that says which argument was wrong and what was expected. The first script shows the first two failures on the shelf scenario and the third as the repair.

Source: R documentation: stopifnot

average_pages("300") first returns NA with the warning argument is not numeric or logical: returning NA, which tryCatch(warning = ) turns into a value so the text can be shown; with the warning suppressed the caller sees only NA. The checked version also repairs a second, quieter problem: books$pages contains two NA values, and the checked function computes the mean of the known page counts on purpose (na.rm = TRUE) instead of returning NA by accident of the data. The point of a check is not only to reject bad input but to make the decisions about edge cases explicit.

Where to put the checks matters as much as how to write them. Three kinds of problem call for three different tools:

The checks belong at the boundary of the system: the exported functions of a package, the constructor of a class, the function that reads a file or a request. Inside, the functions can trust what the boundary let through and do one cheap check or none. This is also how the book class of the shelf scenario is layered, which the second script shows.

Source: R documentation: stopifnot

new_book() is the low-level constructor: it checks only the types, with an unnamed stopifnot(), and its message is the text of the failed expression. The pitfall in the first call is typical: 2019 is a double, and the constructor asks for an integer, so year = 2019L (or as.integer()) is needed; the user-facing book() helper does the conversion itself, which is why book("Orchard Logic", year = 2200) reaches the value check and not the type check. validate_book() checks values and signals plain errors with stop(..., call. = FALSE), which is a reasonable choice for messages that go to the end user, and the helper cleans the input (trimws(), normalise_isbn(), as.integer()) before the checks run. Inside, page_count() trusts a book and verifies only that it was given one.

stopifnot() is the most used validation tool in base R. Its help page says it is meant for regression tests and for checking the arguments of functions, where it makes the code easier to read (R documentation: stopifnot). It takes any number of expressions, evaluates them one after the other, and if one of them is not a logical vector of TRUE values it calls stop() with a message naming that expression. The help page gives the equivalent code: stopifnot(A, B) is conceptually if (any(is.na(A)) || !all(A)) stop(...) followed by the same for B. Two consequences follow. An NA is not good enough, because the point of an assertion is that the condition is known to hold. And a vector passes only when all of its elements are TRUE, so the idiom stopifnot(x > 0) checks a whole vector in one expression.

A check has two halves: the type of the value (is it a character vector, a function, a data frame?) and its shape (how long, how many missing values, within what range?). Most mistakes in real programs come from forgetting the second half, so the examples below combine them.

An argument that must be one of a few strings is the classic case for match.arg(). The function declares the set as the default value, status = c("all", "out", "overdue", "returned"), and match.arg(status) replaces the vector by the validated choice: the first element when the caller passed nothing, the full name when the caller passed an abbreviation, and an error for anything else. In the one-argument form the choices are read from the default of the formal argument of the calling function, so the set is written once, in the signature, where args() and the help page show it. Matching uses pmatch(), so an abbreviation is accepted when it is unambiguous, and the empty string never matches (R documentation: match.arg). The mechanics and the interaction with the dots are described on Functions; this page looks at it as a validator.

Source: R documentation: match.arg

The error message lists the allowed values, which is what the user needs, but three of its properties are worth knowing. Its call is match.arg(status), not the call of loan_report(), so the console shows Error in match.arg(status) : 'arg' should be one of ...; the user sees the name of the argument but not the function they called, and the traceback described on Debugging is the way to find the caller when many functions share an argument name. The wording depends on the input: a number gives 'arg' must be NULL or a character vector, a vector of length two or a zero-length vector gives 'arg' must be of length 1, and anything else that does not match gives the should be one of message. And the help page warns that the wording of these messages is liable to change, and that it did change in R 4.2.0, so a package must not test for them. A test should check that an error is signalled, or catch it and check only the part that matters. When the call or the wording is important, validate by hand with %in% and signal a classed condition, as shown below.

NULL is accepted and means "take the first choice", which matters for a caller that builds the argument programmatically and passes NULL for "use the default". The R 4.2.0 NEWS records a better error message for match.arg("", ...).

An argument without a default that the caller did not supply is an error only when the function first evaluates it, which can be far from the top of the function, so the message argument "x" is missing, with no default appears at the use, not at the call. The error names the call (here double_it()) but not the position in the body. The error has the class missingArgError: the R 4.5.0 NEWS mentions that class, with a subclass "getMissingError" for get(), and uses f <- function(x) exp(x); try(f()) as the example of the situation. A handler can therefore select on the class instead of on the message (R NEWS: Changes in R 4.5.0). The class vector has further subclasses whose names depend on how the error was signalled, so test for "missingArgError" with inherits() and do not print the whole vector.

missing(x) is TRUE when the caller did not supply x, and is the way to turn the late, obscure error into an early one with a clear message. A stricter alternative to the default NULL is not to give a default at all and to check with missing() at the top, as borrow() does with named conditions. nargs() counts the arguments that were supplied, including empty ones, which is useful for functions that accept one of several argument combinations. The mechanics of missing() (for example that it follows an argument forwarded through another function, and that it becomes FALSE once the argument is assigned to) are described on Functions, and the deferred evaluation that explains the late error is the subject of Lazy Evaluation and Promises.

Source: R documentation: missing

For an optional argument the usual choice is a default of NULL and a replacement inside the function, and R 4.4.0 added an operator for the replacement: L %||% R returns L unless L is NULL, in which case it returns R. The NEWS entry describes it as an expressive form of the two phrases if (!is.null(L)) L else R and if (is.null(L)) R else L (R NEWS: Changes in R 4.4.0); it is documented with the control-flow constructs (R documentation: Control). Only NULL triggers the replacement: character(), NA and the empty string are values and are passed through, which is why character() %||% "fallback" is character(0). For code that must run on R 4.3 or older, the operator can be defined in a few lines, and several packages define it for that reason.

Loops and the apply family are where defensive habits pay off, because the input that breaks them is usually the empty one, and the empty case rarely appears in the data used while writing the code.

The comparison operators answer a different question from the one if() asks. == compares element by element and returns a vector of the same length as its operands, with NA wherever an operand is NA; if() needs one TRUE or FALSE. The help page of identical() makes the point directly: identical() is the way to test exact equality in if and while conditions and in logical expressions with && and ||, because it always returns a single logical value, where == returns an object like its arguments (R documentation: identical). Three functions cover the three questions a program asks:

The reason to prefer all.equal() for computed numbers is R FAQ 7.31, "Why doesn’t R think these numbers are equal?": only integers and fractions whose denominator is a power of two are represented exactly, every other number is rounded to about 53 binary digits, so two floating point numbers are not reliably equal unless they were computed by the same algorithm, and not always even then. The FAQ uses sqrt(2) squared as its example and recommends all.equal(), which compares with a tolerance of .Machine$double.eps ^ 0.5 (R FAQ 7.31: Why doesn’t R think these numbers are equal?).

Source: R FAQ 7.31: Why doesn’t R think these numbers are equal?

The output of all.equal() is the part that people forget. all.equal(1, 1.1) is not FALSE but the string Mean relative difference: 0.1, and a string in if() gives argument is not interpretable as logical, so the idiom is isTRUE(all.equal(x, y)). The same tolerance applies to all.equal(1, 1 + 1e-7), which differs by more than 1.5e-8 and reports Mean relative difference: 1e-07, while a difference of 1e-9 is accepted. The text of the difference is useful in a test or in stopifnot(), which prints it, as the first script of this page showed.

isTRUE(x) is documented as the same as { is.logical(x) && length(x) == 1 && !is.na(x) && x }, so it is TRUE for exactly one logical TRUE and for nothing else: not for 1, not for "TRUE", not for NA, and not for a vector of two TRUE values. The help page adds the reason it exists: if (isTRUE(cond)) may be preferable to if (cond) because of NA (R documentation: Logic). R 3.5.0 made isTRUE() tolerant of attributes, so a named TRUE such as c(a = TRUE) now passes (the previous definition identical(x, TRUE) rejected it), and added isFALSE() defined in the same way. isFALSE(NA) is FALSE, so the pair gives a three-way test of a condition that may be NA: isTRUE(cond), isFALSE(cond), and otherwise unknown. %in% is another comparison that never returns NA and so is safe in a condition: NA %in% "Fiction" is FALSE, where NA == "Fiction" is NA.

R is generous about names, and the generosity hides typos. Three places allow a partial name. The $ operator on a list or a data frame returns the single element whose name starts with the given text. A function call matches an argument name partially when the formal comes before the dots; the manual states the three passes of the matching, exact, then partial, then positional, and that formals after ... can be matched only exactly (R-lang: Argument matching). And attr(x, "name") matches an attribute name partially unless exact = TRUE. The matching is sensible at the console, where it saves keystrokes, and a liability in a script, where books$yea works today and silently returns the wrong column the day somebody adds a year_end column, because after that the prefix is ambiguous and the result becomes NULL (the script shows two$ye returning NULL).

Source: R documentation: options

Three options turn the silent matching into a warning, and all three default to FALSE (R documentation: options):

Source: R documentation: options

In the output above, the $ warning has class simpleWarning and the call fields$ye, the argument warning has the class vector partialMatchWarning, warning, condition and the call of the function that received the argument, and the attribute warning reuses the wording of the argument warning although it comes from attr(). Set an option for the duration of a test run or in the .Rprofile of a development session (the file is described on Sessions, Workspaces and Startup), and restore the old values afterwards, as the script does with old <- options(...) and options(old). A test suite that runs with options(warn = 2) as well turns every partial match into an error. [[ is exact by default, so fields[["ye"]] is NULL; exact = FALSE allows a partial match; and exact = NA allows it but warns, which is the targeted way to find the places in an old script that rely on it. On data frames, dd[["ye"]] is NULL and dd[, "ye"] is an error, undefined columns selected, so the bracket forms are strict while $ is not. R 3.1.1 changed the data frame case of $ to warn only when warnPartialMatchDollar is TRUE: before that, $ on a data frame warned about every partial match.

stopifnot() and stop("message") produce errors that differ only in their text, and text is a poor interface. A caller who wants to skip a row with a bad ISBN but let every other error through would have to search the message for "invalid ISBN", which breaks when someone fixes the wording. The scenario’s own validate_book() has this limitation on purpose: its errors are plain simpleError conditions with call. = FALSE, so conditionCall() is NULL and only conditionMessage() tells them apart.

R lets a condition be an object with a class and with data. errorCondition(message, ..., class, call) and its sibling warningCondition() were added in R 3.6.0 to build such objects: the first argument is the message, any further named arguments become fields of the condition, class is prepended to the standard class vector, and call records the call to show. stop(cond) signals the object, and tryCatch() selects a handler by class (R documentation: conditions). The class hierarchy gives the same specific-to-general selection that exceptions give in other languages: the most specific class first, then a package-wide parent class such as shelf_error, then the built-in error. The full machinery is on Conditions and Error Handling; the script below is the validation side of it.

Source: R documentation: conditions

Four design points in the script. The helper shelf_abort() is the single place that builds the condition, so every error of the package has the parent class shelf_error and the same shape. Its default call = sys.call(-1L) records the call of the function that called the helper, check_book(...), and not the call of the helper itself, which is what stop() does for a plain message. The data that triggered the error travels as a field, e$isbn, so the handler reports the offending value without parsing a message. And the two layers stay separate: the type check at the top of check_book() is a stopifnot() that raises a plain error for a programming mistake, which import_one(42) shows passing through the shelf handlers untouched, and only the data error is classed. The last block applies the pattern to a whole column: vapply() over books$isbn, each element wrapped by a handler that returns a status string, finds the two bad rows (the empty ISBN and the one with a wrong check digit) in one pass without stopping at the first, the situation that a plain stop() cannot express without text matching.

A custom class is part of a package’s interface: document it, keep the names stable, and prefix them with the package name to avoid clashes (shelf_invalid_isbn, not invalid_isbn). R 4.4.0 made tools::xgettext() stop extracting the class names in errorCondition() and warningCondition() calls as translatable strings, since they are identifiers and not messages. R-devel NEWS (4.7.0, under development, not available in R 4.6.1) lists two new built-in classes for failed lookups, objectNotFoundError for an object that is not found and functionNotFoundError for a function that is not found, and says that the classes used internally for signalling some errors are now documented in ?conditions; that would let a handler select a missing function without parsing the message, and it is mentioned here only as upcoming (R-devel NEWS).

Validation also protects the callers of an old function. A function that is going to be removed should say so for a release or two, and then fail with an explanation, and base R has a pair of helpers for the two steps. .Deprecated(new, package, msg, old) signals a warning whose default text names the old function and the one to use instead, and tells the user to see help("Deprecated"); .Defunct() signals an error for a function that has been retired (R documentation: Deprecated). Since R 3.6.0 the warning has class deprecatedWarning and the error class defunctError, so a test or a caller can select them without matching text, and the condition keeps the fields old, new and package.

Source: R documentation: Deprecated

Base R follows the same two steps for its own functions. is.R(), which asked whether code ran in R rather than in S-PLUS, was deprecated in R 4.4.0 and is defunct since R 4.5.0, whose NEWS also says that the environment variable _R_DEPRECATED_IS_R_ no longer has any effect. A guard such as exists("is.R") && is.R() in older code now stops with 'is.R' is defunct., and the repair is to delete the test (R documentation: base-defunct; What’s New and Migrating Older Code).

The wording of the default message is built from the name of the function that called .Deprecated() unless old is given, which is why shelf_old() passes old = "shelf_old" and package = "shelf" explicitly when the function lives in a package. The msg argument replaces the whole text for a case like a renamed argument. A common policy is to deprecate in one release, keep the function working while it warns, make it defunct in a later one, and remove it after that, with an entry in the package NEWS at each step; the final block shows how a caller that knows about the deprecation and wants the old behaviour for now can mute exactly that warning class with a calling handler and the muffleWarning restart, leaving other warnings visible. The mechanism is described on Conditions and Error Handling.

Writing the checks by hand for every argument gets repetitive, and several packages provide a vocabulary for it. This section covers one of them, checkmate (checkmate package documentation, version 2.3.4 here), a CRAN package of argument checks, a substantial part of which is written in C so that the checks can sit in frequently called functions. It is optional: everything above is base R, and a package that wants to stay dependency-free can ship a few of its own is_* helpers. For each kind of check checkmate provides three functions: assert_*() stops with an informative message that names the checked expression and returns its argument invisibly, check_*() returns TRUE or the text of the problem, and test_*() returns TRUE or FALSE. The camel-case spellings (assertString(), checkString()) are equivalent. qassert() states a whole rule in a short string, "I1" for one integer, "N1" for one number, with optional bounds. Functions such as assert_choice(), assert_data_frame() and assert_class() cover the cases that match.arg(), is.data.frame() and inherits() handle in base R, and assert() combines several checks with "or" semantics (checkmate package documentation: assert).

Source: checkmate package documentation: checkIntegerish

The messages follow a fixed pattern, Assertion on '<expression>' failed: <what is wrong>., and the call recorded in the condition is the function that contains the assertion, as with stopifnot(). assert_integerish() accepts a double that holds a whole number, which is what a user typing 300 at the console supplies, and rejects 1.5 with a message that says the element is not close to an integer; the arguments lower, len and any.missing express the range, the length and the NA rule that the hand-written is_count() above checks with four operands. The second line, assert_string(title, min.chars = 1), states in one call that the title is a single string that is not missing and not empty. The classes are plain simpleError conditions, so tryCatch() can select them only by message, not by class, which is one reason to use the classed conditions of the previous section for data errors and to keep checkmate for programming errors. Further documentation: checkmate package documentation: qassert, checkmate package documentation: checkString and checkmate package documentation: checkChoice.

The sections above each carry their own pitfalls; this table puts the main ones next to the help page or FAQ entry that explains them.

Source: R FAQ 7.31: Why doesn’t R think these numbers are equal?

Source: R NEWS: Changes in R 3.1.1 to 3.6.0

The entries for R 4.0.0 and later are in R NEWS: Changes in R 4.0.0 to 4.6.0, and the R-devel entries in the development NEWS; they may change before 4.7.0 is released.

Many pages on the web predate R 4.0.0 and some predate R 3.5.0. The table lists what they do differently from the current practice used on this page.

Source: R NEWS: Changes in R 4.0.0 to 4.6.0

For the full list of changes by release see What’s New and Migrating Older Code.