init docs, tests

DESCRIPTION

@@ -5,18 +5,17 @@ Version: 0.1.0
 Date: 2024-05-23
 Authors@R: c(person("Qile", "Yang", email = "[email protected]", role = c("cre","aut","cph")))
 Maintainer: Qile Yang <[email protected]>
-Description: One paragraph description of what the package does as one
-        or more full sentences.
+Description:  for general use. All functions have vectorized implementations whenever possible.
 BugReports: https://github.com/Qile0317/FastUtils/issues/
 License: MIT + file LICENSE
 Encoding: UTF-8
 Language: en-US
 Imports: 
-    data.table,
     dplyr,
     ggplot2,
     hash,
-    Rcpp (>= 1.0.12)
+    Rcpp (>= 1.0.12),
+    usethis
 LinkingTo: Rcpp
 Suggests: 
     testthat (>= 3.0.0)

NAMESPACE

@@ -1,3 +1,39 @@
-useDynLib(ArrayStats, .registration=TRUE)
-importFrom(Rcpp, evalCpp)
+# Generated by roxygen2: do not edit by hand
+
+S3method(getfirst,default)
+S3method(getlast,default)
+export(add)
+export(bound)
+export(closestWord)
+export(createHash)
+export(createMutator)
+export(divide)
+export(enumerate)
+export(getAvgHex)
+export(getChar)
+export(getUniquePairsUpTo)
+export(getfirst)
+export(getlast)
+export(ind)
+export(initEmptyTable)
+export(initTestthat)
+export(initV)
+export(isBound)
+export(isEven)
+export(isOdd)
+export(isVowel)
+export(multiply)
+export(namedNumericToTable)
+export(prependIndefArticle)
+export(scaleHex)
+export(startsWithVowel)
+export(stripSpaces)
+export(substrEnd)
+export(subtract)
+export(tableToNumeric)
+export(val)
+export(val1)
+export(zip)
 exportPattern("^[[:alpha:]]+")
+importFrom(Rcpp,evalCpp)
+useDynLib(FastUtils, .registration = TRUE)

R/FastUtils-package.R

@@ -0,0 +1,9 @@
+#' @keywords internal
+"_PACKAGE"
+
+## usethis namespace: start
+#' @importFrom Rcpp evalCpp
+#' @useDynLib FastUtils, .registration = TRUE
+#' @exportPattern "^[[:alpha:]]+"
+## usethis namespace: end
+NULL

R/character.R

@@ -0,0 +1,14 @@
+#' Extract Substring from Start to End Difference
+#'
+#' This function extracts a substring from a given start position to the position determined by subtracting `endDiff` from the string length.
+#'
+#' @param x A character string from which the substring is extracted.
+#' @param start The starting position for the substring extraction.
+#' @param endDiff The difference to subtract from the string length to determine the end position.
+#' 
+#' @return A substring of the input character string.
+#' @export
+#' @keywords character
+substrEnd <- function(x, start, endDiff) {
+    substr(x, start, nchar(x) - endDiff)
+}

R/color.R

@@ -1,6 +1,14 @@
-#' @export
-#' @source https://stackoverflow.com/questions/649454
+#' Compute the Average of Hex Colors
+#'
+#' This function computes the average color of the provided hex color values.
 #'
