Hmisc (version 5.3-1)

warn_once: Issue a Warning Only Once Per Session

Description

Issues a warning the first time a given warning is requested in an R session and silently ignores later requests for the same warning. This is useful for advisory warnings (e.g., recommending a better method) that would otherwise be repeated many times, for example when a function is called inside a bootstrap loop.

Usage

warn_once(msg, id = msg, reset = FALSE, call. = FALSE, immediate. = FALSE)

Value

Invisibly, `TRUE` if a warning was issued and `FALSE` if it was suppressed because it had already been issued. When `reset = TRUE`, invisibly `NULL`.

Arguments

msg

character string containing the warning message. Multiple strings are pasted together with no separator, as in [base::warning()]. May be omitted when `reset = TRUE` and all records are to be cleared.

id

character string identifying the warning for the purpose of deciding whether it has already been issued. Defaults to `msg`.

reset

set to `TRUE` to forget that a warning has been issued so that it will be issued again the next time it is requested. If `msg` and `id` are both omitted, the records of all warnings are cleared; otherwise only the warning identified by `id` is cleared. No warning is issued when `reset = TRUE`. Mainly useful in examples and tests.

call.

logical; if `TRUE` the call that invoked `warn_once` is included in the warning. Default is `FALSE`.

immediate.

logical; if `TRUE` the warning is printed immediately rather than being deferred until the top-level call completes. Passed to [base::warning()].

Author

Frank Harrell

Details

Warnings are identified by `id`, which by default is the message text itself, so two calls with identical text are treated as the same warning. Supply `id` explicitly when the message text varies from call to call (for example, when it contains a sample size) but the warning should still be shown only once.

The record of warnings already issued is kept in an environment inside the package namespace, so it lasts for the current R session only and is empty when R starts. Nothing is written to the global environment.

Unlike `options(warn = -1)`, which silences all warnings, only repeats of the warning identified by `id` are suppressed. Warnings issued by [base::warning()] and other functions are unaffected.

See Also

[base::warning()], [base::suppressWarnings()]

Examples

warn_once('method="loess" is recommended', reset = TRUE)
f <- function() {
  warn_once('method="loess" is recommended')
  invisible()
}
f()   # issues the warning
f()   # silent: same text has already been warned about
f()   # silent

## Different text, but treated as the same warning because of id
g <- function(n) {
  warn_once(paste('n =', n, 'is small'), id = 'small.n')
  invisible()
}
g(10)  # issues the warning
g(12)  # silent

## Make the warning appear again
warn_once(reset = TRUE)
f()   # issues the warning again