Package typhint

xmlconvert logo

How do type hints work? Overview

Type hints are special comments with a leading #| within a function body indicating the intended nature of the function’s arguments in terms of data types, dimensions and even permitted values. The actual parameters with which the function is called can be evaluated against these type hint comments using the check_types() function.

check_types() returns `FALSE if any of the checks fails. Checking can be aborted after the first error occurs, or it can be continued until all checks have been performed. Optionally, the user is shown a message indicating the nature of the problem with the function arguments. The messages can be completely customized using placerholder variables for all kinds of relevant information.

Type hint comments

Placement of comments

Type hint comments always need to be placed inside a function body and refer to the arguments of that function. They can be placed anywhere in the function body (even after the call of check_types(). Type hint comments are regular R comments but start with #| (hash plus pipe, without blanks in between). Each function argument will have its own type hint comment line. Type hint comments can cover a subset of all arguments, so there can be arguments without any type hint restrictions.

Comment syntax

Type hint comments consist of a data type check and (optionally) dimension and value checks:

When formulating dim or not restrictions you can use the values of other parameters of the function call. So, if you have a function with two arguments, a number of children (num.children) and a numeric vector with the ages of these children (age.children) you can have a type hint comment for the latter which looks like this:#| age.children numeric dim(num.children)`.

If a type hint check fails

If any of the checks fails check_types() returns FALSE, otherwise it returns TRUE. If show.msg=TRUE then a message will be shown in the R console. The messages can be customized using templates (see next section). Depending on the value of abort the checking of parameters is continued (abort=FALSE) or stopped immediately (abort=TRUE), i.e. no further checks are performed after the first error.

Type hint output messages

Message templates

The error messages that are shown (if show.msg=TRUE) when a check fails are based on templates. The templates are provided to the check_types() function via the messages argument. messages is a character vector with five elements, one for each possible kind of error message (or NULL, if the default error #’ messages shall be used); the types of error messages are:

The messages provided via the messages argument are templates that can use predefined placeholders to convey information relevant for understanding the problem.

Placeholder that can be used in message templates

Example

library(typehint)

celsius_to_fahrenheit <- function(degrees_celsius) {
    #| degrees_celsius numeric dim(1) not(NA, NULL)

    if(check_types()) return(degrees_celsius * 9/5 + 32)
    else return(NA)
}

res <- celsius_to_fahrenheit("100.0")

Contact the author

Joachim Zuckarelli

Twitter: [@jsugarelli](https://twitter.com/jsugarelli)

GitHub: https://github.com/jsugarelli/typehint