R: Custom conditions for vctrs package

vctrs-conditions {vctrs} | R Documentation

## Custom conditions for vctrs package

### Description

These functions are called for their side effect of raising errors and warnings. These conditions have custom classes and structures to make testing easier.

### Usage

    stop_incompatible_type(
      x,
      y,
      x_arg = "",
      y_arg = "",
      details = NULL,
      ...,
      message = NULL,
      class = NULL
    )

    stop_incompatible_cast(
      x,
      y,
      details = NULL,
      ...,
      x_arg = "",
      to_arg = "",
      message = NULL,
      class = NULL
    )

    stop_incompatible_op(
      op,
      x,
      y,
      details = NULL,
      ...,
      message = NULL,
      class = NULL
    )

    stop_incompatible_size(
      x,
      y,
      x_size,
      y_size,
      x_arg = "",
      y_arg = "",
      details = NULL,
      ...,
      message = NULL,
      class = NULL
    )

    maybe_lossy_cast(
      result,
      x,
      to,
      lossy = NULL,
      locations = NULL,
      details = NULL,
      ...,
      x_arg = "",
      to_arg = "",
      message = NULL,
      class = NULL,
      .deprecation = FALSE
    )

    allow_lossy_cast(expr, x_ptype = NULL, to_ptype = NULL)

### Arguments

`x, y` | Vectors
`details` | Any additional human readable details
`..., message, class` | Only use these fields when creating a subclass.
`result` | The result of a potentially lossy cast.
`to` | Type to cast to.
`lossy` | A logical vector indicating which elements of `result` were lossy. Can also be a single `TRUE`, but note that `locations` picks up locations from this vector by default. In this case, supply your own location vector, possibly empty.
`locations` | An optional integer vector giving the locations where `x` lost information.
`.deprecation` | If `TRUE`, the error is downgraded to a deprecation warning. This is useful for transitioning your class to a stricter conversion scheme. The warning advises your users to wrap their code with `allow_lossy_cast()`.
`x_ptype, to_ptype` | Suppress only the casting errors where `x` or `to` match these prototypes.
`subclass` | Use if you want to further customise the class

### Value

`stop_incompatible_*()` unconditionally raise an error of class `"vctrs_error_incompatible_*"` and `"vctrs_error_incompatible"`.

### Lossy cast errors

By default, lossy casts are an error. Use `allow_lossy_cast()` to silence these errors and continue with the partial results. In this case the lost values are typically set to `NA` or to a lower value resolution, depending on the type of cast.

Lossy cast errors are thrown by `maybe_lossy_cast()`. Unlike functions prefixed with `stop_`, `maybe_lossy_cast()` usually returns a result. If a lossy cast is detected, it throws an error, unless it's been wrapped in `allow_lossy_cast()`. In that case, it returns the result silently.

### Examples

    # Most of the time, `maybe_lossy_cast()` returns its input normally:
    maybe_lossy_cast(c("foo", "bar"), NULL, "", lossy = c(FALSE, FALSE))

    # If `lossy` has any `TRUE`, an error is thrown:
    try(maybe_lossy_cast(c("foo", "bar"), NULL, "", lossy = c(FALSE, TRUE)))

    # Unless lossy casts are allowed:
    allow_lossy_cast(
      maybe_lossy_cast(c("foo", "bar"), NULL, "", lossy = c(FALSE, TRUE))
    )

[Package vctrs version 0.2.4 Index]