Overview

Today is a good day to start documenting what this package (kwb.utils) can be used for.

Intention

The main purpose of the package “kwb.utils” is to provide functions that allow for writing cleaner and safer code. One main characteristic of clean code is that it is free or at least almost free of duplication. This is a very hard goal to achieve! But we should try our best!

I would like to start with a complete list of the names of the functions that are contained in this package. But how can I get such a list?

How to get a list of functions in a package?

In fact, I do not know (any more) how to achieve this. However, I know that this package contains a function assignPackageObjects() that copies all the objects that are contained in a package (including all its functions) to the global environment. By inspecting the definition, i.e. the body, of this function, we can learn how this function works. Therefore, just type the function’s name, without parentheses, and press Enter:

kwb.utils::assignPackageObjects
#> function (package) 
#> {
#>     for (name in ls(getNamespace(package))) {
#>         object <- get(name, envir = asNamespace(package), inherits = FALSE)
#>         assign(name, object, envir = .GlobalEnv)
#>     }
#> }
#> <bytecode: 0x7fa86f8d84a0>
#> <environment: namespace:kwb.utils>

As the code reveals, the function loops through the values that are returned by ls(getNamespace(package)) where package is the name of the package. This is exacly what we need. We can use this code to get the names of all objects in the “kwb.utils” package. Let’s store these names in the variable object_names:

object_names <- ls(getNamespace("kwb.utils"))

length(object_names)
#> [1] 343

Wow! There are 343 objects (functions) defined in this package. So where should I start?

To make it somehow scientific, let’s have a look at the distribution of the function names, grouped by their first letter:

letter_distribution <- table(substr(sort(tolower(object_names)), 1, 1))
barplot(letter_distribution, horiz = TRUE, las = 1)

Even though not the highest peak, there are a lot of function names starting with h. Among these are functions that are prefixed by hs. We could find the names of these functions with the function stringStartsWith(), that is provided in this package (see String Functions, below). As, since R version 3.3.0, there is a function startsWith() in base R, we should use that one instead:

object_names[startsWith(object_names, "hs")]
#>  [1] "hsAddMissingCols"      "hsChrToNum"            "hsCountInStr"         
#>  [4] "hsDelEmptyCols"        "hsMatrixToListForm"    "hsMovingMean"         
#>  [7] "hsOpenWindowsExplorer" "hsPrepPdf"             "hsQuoteChr"           
#> [10] "hsRenameColumns"       "hsResolve"             "hsRestoreAttributes"  
#> [13] "hsSafeName"            "hsShell"               "hsShowPdf"            
#> [16] "hsStringToDate"        "hsStringToDouble"      "hsSubstSpecChars"     
#> [19] "hsSystem"              "hsTrim"                "hsValidValue"

The functions prefixed by hs are the oldest. When I started writing functions, I thought that it is important to indicate that these functions are user-defined functions, as opposed to base R functions. Reading the book Clean Code by Robert C. Martin convinced me to use clean names that can be pronounced easily.

Functions by Category

I tried to group all package functions per topic or per type of object that they either work on or return. These groups are listed below and described in further detail in one dedicated article per group.

Functions Returning Logical

These functions take different types of arguments as input but have all in common that they return a vector of logical. Some of these functions are just a shortcut to a rather long expression aiming at making the code more readable and avoiding duplication, such as allAreEqual(), allAreIdentical(), almostEqual(), isNaOrEmpty() or isNullOrEmpty(). Others do more complex things, such as matchesCriteria() that evaluates a set of conditions on a data frame, returning TRUE or FALSE depending on whether a row matches all conditions or not. Another more complex function is hsValidValue() that checks if a vector of character seems to contain numerical values.

For details, see Functions Returning Logical.

String Functions

The functions prefixed by string are wrappers around some simple grep expressions and exist since a former trainee asked me to provide these functions.

For details, see String Functions.

Vector Functions

For details, see Vector Functions.

General Object Functions

For details, see General Object Functions.

Conversion Functions

For details, see Conversion Functions.

Shortcut Functions to if-statements

For details, see Shortcut Functions to if-statements.

Operating System Functions

For details, see Operating System Functions.

Check Functions

For details, see Check Functions.: Functions that check for prerequisites

Debug Functions

For details, see Debug Functions.

Compare Objects

For details, see Compare Objects.

Calling Functions

For details, see Calling Functions.

Cryptographic Functions

For details, see Cryptographic Functions.

Grammar/Dictionary Functions

For details, see Grammar/Dictionary Functions.

Non-Categorised Functions

For details, see Non-Categorised Functions.

Hauke Sonnenberg

2024-03-28