omapR: R6 class representing an ordered map

omapRR Documentation

R6 class representing an ordered map

Description

A map is given by keys and values.

Methods

Public methods


Method new()

Creates a new omapR object.

Usage
omapR$new(keys, values, duplicated = "drop", checks = TRUE)
Arguments
keys

keys, a character vector without NA value

values

values, a list of R objects; keys and values must have the same length

duplicated

the action to perform for duplicated keys, one of "drop", "join", or "separate"

checks

Boolean, whether to check keys and values

Returns

An omapR object.

Examples
omapR$new(
  keys = c("z", "a"), 
  values = list(c(1, 2), c(3, 4, 5))
)
# examples with duplicated keys:
omapR$new(
  keys = c("a", "a", "b"), 
  values = list(c(1, 2), c(3, 4), c(5, 6))
)
omapR$new(
  keys = c("a", "a", "b"), 
  values = list(c(1, 2), c(3, 4), c(5, 6)),
  duplicated = "join"
)
omapR$new(
  keys = c("a", "a", "b"), 
  values = list(c(1, 2), c(3, 4), c(5, 6)),
  duplicated = "separate"
)

Method print()

Show instance of an omapR object.

Usage
omapR$print(...)
Arguments
...

ignored


Method size()

Size of the reference map.

Usage
omapR$size()
Returns

An integer, the number of entries.

Examples
map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$size()

Method keys()

Get all keys.

Usage
omapR$keys()
Returns

The keys, a character vector.

Examples
map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$keys()

Method values()

Get all values.

Usage
omapR$values()
Returns

The values, a list of numeric vectors.

Examples
map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$values()

Method items()

Get all entries of the reference map.

Usage
omapR$items()
Returns

The entries in a dataframe.

Examples
map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$items()

Method toList()

Converts the map to a named list.

Usage
omapR$toList()
Returns

A named list.

Examples
map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$toList()

Method at()

Returns the 'maybe' value corresponding to the given key.

Usage
omapR$at(key)
Arguments
key

a key (string)

Returns

A maybe value, either the value corresponding to the key as a 'Just' maybe value if the key is found, otherwise the 'Nothing' maybe value.

Examples
map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$at("b")
from_just(map$at("b"))
map$at("x")

Method index()

Returns the index of the given key.

Usage
omapR$index(key)
Arguments
key

a key (string)

Returns

The index of the key, or NA if it is not found.

Examples
map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$index("b")
map$index("x")

Method extract()

Extract a submap from the reference map.

Usage
omapR$extract(keys, inplace = FALSE, bydeleting = FALSE)
Arguments
keys

some keys, a character vector; those which do not belong to the keys of the reference map will be ignored

inplace

Boolean, whether to update the reference map or to return a new map

bydeleting

Boolean, whether to construct the submap by deleting the keys which are not in keys or by starting from the empty submap and adding the entries

Returns

An omapR object if inplace=FALSE, nothing otherwise.

Examples
map <- omapR$new(
  keys = c("a", "b", "c"), 
  values = list(c(1, 2), c(3, 4, 5), c(6, 7))
)
map_copy <- map$copy()
map$extract(c("a", "c"))
map
map$extract(c("a", "c"), inplace = TRUE)
map
map_copy$extract(c("a", "c"), bydeleting = TRUE)
map_copy
map_copy$extract(c("a", "c"), inplace = TRUE, bydeleting = TRUE)
map_copy

Method has_key()

Checks whether a key exists in the reference map.

Usage
omapR$has_key(key)
Arguments
key

a key (string)

Returns

A Boolean value.

Examples
map <- omapR$new(
  keys = c("a", "b"), 
  values = list(c(1, 2), c(3, 4, 5))
)
map$has_key("b")
map$has_key("x")

Method nth()

Returns the n-th entry of the reference map.

Usage
omapR$nth(n, stop_if_too_large = TRUE)
Arguments
n

index, a positive integer

stop_if_too_large

a Boolean value, whether to stop if n is too large, or to use maybe values

Returns

A list with the key and the value at index n if stop_if_too_large=TRUE and n is not too large, otherwise a maybe value: either this list wrapped in a 'Just' container, or 'Nothing'.

Examples
map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$nth(2)
map$nth(2, stop_if_too_large = FALSE)
map$nth(9, stop_if_too_large = FALSE)

Method insert()

Insert a new entry in the reference map.

Usage
omapR$insert(key, value, replace = FALSE)
Arguments
key

a key (string)

value

a value (R object)

replace

Boolean, whether to replace the value if the key is already present

Returns

This updates the reference map and this returns a Boolean value: if replace=FALSE, this returns TRUE if the value has been inserted (i.e. the given key is new); similarly, if replace=TRUE, this returns TRUE if the given key is new (so FALSE means that the value of the existing key has been replaced).

Examples
map <- omapR$new(
  keys = c("a", "b"), 
  values = list(c(1, 2), c(3, 4, 5))
)
map$insert("c", c(6, 7)) # TRUE (insertion)
map
map$insert("a", c(8, 9)) # FALSE (no change)
map
map$insert("a", c(8, 9), replace = TRUE) # FALSE (replacement)
map

Method erase()

Erase the entries of the reference map whose keys are the given ones.

Usage
omapR$erase(keys)
Arguments
keys

some keys, a character vector

Returns

Nothing, this updates the map.