+#' @param ... Hex color values as character strings.
+#' 
+#' @return A single hex color value representing the average of the input colors.
+#' @export
+#' @keywords color
+#' 
+#' @source \url{https://stackoverflow.com/questions/649454}
 getAvgHex <- function(...) {
     Reduce(function(hex1, hex2) {
         grDevices::rgb(
@@ -10,7 +18,16 @@ getAvgHex <- function(...) {
     }, unlist(list(...)))
 }
 
+#' Scale the Brightness of a Hex Color
+#'
+#' This function scales the brightness of a hex color by a given factor.
+#'
+#' @param hex A hex color value as a character string.
+#' @param scaleFactor A numeric value to scale the brightness. A value of 1 returns the original color.
+#' 
+#' @return A hex color value with adjusted brightness.
 #' @export
+#' @keywords color
 scaleHex <- function(hex, scaleFactor) {
 
     if (all(scaleFactor == 1)) return(hex)

R/dataInitialization.R

@@ -1,4 +1,14 @@
+#' Initialize a Vector
+#'
+#' This function initializes a vector based on a specified type and size, with an optional initial value.
+#'
+#' @param typeFunc A character string indicating the type of the vector or a function to create the vector.
+#' @param x The length of the vector.
+#' @param initVal An optional initial value to fill the vector.
+#' 
+#' @return A vector of the specified type and size, optionally initialized with a value.
 #' @export
+#' @keywords dataInitialization
 initV <- function(typeFunc, x, initVal = NULL) {
     if (is(typeFunc, "character")) {
         v <- vector(typeFunc, x)
@@ -9,7 +19,13 @@ initV <- function(typeFunc, x, initVal = NULL) {
     sapply(v, function(i) initVal)
 }
 
+#' Initialize an Empty Table
+#'
+#' This function initializes an empty table.
+#'
+#' @return An empty table structure.
 #' @export
+#' @keywords dataInitialization
 initEmptyTable <- function() {
     structure(
         integer(0),
@@ -19,12 +35,28 @@ initEmptyTable <- function() {
     )
 }
 
+#' Convert a Table to Numeric
+#'
+#' This function converts a table to a numeric vector.
+#'
+#' @param x A table to be converted.
+#' 
+#' @return A numeric vector with names preserved from the table.
 #' @export
+#' @keywords dataInitialization
 tableToNumeric <- function(x) {
     structure(as.numeric(x), names = names(x))
 }
 
+#' Convert Named Numeric Vector to Table
+#'
+#' This function converts a named numeric vector to a table.
+#'
+#' @param x A named numeric vector.
+#' 
+#' @return A table with the same names and values as the input vector.
 #' @export
+#' @keywords dataInitialization
 namedNumericToTable <- function(x) {
     output <- as.integer(x)
     names(output) <- names(x)
@@ -33,7 +65,16 @@ namedNumericToTable <- function(x) {
     output
 }
 
+#' Create a Hash Table
+#'
+#' This function creates a hash table from a set of keys and optional initial values.
+#'
+#' @param keys A vector of keys for the hash table.
+#' @param init_vals Optional initial values for the hash table.
+#' 
+#' @return A hash table with the specified keys and initial values.
 #' @export
+#' @keywords dataInitialization
 createHash <- function(keys, init_vals = NULL) {
     keys <- unique(keys)
     numkeys <- length(keys)

R/ggplot.R

@@ -1,5 +1,11 @@
-#' @title Get the xmin, xmax, ymin, ymax of a ggplot object
-#' @return list(xr = c(xmin, xmax), yr = c(ymin, ymax))
+#' Get the xmin, xmax, ymin, ymax of a ggplot Object
+#'
+#' This function retrieves the minimum and maximum x and y dimensions of a ggplot object.
+#'
+#' @param plt A ggplot object.
+#' 
+#' @return A list with elements `xr` (a vector of xmin and xmax) and `yr` (a vector of ymin and ymax).
+#' @keywords ggplot
 #' @noRd
 getPlotDims <- function(plt) {
     built_plt_layout <- ggplot2::ggplot_build(plt)$layout

R/higherOrderFunctions.R

@@ -1,8 +1,16 @@
+#' Create a Mutator Function
+#'
+#' This function creates a mutator function based on a specified binary operator. The mutator function updates a variable in the parent frame by applying the binary operator with a given value.
+#'
+#' @param binaryOperator A binary operator function to apply for the mutation.
+#' 
+#' @return A function that takes a variable and a value, applying the binary operator to update the variable in the parent frame.
 #' @export
-createMutator <- function(binary_operator) {
+#' @keywords higherOrderFunctions
+createMutator <- function(binaryOperator) {
     function(var, val) {
         eval(
-            call("<-", substitute(var), binary_operator(var, val)),
+            call("<-", substitute(var), binaryOperator(var, val)),
             envir = parent.frame()
         )
     }

R/indexing.R

@@ -0,0 +1,45 @@
+#' Get the Last Elements of a Vector or List
+#'
+#' This function retrieves the last `n` elements of a vector or list.
+#'
+#' @param x A vector, list, or other supported data type.
+#' @param n An integer specifying the number of elements to retrieve from the end. Default is 1.
+#' 
+#' @return The last `n` elements of the input.
+#' @export
+#' @keywords indexing
+getlast <- function(x, n = 1) {
+    UseMethod("getlast")
+}
+
+#' @export
+getlast.default <- function(x, n = 1) {
+    index <- length(x) - n + 1
+    if (is.list(x)) {
+        return(x[[index]])
+    }
+    x[index]
+}
+
+#' Get the First Elements of a Vector or List
+#'
+#' This function retrieves the first `n` elements of a vector or list.
+#'
+#' @param x A vector, list, or other supported data type.
+#' @param n An integer specifying the number of elements to retrieve from the start. Default is 1.
+#' 
+#' @return The first `n` elements of the input.
+#' @export
+#' @keywords indexing
+getfirst <- function(x, n = 1) {
+    UseMethod("getfirst")
+}
+
+#' @export
+getfirst.default <- function(x, n = 1) {
+    index <- n
+    if (is.list(x)) {
+        return(x[[index]])
+    }
+    x[index]
+}

R/iteration.R

@@ -1,29 +1,73 @@
+#' Generate Unique Pairs Up To a Number
+#'
+#' This function generates all unique pairs of integers up to a given number.
+#'
+#' @param x An integer specifying the upper limit for pairs.
+#' @param oneIndexed A logical indicating whether the pairs should be one-indexed. Default is TRUE.
+#' 
+#' @return A list of unique pairs of integers up to the specified number.
 #' @export
+#' @keywords iteration
 getUniquePairsUpTo <- function(x, oneIndexed = TRUE) {
     if (x <= 1) return(list())
     rcppGetUniquePairsUpTo(as.integer(x), oneIndexed = oneIndexed)
 }
 
+#' Zip Multiple Vectors or Lists
+#'
+#' This function combines multiple vectors or lists element-wise into a list of lists.
+#'
+#' @param ... Vectors or lists to be combined.
+#' 
+#' @return A list of lists, where each inner list contains the elements from the corresponding positions in the input vectors or lists.
 #' @export
-getlast <- function(x, n = 1) {
-    index <- length(x) - n + 1
-    if (is.list(x)) return(x[[index]])
-    x[index]
-}
-
-#' @export
+#' @keywords iteration
 zip <- function(...) mapply(list, ..., SIMPLIFY = FALSE)
 
+#' Enumerate Elements with Indices
+#'
+#' This function pairs elements of vectors or lists with their indices.
+#'
+#' @param ... Vectors or lists to be enumerated.
+#' @param zero_indexed A logical indicating whether indexing should start from zero. Default is FALSE.
+#' 
+#' @return A list of lists, where each inner list contains an index and the corresponding elements from the input vectors or lists.
 #' @export
+#' @keywords iteration
 enumerate <- function(..., zero_indexed = FALSE) {
     zip(seq_along(..1) - zero_indexed, ...)
 }
 
+#' Get Index from Enumerated Element
+#'
+#' This function extracts the index from an enumerated element.
+#'
+#' @param elem An enumerated element.
+#' 
+#' @return The index of the enumerated element.
 #' @export
+#' @keywords iteration
 ind <- function(elem) elem[[1]]
 
+#' Get Value from Enumerated Element by Index
+#'
+#' This function extracts the value from an enumerated element by the given index.
+#'
+#' @param elem An enumerated element.
+#' @param index The index of the value to extract.
+#' 
+#' @return The value at the specified index in the enumerated element.
 #' @export
+#' @keywords iteration
 val <- function(elem, index) elem[[index + 1]]
 
+#' Get First Value from Enumerated Element
+#'
+#' This function extracts the first value from an enumerated element.
+#'
+#' @param elem An enumerated element.
+#' 
+#' @return The first value in the enumerated element.
 #' @export
+#' @keywords iteration
 val1 <- function(elem) val(elem, 1)