Skip to contents

Ensure a list meets expectations

Source: R/stabilize_lst.R
stabilize_lst.Rd

stabilize_lst() validates the structure and contents of a list. It can check that specific named elements are present and valid, that extra named elements conform to a shared rule, and that unnamed elements conform to a shared rule. stabilise_lst(), stabilize_list(), and stabilise_list() are synonyms of stabilize_lst().

Usage

stabilize_lst(
  .x,
  ...,
  .named = NULL,
  .unnamed = NULL,
  .allow_duplicate_names = FALSE,
  .unique = FALSE,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .required = ...names(),
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

stabilize_list(
  .x,
  ...,
  .named = NULL,
  .unnamed = NULL,
  .allow_duplicate_names = FALSE,
  .unique = FALSE,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .required = ...names(),
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

stabilise_lst(
  .x,
  ...,
  .named = NULL,
  .unnamed = NULL,
  .allow_duplicate_names = FALSE,
  .unique = FALSE,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .required = ...names(),
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

stabilise_list(
  .x,
  ...,
  .named = NULL,
  .unnamed = NULL,
  .allow_duplicate_names = FALSE,
  .unique = FALSE,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .required = ...names(),
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

Arguments

.x

The object to stabilize.

...

Named stabilizer functions, such as stabilize_* functions (stabilize_chr(), etc) or functions produced by specify_*() functions (specify_chr(), etc). Each name corresponds to an element in .x, and the function is used to validate that element when present. Whether the element is required (its absence is an error) is controlled by .required.

.named

Controls how named elements of .x that are not explicitly listed in ... are handled. One of:

  • NULL or FALSE (default): any extra named elements cause an error.

  • TRUE: extra named elements are allowed, unchecked.

  • A single stabilizer function, such as a stabilize_* function (stabilize_chr(), etc) or a function produced by a specify_*() function (specify_chr(), etc), used to validate every extra named element.

.unnamed

Controls how unnamed elements of .x are handled. One of:

  • NULL or FALSE (default): any unnamed elements cause an error.

  • TRUE: unnamed elements are allowed, unchecked.

  • A single stabilizer function, such as a stabilize_* function (stabilize_chr(), etc) or a function produced by a specify_*() function (specify_chr(), etc), used to validate every unnamed element.

.allow_duplicate_names

(logical(1)) Should .x be allowed to have duplicate names? If FALSE (default), an error is thrown when any named element of .x shares a name with another.

.unique

(logical(1)) Should all elements in .x be distinct? If TRUE, duplicated elements are rejected.

.allow_null

(logical(1)) Is NULL an acceptable value?

.allow_zero_length

(logical(1)) Are zero-length vectors acceptable?

.min_size

(integer(1)) The minimum size of the object. Object size will be tested using vctrs::vec_size().

.max_size

(integer(1)) The maximum size of the object. Object size will be tested using vctrs::vec_size().

.required

(character) Names (from ...) of elements that must be present in .x. Defaults to all names in ..., so every named spec is required unless you opt it out. Named specs not listed here are optional: if absent, no error is raised; if present, they're validated normally. Pass NULL or character() to make every named spec optional. A zero-length .x (such as list()) skips this check when .allow_zero_length = TRUE.

.x_arg

(character(1)) The name of the object being stabilized to use in error messages. The automatic value will work in most cases, or pass it through from higher-level functions to make error messages clearer in unexported functions.

.call

(environment) The execution environment to mention as the source of error messages.

.x_class

(character(1)) The class name of the object being stabilized to use in error messages. Use this if you remove a special class from the object before checking its coercion, but want the error message to match the original class.

Value

The validated list, or an error condition with classes <stbl-error>, <stbl-condition>, <rlang_error>, <error>, <condition>, and a specific class by failure mode:

  • <stbl-error-bad_null> for NULL values when .allow_null = FALSE.

  • <stbl-error-coerce-list> when .x cannot be coerced to a list.

  • <stbl-error-size_too_small> when the list is shorter than .min_size.

  • <stbl-error-size_too_large> when the list is longer than .max_size.

  • <stbl-error-duplicate_elements> when .unique = TRUE and duplicate elements are present.

  • <stbl-error-unnamed_spec> when any element passed through ... is unnamed.

  • <stbl-error-missing_element> when a required named element is absent.

  • <stbl-error-bad_unnamed> when unnamed elements are present but .unnamed is NULL or FALSE.

  • <stbl-error-bad_named> when extra named elements are present but .named is NULL or FALSE.

  • <stbl-error-duplicate_names> when duplicate names are present and .allow_duplicate_names = FALSE.

See also

Other list functions: assert_present(), specify_lst(), to(), to_lst()

Other stabilization functions: assert_contains(), assert_not(), assert_present(), stabilize_all_of(), stabilize_any_of(), stabilize_arg(), stabilize_chr(), stabilize_chr_scalar(), stabilize_date(), stabilize_date_scalar(), stabilize_dbl(), stabilize_dbl_scalar(), stabilize_df(), stabilize_dttm(), stabilize_dttm_scalar(), stabilize_dur(), stabilize_dur_scalar(), stabilize_fct(), stabilize_fct_scalar(), stabilize_int(), stabilize_int_scalar(), stabilize_lgl(), stabilize_lgl_scalar(), stabilize_one_of(), stabilize_time(), stabilize_time_scalar(), to_chr(), to_chr_scalar(), to_date(), to_date_scalar(), to_dbl(), to_dbl_scalar(), to_dttm(), to_dttm_scalar(), to_dur(), to_dur_scalar(), to_fct(), to_fct_scalar(), to_int(), to_int_scalar(), to_lgl(), to_lgl_scalar(), to_time(), to_time_scalar()

Examples

# Basic validation: named required elements
stabilize_lst(
  list(name = "Alice", age = 30L),
  name = specify_chr_scalar(),
  age = specify_int_scalar()
)
#> $name
#> [1] "Alice"
#> 
#> $age
#> [1] 30
#> 

# Allow any non-NULL element with assert_present
stabilize_lst(list(data = mtcars), data = assert_present)
#> $data
#>                      mpg cyl  disp  hp drat    wt  qsec vs am gear carb
#> Mazda RX4           21.0   6 160.0 110 3.90 2.620 16.46  0  1    4    4
#> Mazda RX4 Wag       21.0   6 160.0 110 3.90 2.875 17.02  0  1    4    4
#> Datsun 710          22.8   4 108.0  93 3.85 2.320 18.61  1  1    4    1
#> Hornet 4 Drive      21.4   6 258.0 110 3.08 3.215 19.44  1  0    3    1
#> Hornet Sportabout   18.7   8 360.0 175 3.15 3.440 17.02  0  0    3    2
#> Valiant             18.1   6 225.0 105 2.76 3.460 20.22  1  0    3    1
#> Duster 360          14.3   8 360.0 245 3.21 3.570 15.84  0  0    3    4
#> Merc 240D           24.4   4 146.7  62 3.69 3.190 20.00  1  0    4    2
#> Merc 230            22.8   4 140.8  95 3.92 3.150 22.90  1  0    4    2
#> Merc 280            19.2   6 167.6 123 3.92 3.440 18.30  1  0    4    4
#> Merc 280C           17.8   6 167.6 123 3.92 3.440 18.90  1  0    4    4
#> Merc 450SE          16.4   8 275.8 180 3.07 4.070 17.40  0  0    3    3
#> Merc 450SL          17.3   8 275.8 180 3.07 3.730 17.60  0  0    3    3
#> Merc 450SLC         15.2   8 275.8 180 3.07 3.780 18.00  0  0    3    3
#> Cadillac Fleetwood  10.4   8 472.0 205 2.93 5.250 17.98  0  0    3    4
#> Lincoln Continental 10.4   8 460.0 215 3.00 5.424 17.82  0  0    3    4
#> Chrysler Imperial   14.7   8 440.0 230 3.23 5.345 17.42  0  0    3    4
#> Fiat 128            32.4   4  78.7  66 4.08 2.200 19.47  1  1    4    1
#> Honda Civic         30.4   4  75.7  52 4.93 1.615 18.52  1  1    4    2
#> Toyota Corolla      33.9   4  71.1  65 4.22 1.835 19.90  1  1    4    1
#> Toyota Corona       21.5   4 120.1  97 3.70 2.465 20.01  1  0    3    1
#> Dodge Challenger    15.5   8 318.0 150 2.76 3.520 16.87  0  0    3    2
#> AMC Javelin         15.2   8 304.0 150 3.15 3.435 17.30  0  0    3    2
#> Camaro Z28          13.3   8 350.0 245 3.73 3.840 15.41  0  0    3    4
#> Pontiac Firebird    19.2   8 400.0 175 3.08 3.845 17.05  0  0    3    2
#> Fiat X1-9           27.3   4  79.0  66 4.08 1.935 18.90  1  1    4    1
#> Porsche 914-2       26.0   4 120.3  91 4.43 2.140 16.70  0  1    5    2
#> Lotus Europa        30.4   4  95.1 113 3.77 1.513 16.90  1  1    5    2
#> Ford Pantera L      15.8   8 351.0 264 4.22 3.170 14.50  0  1    5    4
#> Ferrari Dino        19.7   6 145.0 175 3.62 2.770 15.50  0  1    5    6
#> Maserati Bora       15.0   8 301.0 335 3.54 3.570 14.60  0  1    5    8
#> Volvo 142E          21.4   4 121.0 109 4.11 2.780 18.60  1  1    4    2
#> 

# Validate extra named elements via .named
stabilize_lst(
  list(a = 1L, b = 2L, c = 3L),
  .named = specify_int_scalar()
)
#> $a
#> [1] 1
#> 
#> $b
#> [1] 2
#> 
#> $c
#> [1] 3
#> 

# Allow extra named elements unchecked with .named = TRUE
stabilize_lst(list(a = 1L, b = "anything"), .named = TRUE)
#> $a
#> [1] 1
#> 
#> $b
#> [1] "anything"
#> 

# Validate unnamed elements via .unnamed
stabilize_lst(list(1L, 2L, 3L), .unnamed = specify_int_scalar())
#> [[1]]
#> [1] 1
#> 
#> [[2]]
#> [1] 2
#> 
#> [[3]]
#> [1] 3
#> 

# Allow unnamed elements unchecked with .unnamed = TRUE
stabilize_lst(list(1L, "anything"), .unnamed = TRUE)
#> [[1]]
#> [1] 1
#> 
#> [[2]]
#> [1] "anything"
#> 

# NULL is allowed by default
stabilize_lst(NULL)
#> NULL
try(stabilize_lst(NULL, .allow_null = FALSE))
#> Error in eval(expr, envir) : `NULL` must not be <NULL>.

# Enforce size constraints
try(stabilize_lst(list(a = 1L), .min_size = 2))
#> Error in eval(expr, envir) : `list(a = 1L)` must have size >= 2.
#> ✖ 1 is too small.

# Reject duplicate names by default; opt in to allow them
try(stabilize_lst(list(a = 1L, a = 2L), .named = specify_int_scalar()))
#> Error in eval(expr, envir) : 
#>   `list(a = 1L, a = 2L)` must not contain duplicate names.
#> ✖ Duplicate name: "a"
stabilize_lst(
  list(a = 1L, a = 2L),
  .named = specify_int_scalar(),
  .allow_duplicate_names = TRUE
)
#> $a
#> [1] 1
#> 
#> $a
#> [1] 2
#> 

# Mark named specs as optional via .required
stabilize_lst(
  list(a = 1L),
  a = specify_int_scalar(),
  b = specify_int_scalar(),
  .required = "a"
)
#> $a
#> [1] 1
#> 
try(
  stabilize_lst(list(a = 1L), a = specify_int_scalar(), b = specify_int_scalar())
)
#> Error in eval(expr, envir) : 
#>   `list(a = 1L)` must contain element "b".