---
title: "Use container in interactive session"
output:
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 4
description: >
  A starting point for new users, this vignette introduces the basic functionality
  of {container}. It provides guidance on when to use the package, explains key operations, and illustrates how {container} improves upon base R lists.
vignette: >
  %\VignetteIndexEntry{Use container in interactive session}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r knitr-setup, include = FALSE}
unloadNamespace("dplyr")
require(container)
has = container::has
has_name = container::has_name


knitr::opts_chunk$set(
  comment = "#",
  prompt = F,
  tidy = FALSE,
  cache = FALSE,
  collapse = T
)

old <- options(width = 100L)
```


## Interactive usage

In an interactive R session a container can be used similar to a base
R `list`, but also provides some extra features.
For easier typing it's recommended to use the shorter `cont`.

```{r}
library(container)
co <- cont(a = 1, b = 1:10)  # same as co = container(a = 1, b = 1:10)
```

The container print method is designed to be very compact.

```{r}
print(co)
```

For more verbose output, either convert to a base `list` ...

```{r}
as.list(co)
```

or use `str`.

```{r}
str(co)
```

Both `length` and `names` work as usual.

```{r}
length(co)

names(co)

names(co)[1] <- "A"

co
```

A container can also be constructed from a list.

```{r}
l <- list(x = (1:2)^1, y = (1:2)^2)
co2 <- as.container(l)

co2
```


### Add

Elements can be added by concatenation,

```{r}
c(co, c = 3, d = 4)

c(co, co2)
```

or name,

```{r}
co[["c"]] <- 3

co
```

and containers can be nested.

```{r}
co[["co2"]] <- co2

co
```

In contrast to base R `list`, elements cannot be added via positional index
if it exceeds the container's length.

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


### Replace

Single or multiple value replacement works as usual.

```{r}
co[[3]] <- 0
co[1:2] <- 0

co
```

In contrast to base `list`, containers can take a mix of numeric and character
indices.

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

co
```

Another option is to replace *by value*.

```{r}
co[[{"three"}]] <- 3

co
```

This works for any data type.

```{r}
co[[{co2}]] <- 3

co
```


### Extract

The following standard access operators can be applied.

```{r}
co[["A"]]

co[[1]]

co[1:3]
```

At this point, neither the `$` operator nor negative indices^[Negative indexing support
is planned for the next version.] are supported.
They just give empty results.

```{r}
co$A

co[-1]
```

For now, a workaround for negative indexing is to temporarily convert to a list.

```{r}
tmp <- as.list(co)

as.container(tmp[-1])
```


As another option, you can pass any number of indices, possibly mixed as numeric
and character.

```{r}
co[1, 3, "b"]

co[2:1, "A"]
```

Invalid indices don't produce `NULL`s but are just ignored.

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

co[3:33]

co[10:20]
```


### Inspect

Count the number of elements.

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

count(co, 3)
```


## Summary

This vignette showcases how {container} enhances interactive R workflows by combining
the familiarity of base R list operations with additional features:

* Compact printing for quick overviews, with options for detailed inspection
  via as.list() and str().
* Flexible adding and replacing of elements, supporting mixed indices and
  preventing out-of-bounds additions.
* Intuitive extraction using familiar operators, with safe handling of invalid indices.

Next, see vignette [Use container for code development](v02-code-development.html).

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