-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.Rmd
151 lines (107 loc) · 4.44 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
require(container)
require(badger)
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#",
prompt = F,
fig.path = "images/README-",
tidy = FALSE,
cache = FALSE,
out.width = "100%"
)
old <- options(width = 100L)
```
<!-- badges: start -->
[](https://cran.r-project.org/package=container)
[](https://CRAN.R-project.org/package=container)
[](https://app.codecov.io/gh/rpahl/container)
[](https://github.com/rpahl/container/actions)
[](https://github.com/rpahl/container/actions)
[](https://cran.r-project.org/web/checks/check_results_v01-interactive-usage.html)
[](https://cran.r-project.org/package=container)
[](https://cran.r-project.org/package=container)
[](https://github.com/rpahl/container/commits/master)
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
<!-- badges: end -->
# container <img src="man/figures/logo.png" alt="logo" align="right" width="163" height="104"/>
The {container} package offers an enhanced version of base R's `list` with a
carefully designed set of extract, replace, and remove operations that make
it easier and safer to work with list-like data structures.
### Why use {container}?
{container} objects work similar to base R lists and on top provide
* safe and flexible operations to
* extract (custom default values, no unintended `NULL`)
* add and replace (mixed indices, no unintended overrides)
* remove (loose or strict deletion, remove by index or value)
* compact printing
* optional reference semantics
In addition, {container} provides specialized data structures
[Deque, Set, and Dict]( articles/v05-deque-set-dict.html)
and a *special* class `dict.table`, designed to extend
[data.table](https://CRAN.R-project.org/package=data.table) by
container operations to safely
[Manage data columns with dict.table](articles/v04-manage-data-columns.html).
### Installation
```{r, eval = FALSE}
# Install release version from CRAN
install.packages("container")
# Install development version from GitHub
devtools::install_github("rpahl/container")
```
### Usage
```{r}
library(container)
co <- container(colors = c("Red", "Green"), numbers = c(1, 2, 3), data = cars)
co
```
Use like a base R list
```{r}
co[["colors"]] <- c("Blue", "Yellow")
co[["colors"]]
co[2:1]
```
Safe extract
```{r, error = TRUE}
at(co, "colours") # oops
at(co, "colors")
```
Safe remove
```{r, error = TRUE}
co <- delete_at(co, "colours") # oops
co <- delete_at(co, "colors")
co
```
Flexible peek
```{r, error = TRUE}
at(co, "colors") # oops
peek_at(co, "colors")
peek_at(co, "colors", .default = c("black", "white"))
```
Safe replace
```{r, error = TRUE}
co <- replace_at(co, num = 1:10) # oops
co <- replace_at(co, numbers = 1:10)
co
```
### Get started
* [Use container in interactive session](articles/v01-interactive-usage.html)
* [Use container for code development](articles/v02-code-development.html)
* [Manage parameter lists with dict](articles/v03-parameter-list.html)
* [Manage data columns with dict.table](articles/v04-manage-data-columns.html)
### When *not* to use {container}
Don't bother using the {container} framework when *speed* is of high importance.
An exception is the `dict.table` class, which is very fast as it is based on
[data.table](https://CRAN.R-project.org/package=data.table).
Other than that, if computation speed is critical for your application,
we refer you to using base R lists or packages that were optimized for
performance, such as the
[collections](https://CRAN.R-project.org/package=collections) or
[cppcontainers](https://cran.r-project.org/package=cppcontainers) package.
```{r, include = FALSE}
options(old)
```