R: Key-Value Storage

Dictionary {mlr3misc} | R Documentation

## Key-Value Storage

### Description

A key-value store for R6::R6 objects. On retrieval of an object, the following applies:

- If the object is a `R6ClassGenerator`, it is initialized with `new()`.

- If the object is a function, it is called and must return an instance of a R6::R6 object.

- If the object is an instance of a R6 class, it is returned as-is.

Default argument required for construction can be stored alongside their constructors by passing them to `$add()`.

### S3 methods

- `as.data.table(d)`
  Dictionary -> `data.table::data.table()`
  Converts the dictionary to a `data.table::data.table()`.

### Public fields

`items`

  (`environment()`)
  Stores the items of the dictionary

### Methods

#### Public methods

- `Dictionary$new()`

- `Dictionary$format()`

- `Dictionary$print()`

- `Dictionary$keys()`

- `Dictionary$has()`

- `Dictionary$get()`

- `Dictionary$mget()`

- `Dictionary$add()`

- `Dictionary$remove()`

- `Dictionary$required_args()`

- `Dictionary$clone()`

#### Method `new()`

Construct a new Dictionary.

##### Usage

    Dictionary$new()

#### Method `format()`

Format object as simple string.

##### Usage

    Dictionary$format()

#### Method `print()`

Print object.

##### Usage

    Dictionary$print()

#### Method `keys()`

Returns all keys which comply to the regular expression `pattern`. If `pattern` is `NULL` (default), all keys are returned.

##### Usage

    Dictionary$keys(pattern = NULL)

##### Arguments

`pattern`

  (`character(1)`).

##### Returns

`character()` of keys.

#### Method `has()`

Returns a logical vector with `TRUE` at its i-th position if the i-th key exists.

##### Usage

    Dictionary$has(keys)

##### Arguments

`keys`

  (`character()`).

##### Returns

`logical()`.

#### Method `get()`

Retrieves object with key `key` from the dictionary. Additional arguments must be named and are passed to the constructor of the stored object.

##### Usage

    Dictionary$get(key, ...)

##### Arguments

`key`

  (`character(1)`).

`...`

  (`any`)
  Passed down to constructor.

##### Returns

Object with corresponding key.

#### Method `mget()`

Returns objects with keys `keys` in a list named with `keys`. Additional arguments must be named and are passed to the constructors of the stored objects.

##### Usage

    Dictionary$mget(keys, ...)

##### Arguments

`keys`

  (`character()`).

`...`

  (`any`)
  Passed down to constructor.

##### Returns

Named `list()` of objects with corresponding keys.

#### Method `add()`

Adds object `value` to the dictionary with key `key`, potentially overwriting a previously stored item. Additional arguments in `...` must be named and are passed as default arguments to `value` during construction. The names of all additional arguments which are mandatory for construction and missing in `...` should be listed in `required_args`.

##### Usage

    Dictionary$add(key, value, ..., required_args = character())

##### Arguments

`key`

  (`character(1)`).

`value`

  (`any`).

`...`

  (`any`)
  Passed down to constructor.

`required_args`

  (`character()`).

##### Returns

`Dictionary`.

#### Method `remove()`

Removes objects with from the dictionary.

##### Usage

    Dictionary$remove(keys)

##### Arguments

`keys`

  (`character()`)
  Keys of objects to remove.

##### Returns

`Dictionary`.

#### Method `required_args()`

Returns the names of arguments required to construct the object.

##### Usage

    Dictionary$required_args(key)

##### Arguments

`key`

  (`character(1)`)
  Key of object to query for required arguments.

##### Returns

`character()` of names of required arguments.

#### Method `clone()`

The objects of this class are cloneable with this method.

##### Usage

    Dictionary$clone(deep = FALSE)

##### Arguments

`deep`

  Whether to make a deep clone.

### Examples

    library(R6)
    item1 = R6Class("Item", public = list(x = 1))
    item2 = R6Class("Item", public = list(x = 2))
    d = Dictionary$new()
    d$add("a", item1)
    d$add("b", item2)
    d$add("c", item1$new())
    d$keys()
    d$get("a")
    d$mget(c("a", "b"))

[Package mlr3misc version 0.9.5 Index]