R: Cast a vector to a specified type

vec_cast {vctrs} | R Documentation

## Cast a vector to a specified type

### Description

`vec_cast()` provides directional conversions from one type of vector to another. Along with `vec_ptype2()`, this generic forms the foundation of type coercions in vctrs.

### Usage

    vec_cast(x, to, ..., x_arg = "", to_arg = "")

    vec_cast_common(..., .to = NULL)

    ## S3 method for class 'logical'
    vec_cast(x, to, ...)

    ## S3 method for class 'integer'
    vec_cast(x, to, ...)

    ## S3 method for class 'double'
    vec_cast(x, to, ...)

    ## S3 method for class 'complex'
    vec_cast(x, to, ...)

    ## S3 method for class 'raw'
    vec_cast(x, to, ...)

    ## S3 method for class 'character'
    vec_cast(x, to, ...)

    ## S3 method for class 'list'
    vec_cast(x, to, ...)

### Arguments

`x` | Vectors to cast.
`to, .to` | Type to cast to. If `NULL`, `x` will be returned as is.
`...` | For `vec_cast_common()`, vectors to cast. For `vec_cast()`, `vec_cast_default()`, and `vec_restore()`, these dots are only for future extensions and should be empty.
`x_arg, to_arg` | Argument names for `x` and `to`. These are used in error messages to inform the user about the locations of incompatible types (see `stop_incompatible_type()`).

### Value

A vector the same length as `x` with the same type as `to`, or an error if the cast is not possible. An error is generated if information is lost when casting between compatible types (i.e. when there is no 1-to-1 mapping for a specific value).

### Implementing coercion methods

- For an overview of how these generics work and their roles in vctrs, see `?theory-faq-coercion`.

- For an example of implementing coercion methods for simple vectors, see `?howto-faq-coercion`.

- For an example of implementing coercion methods for data frame subclasses, see `?howto-faq-coercion-data-frame`.

- For a tutorial about implementing vctrs classes from scratch, see `vignette("s3-vector")`.

### Dependencies of `vec_cast_common()`

#### vctrs dependencies

- `vec_ptype2()`

- `vec_cast()`

#### base dependencies

Some functions enable a base-class fallback for `vec_cast_common()`. In that case the inputs are deemed compatible when they have the same base type and inherit from the same base class.

### See Also

Call `stop_incompatible_cast()` when you determine from the attributes that an input can't be cast to the target type.

### Examples

    # x is a double, but no information is lost
    vec_cast(1, integer())

    # When information is lost the cast fails
    try(vec_cast(c(1, 1.5), integer()))
    try(vec_cast(c(1, 2), logical()))

    # You can suppress this error and get the partial results
    allow_lossy_cast(vec_cast(c(1, 1.5), integer()))
    allow_lossy_cast(vec_cast(c(1, 2), logical()))

    # By default this suppress all lossy cast errors without
    # distinction, but you can be specific about what cast is allowed
    # by supplying prototypes
    allow_lossy_cast(vec_cast(c(1, 1.5), integer()), to_ptype = integer())
    try(allow_lossy_cast(vec_cast(c(1, 2), logical()), to_ptype = integer()))

    # No sensible coercion is possible so an error is generated
    try(vec_cast(1.5, factor("a")))

    # Cast to common type
    vec_cast_common(factor("a"), factor(c("a", "b")))

[Package vctrs version 0.3.2 Index]