Examples
map <- omapR$new(
  keys = c("a", "b", "c"), 
  values = list(c(1, 2), c(3, 4, 5), c(6, 7))
)
map$erase("a")
map
map$erase(c("b", "c"))
map

Method merge()

Merge the reference map with another map.

Usage
omapR$merge(map, duplicated = "drop")
Arguments
map

an omapR object

duplicated

the action to perform if the reference map and map have some identical keys, one of "drop", "join", or "separate"

Returns

Nothing, this updates the reference map.

Examples
map1 <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map2 <- omapR$new(
  keys = c("c", "d"), values = list(c(9, 8), c(7, 6))
)
map1$merge(map2)
map1

# `duplicated` example ####
map1 <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map1_copy1 <- map1$copy()
map1_copy2 <- map1$copy()
map1_copy3 <- map1$copy()
map2 <- omapR$new(
  keys = c("a", "d"), values = list(c(9, 8), c(7, 6))
)
map1_copy1$merge(map2)
map1_copy1

map1_copy2$merge(map2, duplicated = "join")
map1_copy2

map1_copy3$merge(map2, duplicated = "separate")
map1_copy3

Method copy()

Copy the reference map.

Usage
omapR$copy()
Returns

A copy of the reference map.

Examples
map <- omapR$new(
  c("a", "b"), 
  list(c(1,2), c(FALSE, TRUE))
)
true_copy <- map$copy()
true_copy$erase("a")
map
naive_copy <- map
naive_copy$erase("a")
map

See Also

from_just

Examples


## ------------------------------------------------
## Method `omapR$new`
## ------------------------------------------------

omapR$new(
  keys = c("z", "a"), 
  values = list(c(1, 2), c(3, 4, 5))
)
# examples with duplicated keys:
omapR$new(
  keys = c("a", "a", "b"), 
  values = list(c(1, 2), c(3, 4), c(5, 6))
)
omapR$new(
  keys = c("a", "a", "b"), 
  values = list(c(1, 2), c(3, 4), c(5, 6)),
  duplicated = "join"
)
omapR$new(
  keys = c("a", "a", "b"), 
  values = list(c(1, 2), c(3, 4), c(5, 6)),
  duplicated = "separate"
)

## ------------------------------------------------
## Method `omapR$size`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$size()

## ------------------------------------------------
## Method `omapR$keys`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$keys()

## ------------------------------------------------
## Method `omapR$values`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$values()

## ------------------------------------------------
## Method `omapR$items`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$items()

## ------------------------------------------------
## Method `omapR$toList`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$toList()

## ------------------------------------------------
## Method `omapR$at`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$at("b")
from_just(map$at("b"))
map$at("x")

## ------------------------------------------------
## Method `omapR$index`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$index("b")
map$index("x")

## ------------------------------------------------
## Method `omapR$extract`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b", "c"), 
  values = list(c(1, 2), c(3, 4, 5), c(6, 7))
)
map_copy <- map$copy()
map$extract(c("a", "c"))
map
map$extract(c("a", "c"), inplace = TRUE)
map
map_copy$extract(c("a", "c"), bydeleting = TRUE)
map_copy
map_copy$extract(c("a", "c"), inplace = TRUE, bydeleting = TRUE)
map_copy

## ------------------------------------------------
## Method `omapR$has_key`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b"), 
  values = list(c(1, 2), c(3, 4, 5))
)
map$has_key("b")
map$has_key("x")

## ------------------------------------------------
## Method `omapR$nth`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map$nth(2)
map$nth(2, stop_if_too_large = FALSE)
map$nth(9, stop_if_too_large = FALSE)

## ------------------------------------------------
## Method `omapR$insert`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b"), 
  values = list(c(1, 2), c(3, 4, 5))
)
map$insert("c", c(6, 7)) # TRUE (insertion)
map
map$insert("a", c(8, 9)) # FALSE (no change)
map
map$insert("a", c(8, 9), replace = TRUE) # FALSE (replacement)
map

## ------------------------------------------------
## Method `omapR$erase`
## ------------------------------------------------

map <- omapR$new(
  keys = c("a", "b", "c"), 
  values = list(c(1, 2), c(3, 4, 5), c(6, 7))
)
map$erase("a")
map
map$erase(c("b", "c"))
map

## ------------------------------------------------
## Method `omapR$merge`
## ------------------------------------------------

map1 <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map2 <- omapR$new(
  keys = c("c", "d"), values = list(c(9, 8), c(7, 6))
)
map1$merge(map2)
map1

# `duplicated` example ####
map1 <- omapR$new(
  keys = c("a", "b"), values = list(c(1, 2), c(3, 4, 5))
)
map1_copy1 <- map1$copy()
map1_copy2 <- map1$copy()
map1_copy3 <- map1$copy()
map2 <- omapR$new(
  keys = c("a", "d"), values = list(c(9, 8), c(7, 6))
)
map1_copy1$merge(map2)
map1_copy1

map1_copy2$merge(map2, duplicated = "join")
map1_copy2

map1_copy3$merge(map2, duplicated = "separate")
map1_copy3

## ------------------------------------------------
## Method `omapR$copy`
## ------------------------------------------------

map <- omapR$new(
  c("a", "b"), 
  list(c(1,2), c(FALSE, TRUE))
)
true_copy <- map$copy()
true_copy$erase("a")
map
naive_copy <- map
naive_copy$erase("a")
map

stla/mapR documentation built on April 16, 2022, 11:54 p.m.