assertthat v0.2.0

0

Monthly downloads

0th

Percentile

by Hadley Wickham

Easy Pre and Post Assertions

assertthat is an extension to stopifnot() that makes it easy to declare the pre and post conditions that you code should satisfy, while also producing friendly error messages so that your users know what they've done wrong.

Readme

assertthat

Travis-CI Build Status

assertthat provides a drop in replacement for stopifnot() that makes it easy to check the pre- and post-conditions of a function, while producing useful error messages.

x <- 1:10
stopifnot(is.character(x))
# Error: is.character(x) is not TRUE

assert_that(is.character(x))
# Error: x is not a character vector

assert_that(length(x) == 5)
# Error: length(x) not equal to 5

assert_that(is.numeric(x))
# [1] TRUE

This is a good defensive programming technique, and is useful as source-code documentation: you can see exactly what your function expects when you come back to it in the future. It is partly a response to the lack of static typing in R, but it allows you to test for general conditions (like length(x) == length(y)) that are difficult to express in a type system.

assertthat can be installed either from CRAN:

install.packages('assertthat')

or with devtools:

devtools::install_github("hadley/assertthat")

New assertions

As well as all the functions provided by R, assertthat provides a few more that I use a lot:

  • is.flag(x): is x TRUE or FALSE? (a boolean flag)
  • is.string(x): is x a length 1 character vector?
  • has_name(x, nm), x %has_name% nm: does x have component nm?
  • has_attr(x, attr), x %has_attr% attr: does x have attribute attr?
  • is.count(x): is x a single positive integer?
  • are_equal(x, y): are x and y equal?
  • not_empty(x): are all dimensions of x greater than 0?
  • noNA(x): is x free from missing values?
  • is.dir(path): is path a directory?
  • is.writeable(path)/is.readable(path): is path writeable/readable?
  • has_extension(path, extension): does file have given extension?

assert_that, see_if and validate_that

There are three main functions in assertthat:

  • assert_that() signal an error

  • see_if() returns a logical value, with the error message as an attribute.

  • validate_that() returns TRUE on success, otherwise returns the error as a string.

You'll use assert_that() in your own code, but you'll mostly see see_if() in the examples (because R CMD check requires that examples run without errors). Use validate_that() for S4 validate methods.

Writing your own assertions

If you're writing your own assertions, you can provide custom error messages using the on_failure() helper:

is_odd <- function(x) {
  assert_that(is.numeric(x), length(x) == 1)
  x %% 2 == 1
}
assert_that(is_odd(2))
# Error: is_odd(x = 2) is not TRUE

on_failure(is_odd) <- function(call, env) {
  paste0(deparse(call$x), " is even")
}
assert_that(is_odd(2))
# Error: 2 is even

The on_failure callback is called with two arguments, the unevaluated function call (which has already been standardised with match.call()), and env, and the environment in which the assertion was executed. This allows you to choose between displaying values or names in your error messages. Read the advanced R book to learn more about working with calls.

Also note the use of assert_that() in our new function: assertions flow through function calls ensuring that you get a useful error message at the top level:

assert_that(is_odd("b"))
# Error: x is not a numeric or integer vector
assert_that(is_odd(1:2))
# Error: length(x) not equal to 1

Functions in assertthat

Name Description
has_args Check a function has specified arguments
has_attr Has attribute or name?
noNA Does object contain any missing values?
not_empty Check an object doesn't have any empty dimensions
assert_that Assert that certain conditions are true.
validate_that Validate that certain conditions are true.
are_equal Are two objects equal?
assert-is Missing is functions.
on_failure Custom failure messages for assertions.
scalar Assert input is a scalar.
assertions-file Useful test related to files
No Results!

Last month downloads

Details

License GPL-3
Collate 'assert-that.r' 'on-failure.r' 'assertions-file.r' 'assertions-scalar.R' 'assertions.r' 'base.r' 'base-comparison.r' 'base-is.r' 'base-logical.r' 'base-misc.r' 'utils.r' 'validate-that.R'
RoxygenNote 6.0.1
NeedsCompilation no
Packaged 2017-04-10 19:00:43 UTC; hadley
Repository CRAN
Date/Publication 2017-04-11 21:28:45 UTC
suggests testthat
imports tools
Contributors

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/assertthat)](http://www.rdocumentation.org/packages/assertthat)