Cran prep rpkgs (#73)

* Merge documentation.

* Merge to into stabilize.

* Include to_fct() params.

DESCRIPTION

@@ -2,7 +2,7 @@ Package: stbl
 Title: Stabilize Function Arguments
 Version: 0.0.0.9001
 Authors@R: 
-    person("Jon", "Harmon", , "[email protected]", role = c("aut", "cre"),
+    person("Jon", "Harmon", , "[email protected]", role = c("aut", "cre", "cph"),
            comment = c(ORCID = "0000-0003-4781-4346"))
 Description: A set of consistent, opinionated functions to quickly check 
     function arguments, coerce them to the desired configuration, or deliver 

R/stabilize_arg.R

@@ -1,10 +1,13 @@
 #' Ensure an argument meets expectations
 #'
-#' This function is used by other functions such as [stabilize_int()]. Use
+#' @description
+#' `stabilize_arg()` is used by other functions such as [stabilize_int()]. Use
 #' `stabilize_arg()` if the type-specific functions will not work for your use
 #' case, but you would still like to check things like size or whether the
 #' argument is NULL.
 #'
+#' `stabilize_arg_scalar()` is optimized to check for length-1 vectors.
+#'
 #' @inheritParams .coerce-params
 #'
 #' @return `x`, unless one of the checks fails.
@@ -21,6 +24,9 @@
 #' try(wrapper(NA, allow_na = FALSE))
 #' try(wrapper(1, min_size = 2))
 #' try(wrapper(1:10, max_size = 5))
+#' stabilize_arg_scalar("a")
+#' stabilize_arg_scalar(1L)
+#' try(stabilize_arg_scalar(1:10))
 stabilize_arg <- function(x,
                           ...,
                           allow_null = TRUE,

R/stabilize_arg_scalar.R

@@ -1,18 +1,5 @@
-#' Ensure an argument meets expectations and is length-1
-#'
-#' This function is equivalent to [stabilize_arg()], but it is optimized to
-#' check for length-1 vectors.
-#'
-#' @inheritParams stabilize_arg
-#' @inheritParams .coerce-params
-#'
-#' @return `x`, unless one of the checks fails.
+#' @rdname stabilize_arg
 #' @export
-#'
-#' @examples
-#' stabilize_arg_scalar("a")
-#' stabilize_arg_scalar(1L)
-#' try(stabilize_arg_scalar(1:10))
 stabilize_arg_scalar <- function(x,
                                  ...,
                                  allow_null = TRUE,

R/stabilize_chr.R

@@ -1,12 +1,26 @@
 #' Ensure a character argument meets expectations
 #'
-#' Check a character argument to ensure that it meets expectations, coercing it
-#' to character where possible. If the argument does not meet the requirements,
-#' the user will receive an informative error message. Note that [to_chr()] is a
-#' faster version of this function with fewer options.
+#' @description `to_chr()` checks whether an argument can be coerced to
+#'   character without losing information, returning it silently if so.
+#'   Otherwise an informative error message is signaled.
+#'
+#'   `stabilize_chr()` can check more details about the argument, but is slower
+#'   than `to_chr()`.
+#'
+#'   `stabilize_chr_scalar()` and `to_chr_scalar()` are optimized to check for
+#'   length-1 character vectors.
+#'
+#' @details These functions have two important differences from
+#'   [base::as.character()]:
+#'
+#' - `list`s and `data.frame`s are *not* coerced to character. In base R, such
+#'   objects are coerced to character representations of their elements. For
+#'   example, `as.character(list(1:3))` returns "1:10". In the unlikely event
+#'   that this is the expected behavior, use `as.character()` instead.
+#' - `NULL` values can be rejected as part of the call to this function (with
+#'   `allow_null = FALSE`).
 #'
 #' @inheritParams .coerce-params
-#' @inheritParams to_chr
 #' @param regex Character scalar. An optional regex pattern to compare the
 #'   value(s) of `x` against. If a complex regex pattern throws an error, try
 #'   installing the stringi package with `install.packages("stringi")`.
@@ -15,6 +29,19 @@
 #' @export
 #'
 #' @examples
+#' # to_chr()
+#' to_chr("a")
+#' to_chr(letters)
+#' to_chr(1:10)
+#' to_chr(1 + 0i)
+#' to_chr(NULL)
+#' try(to_chr(NULL, allow_null = FALSE))
+#'
+#' # to_chr_scalar()
+#' to_chr_scalar("a")
+#' try(to_chr_scalar(letters))
+#'
+#' # stabilize_chr()
 #' stabilize_chr(letters)
 #' stabilize_chr(1:10)
 #' stabilize_chr(NULL)
@@ -23,6 +50,13 @@
 #' try(stabilize_chr(letters, min_size = 50))
 #' try(stabilize_chr(letters, max_size = 20))
 #' try(stabilize_chr(c("hide", "find", "find", "hide"), regex = "hide"))
+#'
+#' # stabilize_chr_scalar()
+#' stabilize_chr_scalar(TRUE)
+#' stabilize_chr_scalar("TRUE")
+#' try(stabilize_chr_scalar(c(TRUE, FALSE, TRUE)))
+#' stabilize_chr_scalar(NULL)
+#' try(stabilize_chr_scalar(NULL, allow_null = FALSE))
 stabilize_chr <- function(x,
                           ...,
                           allow_null = TRUE,

R/stabilize_chr_scalar.R

@@ -1,20 +1,5 @@
-#' Ensure a character argument meets expectations and is length-1
-#'
-#' This function is equivalent to [stabilize_chr()], but it is optimized to
-#' check for length-1 character vectors.
-#'
-#' @inheritParams stabilize_chr
-#' @inheritParams .coerce-params
-#'
-#' @return `x`, unless one of the checks fails.
 #' @export
-#'
-#' @examples
-#' stabilize_chr_scalar(TRUE)
-#' stabilize_chr_scalar("TRUE")
-#' try(stabilize_chr_scalar(c(TRUE, FALSE, TRUE)))
-#' stabilize_chr_scalar(NULL)
-#' try(stabilize_chr_scalar(NULL, allow_null = FALSE))
+#' @rdname stabilize_chr
 stabilize_chr_scalar <- function(x,
                                  ...,
                                  allow_null = TRUE,

R/stabilize_fct.R

@@ -1,22 +1,53 @@
 #' Ensure a factor argument meets expectations
 #'
-#' Check a factor argument to ensure that it meets expectations, coercing it
-#' to factor where possible. If the argument does not meet the requirements,
-#' the user will receive an informative error message. Note that [to_fct()] is a
-#' faster version of this function with fewer options.
+#' @description `to_fct()` checks whether an argument can be coerced to
+#'   a factor without losing information, returning it silently if so.
+#'   Otherwise an informative error message is signaled.
+#'
+#'   `stabilize_fct()` can check more details about the argument, but is slower
+#'   than `to_fct()`.
+#'
+#'   `stabilize_fct_scalar()` and `to_fct_scalar()` are optimized to check for
+#'   length-1 factors.
+#'
+#' @details These functions have important differences from [base::as.factor()] and
+#' [base::factor()]:
+#'
+#' - Values are never silently coerced to `NA` unless they are explicitly
+#' supplied in the `to_na` argument.
+#' - `NULL` values can be rejected as part of the call to this function (with
+#' `allow_null = FALSE`).
 #'
 #' @inheritParams .coerce-params
-#' @inheritParams to_fct
+#' @param levels Character. Expected levels. If `NULL` (default), the levels
+#'   will be computed by [base::factor()].
+#' @param to_na Character. Values to coerce to `NA`.
 #'
 #' @return The argument as a factor.
 #' @export
 #'
 #' @examples
+#' # to_fct
+#' to_fct("a")
+#' to_fct(1:10)
+#' to_fct(NULL)
+#' try(to_fct(letters[1:5], levels = c("a", "c"), to_na = "b"))
+#'
+#' # to_fct_scalar
+#' to_fct_scalar("a")
+#' try(to_fct_scalar(letters))
+#'
+#' # stabilize_fct
 #' stabilize_fct(letters)
 #' try(stabilize_fct(NULL, allow_null = FALSE))
 #' try(stabilize_fct(c("a", NA), allow_na = FALSE))
 #' try(stabilize_fct(c("a", "b", "c"), min_size = 5))
 #' try(stabilize_fct(c("a", "b", "c"), max_size = 2))
+#'
+#' # stabilize_fct_scalar
+#' stabilize_fct_scalar("a")
+#' try(stabilize_fct_scalar(letters))
+#' try(stabilize_fct_scalar("c", levels = c("a", "b")))
 stabilize_fct <- function(x,
                           ...,
                           allow_null = TRUE,

R/stabilize_fct_scalar.R

@@ -1,18 +1,5 @@
-#' Ensure a factor argument meets expectations and is length-1
-#'
-#' This function is equivalent to [stabilize_fct()], but it is optimized to
-#' check for length-1 factors.
-#'
-#' @inheritParams stabilize_fct
-#' @inheritParams .coerce-params
-#'
-#' @return `x`, unless one of the checks fails.
 #' @export
-#'
-#' @examples
-#' stabilize_fct_scalar("a")
-#' try(stabilize_fct_scalar(letters))
-#' try(stabilize_fct_scalar("c", levels = c("a", "b")))
+#' @rdname stabilize_fct
 stabilize_fct_scalar <- function(x,
                                  ...,
                                  allow_null = TRUE,

R/stabilize_int.R

@@ -1,12 +1,22 @@
 #' Ensure an integer argument meets expectations
 #'
-#' Check an integer argument to ensure that it meets expectations, coercing it
-#' to integer where possible. If the argument does not meet the requirements,
-#' the user will receive an informative error message. Note that [to_int()] is a
-#' faster version of this function with fewer options.
+#' @description `to_int()` checks whether an argument can be coerced to
+#'   integer without losing information, returning it silently if so.
+#'   Otherwise an informative error message is signaled.
+#'
+#'   `stabilize_int()` can check more details about the argument, but is slower
+#'   than `to_int()`.
+#'
+#'   `stabilize_int_scalar()` and `to_int_scalar()` are optimized to check for
+#'   length-1 integer vectors.
 #'
 #' @inheritParams .coerce-params
-#' @inheritParams to_int
+#' @param coerce_character Logical. Should character vectors such as "1" and
+#'   "2.0" be coerced to integer?
+#' @param coerce_factor Logical. Should factors with values such as "1" and
+#'   "2.0" be coerced to integer? Note that this function uses the character
+#'   value from the factor, while [as.integer()] uses the integer index of the
+#'   factor.
 #' @param min_value Integer scalar. The lowest allowed value for `x`. If `NULL`
 #'   (default) values are not checked.
 #' @param max_value Integer scalar. The highest allowed value for `x`. If `NULL`
@@ -16,6 +26,20 @@
 #' @export
 #'
 #' @examples
+#' # to_int
+#' to_int(1:10)
+#' to_int("1")
+#' to_int(1 + 0i)
+#' to_int(NULL)
+#' try(to_int(c(1, 2, 3.1, 4, 5.2)))
+#' try(to_int("1", coerce_character = FALSE))
+#' try(to_int(c("1", "2", "3.1", "4", "5.2")))
+#'
+#' # to_int_scalar
+#' to_int_scalar("1")
+#' try(to_int_scalar(1:10))
+#'
+#' # stabilize_int
 #' stabilize_int(1:10)
 #' stabilize_int("1")
 #' stabilize_int(1 + 0i)
@@ -28,6 +52,13 @@
 #' try(stabilize_int(factor("1"), coerce_factor = FALSE))
 #' try(stabilize_int(1:10, min_value = 3))
 #' try(stabilize_int(1:10, max_value = 7))
+#'
+#' # stabilize_int_scalar
+#' stabilize_int_scalar(1L)
+#' stabilize_int_scalar("1")
+#' try(stabilize_int_scalar(1:10))
+#' stabilize_int_scalar(NULL)
+#' try(stabilize_int_scalar(NULL, allow_null = FALSE))
 stabilize_int <- function(x,
                           ...,
                           allow_null = TRUE,

R/stabilize_int_scalar.R

@@ -1,20 +1,5 @@
-#' Ensure an integer argument meets expectations and is length-1
-#'
-#' This function is equivalent to [stabilize_int()], but it is optimized to
-#' check for length-1 integers.
-#'
-#' @inheritParams stabilize_int
-#' @inheritParams .coerce-params
-#'
-#' @return `x`, unless one of the checks fails.
 #' @export
-#'
-#' @examples
-#' stabilize_int_scalar(1L)
-#' stabilize_int_scalar("1")
-#' try(stabilize_int_scalar(1:10))
-#' stabilize_int_scalar(NULL)
-#' try(stabilize_int_scalar(NULL, allow_null = FALSE))
+#' @rdname stabilize_int
 stabilize_int_scalar <- function(x,
                                  ...,
                                  allow_null = TRUE,

R/stabilize_lgl.R

@@ -1,17 +1,35 @@
 #' Ensure a logical argument meets expectations
 #'
-#' Check a logical argument to ensure that it meets expectations, coercing it
-#' to logical where possible. If the argument does not meet the requirements,
-#' the user will receive an informative error message. Note that [to_lgl()] is a
-#' faster version of this function with fewer options.
+#' @description `to_lgl()` checks whether an argument can be coerced to
+#'   logical without losing information, returning it silently if so.
+#'   Otherwise an informative error message is signaled.
+#'
+#'   `stabilize_lgl()` can check more details about the argument, but is slower
+#'   than `to_lgl()`.
+#'
+#'   `stabilize_lgl_scalar()` and `to_lgl_scalar()` are optimized to check for
+#'   length-1 logical vectors.
 #'
 #' @inheritParams .coerce-params
-#' @inheritParams to_lgl
 #'
 #' @return The argument as a logical vector.
 #' @export
 #'
 #' @examples
+#' # to_lgl
+#' to_lgl(TRUE)
+#' to_lgl("TRUE")
+#' to_lgl(1:10)
+#' to_lgl(NULL)
+#' try(to_lgl(NULL, allow_null = FALSE))
+#' try(to_lgl(letters))
+#' try(to_lgl(list(TRUE)))
+#'
+#' # to_lgl_scalar
+#' to_lgl_scalar("TRUE")
+#' try(to_lgl_scalar(c(TRUE, FALSE)))
+#'
+#' # stabilize_lgl
 #' stabilize_lgl(c(TRUE, FALSE, TRUE))
 #' stabilize_lgl("true")
 #' stabilize_lgl(NULL)
@@ -20,6 +38,13 @@
 #' try(stabilize_lgl(letters))
 #' try(stabilize_lgl(c(TRUE, FALSE, TRUE), min_size = 5))
 #' try(stabilize_lgl(c(TRUE, FALSE, TRUE), max_size = 2))
+#'
+#' # stabilize_lgl_scalar
+#' stabilize_lgl_scalar(TRUE)
+#' stabilize_lgl_scalar("TRUE")
+#' try(stabilize_lgl_scalar(c(TRUE, FALSE, TRUE)))
+#' stabilize_lgl_scalar(NULL)
+#' try(stabilize_lgl_scalar(NULL, allow_null = FALSE))
 stabilize_lgl <- function(x,
                           ...,
                           allow_null = TRUE,

R/stabilize_lgl_scalar.R

@@ -1,20 +1,5 @@
-#' Ensure a logical argument meets expectations and is length-1
-#'
-#' This function is equivalent to [stabilize_lgl()], but it is optimized to
-#' check for length-1 logical vectors.
-#'
-#' @inheritParams stabilize_lgl
-#' @inheritParams .coerce-params
-#'
-#' @return `x`, unless one of the checks fails.
 #' @export
-#'
-#' @examples
-#' stabilize_lgl_scalar(TRUE)
-#' stabilize_lgl_scalar("TRUE")
-#' try(stabilize_lgl_scalar(c(TRUE, FALSE, TRUE)))
-#' stabilize_lgl_scalar(NULL)
-#' try(stabilize_lgl_scalar(NULL, allow_null = FALSE))
+#' @rdname stabilize_lgl
 stabilize_lgl_scalar <- function(x,
                                  ...,
                                  allow_null = TRUE,