stabilize_lst: Ensure a list argument meets expectations

In stbl: Stabilize Function Arguments

Ensure a list argument meets expectations

Description

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,
  .allow_null = TRUE,
  .min_size = NULL,
  .max_size = NULL,
  .x_arg = caller_arg(.x),
  .call = caller_env(),
  .x_class = object_type(.x)
)

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

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

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

Arguments

.x	The argument 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 a required element in .x, and the function is used to validate that element.
.named	A single stabilizer function, such as a ⁠stabilize_*⁠ function (stabilize_chr(), etc) or a function produced by a ⁠specify_*()⁠ function (specify_chr(), etc). This function is used to validate all named elements of .x that are not explicitly listed in .... If NULL (default), any extra named elements will cause an error.
.unnamed	A single stabilizer function, such as a ⁠stabilize_*⁠ function (stabilize_chr(), etc) or a function produced by a ⁠specify_*()⁠ function (specify_chr(), etc). This function is used to validate all unnamed elements of .x. If NULL (default), any unnamed elements will cause an error.
.allow_duplicate_names	⁠(length-1 logical)⁠ 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.
.allow_null	⁠(length-1 logical)⁠ Is NULL an acceptable value?
.min_size	⁠(length-1 integer)⁠ The minimum size of the object. Object size will be tested using vctrs::vec_size().
.max_size	⁠(length-1 integer)⁠ The maximum size of the object. Object size will be tested using vctrs::vec_size().
.x_arg	⁠(length-1 character)⁠ The name of the argument 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	⁠(length-1 character)⁠ The class name of the argument 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.

See Also

Other list functions: specify_lst(), stabilize_present(), to_lst()

Other stabilization functions: stabilize_arg(), stabilize_chr(), stabilize_dbl(), stabilize_df(), stabilize_fct(), stabilize_int(), stabilize_lgl(), stabilize_present()

Examples

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

# Allow any non-NULL element with stabilize_present
stabilize_lst(list(data = mtcars), data = stabilize_present)

# Allow extra named elements via .named
stabilize_lst(
  list(a = 1L, b = 2L, c = 3L),
  .named = specify_int_scalar()
)

# Allow unnamed elements via .unnamed
stabilize_lst(list(1L, 2L, 3L), .unnamed = specify_int_scalar())

# NULL is allowed by default
stabilize_lst(NULL)
try(stabilize_lst(NULL, .allow_null = FALSE))

# Enforce size constraints
try(stabilize_lst(list(a = 1L), .min_size = 2))

# Reject duplicate names by default; opt in to allow them
try(stabilize_lst(list(a = 1L, a = 2L), .named = specify_int_scalar()))
stabilize_lst(
  list(a = 1L, a = 2L),
  .named = specify_int_scalar(),
  .allow_duplicate_names = TRUE
)

stbl documentation built on April 4, 2026, 5:06 p.m.