---
title: "Use container for code development"
output:
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 4
description: >
    Use this vignette if you want to see how container operations can be used
    to make it safer and easier to work with list-like data structures.
    It describes the different methods to add, extract, replace, and remove
    elements and their nuances.
    This vignette demonstrates how {container} enhances the robustness of
    code by providing strict validation and clear, intent-driven operations
    for adding, extracting, replacing, and removing elements.
    It highlights features that minimize errors and streamline development
    workflows.
vignette: >
  %\VignetteIndexEntry{Use container for code development}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r knitr-setup, include = FALSE}
require(container)
knitr::opts_chunk$set(
  comment = "#",
    error = FALSE,
     tidy = FALSE,
    cache = FALSE,
 collapse = TRUE
)
old <- options(width = 100L)
```

## Robust usage

Base R's list operations are designed for interactive use, offering
flexibility but often being overly permissive with user input.
While convenient, this can lead to subtle bugs during development
and requires additional, sometimes tedious, checks to ensure code
robustness.

The {container} package addresses these challenges by providing
operations that explicitly define the intent of each action. By
prioritizing clarity and precision, {container} enables you
to write leaner and more reliable code right from the start.

This vignette revisits some of the basic operations familiar from
base R lists and demonstrates how {container} enhances them with
strict validation and powerful additional features.

```{r}
co <- container()
```

### Add

Using base R *lists* notation, elements are usually added by name or
concatenation.

```{r}
co[["x"]] <- 1
co <- c(co, 2)

co
```

The {container} package provides the `add` function to add elements.

```{r}
co <- add(co, x = 3)  # same as c(co, x = 3)

co
```

For container objects there is not much of a difference between the two
methods. Now, if for example you don't want to allow duplicated names,
you can use dict objects instead. These are a subclass of container and
would throw an error in this case.

```{r, error = TRUE}
d <- dict(x = 1)

add(d, x = 3)
```

For more details see the reference documentation or have a look at
the [Deque, Set, and Dict](v05-deque-set-dict.html) vignette.
Lastly, note that the base append function also works with containers.

```{r}
append(co, 1.5, after = 1)
```



### Replace

As demonstrated before, elements can be loosely replaced by index or name.

```{r}
co[["x"]] <- 0
co[[2]] <- 12

co
```

Also, in contrast to base *lists*, the container will not allow to
add elements at positions longer than the length of the object.

```{r, error = TRUE}
co[[4]] <- 3
```

If the name does not exist, the element is appended as known from base *lists*.

```{r}
co[["y"]] <- 5

co
```

#### Strict replace

Let's imagine you want to replace an element of a certain name, and therefore
expect that the name exists already. In code development, this would require
an additional check, for example:

```{r, eval = FALSE}
name <- "z"
if (name %in% names(co)) {
  co[[name]] <- 10
} else {
  stop("Name '", name,  "' does not exist.")
}
```

Clearly this is a lot of boilerplate code for a simple operation, and it
is easy to forget such checks. In addition, you end up with a lot of
unit tests basically to check the checks. Last but not
least, the intent of the code is not as clear as it could be.

This is where the {container} package comes in. If you want to make sure
that something is replaced, {container} provides the
function `replace_at`, which will only replace elements at names or
positions that exist. The following statements are all equal and show the
different possibilities on how to use `replace_at`.

```{r}
replace_at(co, x = 10, y = 13)            # name = value pairs

replace_at(co, c("x", "y"),  c(10, 13))   # names followed by values

replace_at(co, c(1, 4),      c(10, 13))   # positions followed by values

replace_at(co, list(1, "y"), c(10, 13))   # mixed indices followed by values
```

Next, let's see how invalid indices are signaled.

```{r, error = TRUE}
replace_at(co, z = 10)

replace_at(co, "z", 10)

replace_at(co, 5, 10)
```

If you instead don't mind that elements at new names will be added,
set `.add = TRUE`. Invalid positional indices are still signaled.

```{r, error = TRUE}
co <- replace_at(co, z = 10, .add = TRUE)   # ok

co <- replace_at(co, 7, 10, .add = TRUE)

co
```


#### Strict replace by value

It is also possible to replace elements by value, that is, you specify the
value (not the index) that should be replaced.
To see this, let's replace `12` (located at the 2nd postion) by `"foo"` and
then `y = 5` (located at the 4th position) by `1:2`.

```{r}
co <- replace(co, old = 12, new = "foo")
co

co <- replace(co, old = 5, new = 1:2)
co
```

Implementing this "manually" would require even more additional code as before.
As intended, if the value does not exist, an error is signaled.

```{r, error = TRUE}
replace(co, old = "non-existent-value", new = "my value")
```

Again, the intend that you want to replace but don't mind that the
element is added can be specified:

```{r}
replace(co, old = "non-existent-value", new = "my value", add = TRUE)
```

### Extract

Let's recap the standard extract operators.

```{r}
co[[1]]

