new_box() is similar to base::I() but it protects a value by wrapping it in a scalar list rather than by adding an attribute. unbox() retrieves the boxed value. is_box() tests whether an object is boxed with optional class. as_box() ensures that a value is wrapped in a box. as_box_if() does the same but only if the value matches a predicate.

new_box(x, class = NULL)

is_box(x, class = NULL)

as_box(x, class = NULL)

as_box_if(.x, .p, .class = NULL, ...)



x, .x

An R object.

class, .class

For new_box(), an additional class for the boxed value (in addition to rlang_box). For is_box(), as_box() and as_box_if(), a class (or vector of classes) to be passed to inherits_all().


A predicate function.


Arguments passed to .p.


A boxed value to unbox.


boxed <- new_box(letters, "mybox") is_box(boxed)
#> [1] TRUE
is_box(boxed, "mybox")
#> [1] TRUE
is_box(boxed, "otherbox")
#> [1] FALSE
#> [1] "a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n" "o" "p" "q" "r" "s" #> [20] "t" "u" "v" "w" "x" "y" "z"
# as_box() avoids double-boxing: boxed2 <- as_box(boxed, "mybox") boxed2
#> [[1]] #> [1] "a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n" "o" "p" "q" "r" "s" #> [20] "t" "u" "v" "w" "x" "y" "z" #> #> attr(,"class") #> [1] "mybox" "rlang_box"
#> [1] "a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n" "o" "p" "q" "r" "s" #> [20] "t" "u" "v" "w" "x" "y" "z"
# Compare to: boxed_boxed <- new_box(boxed, "mybox") boxed_boxed
#> [[1]] #> [[1]] #> [1] "a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n" "o" "p" "q" "r" "s" #> [20] "t" "u" "v" "w" "x" "y" "z" #> #> attr(,"class") #> [1] "mybox" "rlang_box" #> #> attr(,"class") #> [1] "mybox" "rlang_box"
#> [1] "a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n" "o" "p" "q" "r" "s" #> [20] "t" "u" "v" "w" "x" "y" "z"
# Use `as_box_if()` with a predicate if you need to ensure a box # only for a subset of values: as_box_if(NULL, is_null, "null_box")
#> [[1]] #> NULL #> #> attr(,"class") #> [1] "null_box" "rlang_box"
as_box_if("foo", is_null, "null_box")
#> [1] "foo"