co[["x"]]

co[3:5]

co[c("x", "y", "z")]
```

#### Strict extract

The {container} functions to strictly select one or multiple elements are
named `at2` and `at`.^[Resembling R base-internal .subset2 and .subset.]

```{r}
at2(co, 1)

at2(co, "x")

at(co, 3:5)

at(co, c("x", "y", "z"))
```

As before you can specify mixed indices via lists.

```{r}
indices <- list("x", 4, "z")

at(co, indices)
```

Accessing non-existent names or positions is signaled with an error as follows.

```{r, error = TRUE}
at2(co, 10)

at2(co, "a")

at(co, 3:6)

at(co, c("x", "a"))
```

Be reminded that with base *lists* non-existent indices just would have
returned `NULL` values.

```{r}
l <- list()

l[2:3]

l[["a"]]
```

If needed, the (less strict) *list* access can be mimicked with `peek_at` and
`peek_at2`.

```{r}
co

peek_at(co, 10, 11)

peek_at(co, 5:10)

peek_at2(co, "a")
```

As you see, one important difference is that multiple access via `peek_at`
by default instead of `NULL` values just returns nothing.
However, both functions allow to specify a custom default value being
returned if the index does not exist.

```{r}
co

peek_at2(co, "a", default = -1)

peek_at(co, "z", "a", .default = -1)

peek_at(co, 4:8, .default = NA)
```


### Remove

To remove elements in lists, they are usually replaced by `NULL`.

```{r}
l <- list(a = 1)

l

l[["a"]] <- NULL

l
```

With the container package this is done differently, as replacing by `NULL`
will not delete the element but literally replace it by `NULL`.

```{r}
co[["x"]] <- NULL

co
```

Instead, elements can be deleted by index (`delete_at`) or value (`delete`)
as follows.

```{r}
co

delete_at(co, 1, "y", "z")

delete(co, NULL, 1:2, 10)   # same but remove by value
```

As before, invalid indices or missing values are signaled.

```{r, error = TRUE}
co

delete_at(co, "a")

delete_at(co, 10)

delete(co, 1:3)
```


If you need a less strict delete operation, use the `discard` functions, which
delete all valid indices or values and ignore the rest.

```{r}
co

discard_at(co, 1, "a")

discard_at(co, 1:100)

discard(co, NULL, 1:2, 1:3, 1:4)    # discard by value
```


## Combine containers

The `update` function is used to combine/merge two containers.

```{r}
c1 <- container(1, b = 2)
c2 <- container(   b = 0, c = 3)

update(c1, c2)

update(c2, c1)
```

With the container package this function is also provided for base R *lists*.

```{r}
l1 <- list(1, b = 2)
l2 <- list(   b = 0, c = 3)

update(l1, l2)

update(l2, l1)
```

Note that there is a similar function `utils::modifyList`, which, however,
in contrast to `update`, does *not* "forward" unnamed elements.

```{r}
modifyList(l1, l2)

modifyList(l2, l1)  # drops l1[[1]] = 1
```

Also, while `utils::modifyList` modifies a list recursively by changing
a subset of elements at each level, `update` just works on the first level.

```{r}
l1 <- list(a = 1, b = list(c = "a", d = FALSE))

l2 <- list(e = 2, b = list(d = TRUE))

modifyList(l1, l2)  # modifies l1$b$d from FALSE to TRUE

update(l1, l2)      # replaces l1$b by l2$b
```


## Functional programming

The apply family and common higher-order functions both can be used with
containers as usual.

```{r}
co <- container(a = 1, b = 2, c = 3, d = 4)

sapply(co, function(x) x^2)

Filter(co, f = function(x) x > 2)

Reduce(co, f = sum)
```

## Summary

This vignette demonstrates how {container} enhances robust code development by providing:

* Clear and intent-driven operations for adding, replacing, extracting, and removing
  elements, minimizing boilerplate and potential errors.
* Strict validation methods like replace_at() and at() for safer and more precise
  modifications and access.
* Flexible tools like peek_at() and discard() for handling invalid or non-existent
  indices gracefully.
* Safe merging of containers and lists with update()
* Full compatibility with functional programming tools like sapply(), Filter(), and
  Reduce() for streamlined workflows.


To see how some of the functions disussed here are applied with derived
data structures, see:

* [Manage parameter lists with dict](v03-parameter-list.html)
* [Manage data columns with dict.table](v04-manage-data-columns.html)

```{r, include = FALSE}
options(old)
```