---
title: "inops vignette"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{inops vignette}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

library(inops)
```

# inops

Package implementing additional infix operators for R.

Implemented operators work with 4 different value types: **sets**, **intervals**, **regular expressions**, and **counts**.\
And provide 3 distinct functionalities: **detection**, **subsetting**, and **replacement**.

Install using the `remotes` package:

```
remotes::install_github("moodymudskipper/inops")
```

## Syntax ##

All operators have the same form composed of two distinct parts: `%<operation><type>%`.

* `[operation]` specifies the performed functionality and can be one of `in`, `out`, `[in`, `[out`.
* `[type]` specifies the type of operation and can be one of `{}`, `[]`, `()`, `[)`, `(]`, `~`, `~p`, `~f`, `#`.

## Value Types ##

1. **sets**

```
 %in{}%
%out{}%
```

Work with the same values as `%in%` does but provide a more consistent behaviour for `data.frames` and `NA` values.

```{r}
letters <- letters[1:10]
letters

# sets

letters %in{}% c("a", "b", "c", "e")

letters %out{}% c("a", "b", "c", "e")
```

2. **ranges**

```
 %in()%   %in[]%   %in[)%   %in(]%
%out()%  %out[]%  %out[)%  %out(]%
```

```{r}
1:10

# closed interval

1:10 %in()% c(3,6)

1:10 %out()% c(3,6)

# open interval

1:10 %in[]% c(3,6)

1:10 %out[]% c(3,6)

# open on the right

1:10 %in(]% c(3,6)

1:10 %out(]% c(3,6)

# open on the left

1:10 %in[)% c(3,6)

1:10 %out[)% c(3,6)
```

3. **patterns**

```
 %in~%   %in~f%   %in~p%
%out~%  %out~f%  %out~p%
```

```{r}
month.name

# regular expressions

month.name %in~% "^M.*"

month.name %out~% "^M.*"

# fixed string regular expressions

month.name %in~f% "^M.*"

month.name %out~f% "^M.*"

# perl regular expressions

month.name %in~p% "^(?=.*r)(?!.*er)"

month.name %out~p% "^(?=.*r)(?!.*er)"

```

4. **counts**

```
 %in#%
%out#%
```

```{r}
values <- c("a", "a", "b", "b", "b", "c")
values

# number of occurances

values %in#% 1:2

values %out#% 1:2

```

## Operations ##

1. **detection**

Same form as examples shown above.

```{r}
month.name

month.name %in~% c("^A", "^M")
```

2. **subsetting**

Used for obtaining actual values.\
Starts with `[`.

```{r}
month.name

month.name %[in~% c("^A", "^M")
```

3. **replacement**

Used for replacing the matched elements with new values.\
Called with assignment `<-` at the end.

```{r}
month.name

month.name %in~% c("^A", "^M") <- "A or M"

month.name
```

## Behaviour ##

The operators implemented here try to be consistent with the default comparison operators like `==` and `<`.\
Therefore in some scenarios their behaviour differs from `%in%`.\
For instance:

1) `%in{}%` can be used on on data frames.

```{r}
df1 <- data.frame(a = 1:3, b = 2:4, c=letters[1:3])

df1 == 2

df1 %in% 2

df1 %in{}% 2

df1 %in{}% 2:3
```

2) missing values are not considered as not matching.

```{r}
NA == 1

NA %in% 1

NA %in{}% 1

NA %in% NA

NA %in{}% NA

c(1, NA, 3) %in{}% 1:10
```

## Additional Examples ##

Simple examples for illustration.

---

Selecting flight records from the `flights` dataset that:

1. Departed and Landed between noon and 5 p.m.
2. Were not traveling to "LEX", "PSP", nor "HDN"
3. Travelled distance was either very short (below 100) or very long (above 3000)
4. Had a tail number starting with "N1" or "N3"

```{r, message=FALSE}
library(nycflights13)
library(dplyr)
library(inops)

flights <- select(flights, origin, dest, tailnum, dep_time, arr_time, distance)
flights

filter(flights,
       dep_time %in()%  c(1200, 1700),
       arr_time %in()%  c(1200, 1700),
       dest     %out%   c("LEX", "PSP", "HDN"),
       distance %out[]% c(100, 3000),
       tailnum  %in~%   c("^N1", "^N3")
       )
```

---

Cleaning up `planes` dataset in order to:

1. Standardize names of "AIRBUS", "CANADAIR" and "MCDONNELL" manufacturers.
2. Obtain plane counts for each of the 3 manufacturers mentioned above.

```{r, message=FALSE}
library(nycflights13)
library(inops)

table(planes$manufacturer %[in~% c("AIRBUS", "CANADAIR", "MCDONNELL"))

planes$manufacturer %in~% "AIRBUS"    <- "AIRBUS"
planes$manufacturer %in~% "CANADAIR"  <- "CANADAIR"
planes$manufacturer %in~% "MCDONNELL" <- "MCDONNELL"

table(planes$manufacturer %[in~% c("AIRBUS", "CANADAIR", "MCDONNELL"))

```

---

Combine engine models that in the dataset occur less than 6 times under the "Other" group.

```{r, message=FALSE}
library(nycflights13)
library(inops)

table(planes$engine)

planes$engine %in#% 1:5 <- "Other"

table(planes$engine)

```

---

## Full List ##

Below is a full list of all the implemented operators along with their usage examples.

### Detection Operators ###

|  Form       |                             Description                                  |            Call               |
|-------------|--------------------------------------------------------------------------|-------------------------------|
| `%in{}%`    | which elements are inside a set                                          | `x %in{}% set`                |
| `%in[]%`    | which elements are inside a closed interval                              | `x %in[]% interval`           |
| `%in()%`    | which elements are inside an open interval                               | `x %in()% interval`           |
| `%in[)%`    | which elements are inside an interval open on the right                  | `x %in[)% interval`           |
| `%in(]%`    | which elements are inside an interval open on the left                   | `x %in(]% interval`           |
| `%in~%`     | which elements match a regular expression                                | `x %in~% pattern`             |
| `%in~p%`    | which elements match a regular perl expression                           | `x %in~p% pattern`            |
| `%in~f%`    | which elements match a regular fixed expression                          | `x %in~f% pattern`            |
| `%in#%`     | which elements occur a specified number of times                         | `x %in#% count`               |
| `%out%`     | which elements are outside a set (same as ! x %in% y)                    | `x %out% set`                 |
| `%out{}%`   | which elements are outside a set                                         | `x %out{}% set`               |
| `%out[]%`   | which elements are outside a closed interval                             | `x %out[]% interval`          |
| `%out()%`   | which elements are outside an open interval                              | `x %out()% interval`          |
| `%out[)%`   | which elements are outside an interval open on the right                 | `x %out[)% interval`          |
| `%out(]%`   | which elements are outside an interval open on the left                  | `x %out(]% interval`          |
| `%out~%`    | which elements do not match a regular expression                         | `x %out~% pattern`            |
| `%out~p%`   | which elements do not match a regular perl expression                    | `x %out~p% pattern`           |
| `%out~f%`   | which elements do not match a regular fixed expression                   | `x %out~f% pattern`           |
| `%out#%`    | which elements occur other than a specified number of times              | `x %out#% count`              |

### Subsetting Operators ###

|  Form       |                             Description                                  |            Call               |
|-------------|--------------------------------------------------------------------------|-------------------------------|
| `%[in%`     | select elements inside a set                                             | `x %[in% set`                 |
| `%[in{}%`   | select elements inside a set                                             | `x %[in{}% set`               |
| `%[in[]%`   | select elements inside a closed interval                                 | `x %[in[]% interval`          |
| `%[in()%`   | select elements inside an open interval                                  | `x %[in()% interval`          |
| `%[in[)%`   | select elements inside an interval open on the right                     | `x %[in[)% interval`          |
| `%[in(]%`   | select elements inside an interval open on the left                      | `x %[in(]% interval`          |
| `%[in~%`    | select elements matching a regular expression                            | `x %[in~% pattern`            |
| `%[in~p%`   | select elements matching a regular perl expression                       | `x %[in~p% pattern`           |
| `%[in~f%`   | select elements matching a regular fixed expression                      | `x %[in~f% pattern`           |
| `%[in#%`    | select elements that occur a specified number of times                   | `x %[in#% count`              |
| `%[out%`    | select elements outside a set                                            | `x %[out%  set`               |
| `%[out{}%`  | select elements outside a set                                            | `x %[out{}%  set`             |
| `%[out[]%`  | select elements outside a closed interval                                | `x %[out[]% interval`         |
| `%[out()%`  | select elements outside an open interval                                 | `x %[out()% interval`         |
| `%[out[)%`  | select elements outside an interval open on the right                    | `x %[out[)% interval`         |
| `%[out(]%`  | select elements outside an interval open on the left                     | `x %[out(]% interval`         |
| `%[out~%`   | select elements not matching a regular expression                        | `x %[out~% pattern`           |
| `%[out~p%`  | select elements not matching a regular perl expression                   | `x %[out~p% pattern`          |
| `%[out~f%`  | select elements not matching a regular fixed expression                  | `x %[out~f% pattern`          |
| `%[out#%`   | select elements that occur other than specified number of times          | `x %[out% count`              |

### Replacement Operators ###

|  Form       |                             Description                                  |            Call               |
|-------------|--------------------------------------------------------------------------|-------------------------------|
| `==<-`      | change elements equal to the provided value                              | `x == element <- value`       |
| `!=<-`      | change elements not equal to the provided value                          | `x != element <- value`       |
| `><-`       | change elements greater than the provided value                          | `x > number <- value`         |
| `<<-`       | change elements lower than the provided value                            | `x < number  <- value`        |
| `>=<-`      | change elements greater or equal to the provided value                   | `x >= number <- value`        |
| `<=<-`      | change elements lower or equal to the provided value                     | `x <= number <- value`        |
| `%in%<-`    | change elements inside a set                                             | `x %in% set <- value`         |
| `%in{}%<-`  | change elements inside a set                                             | `x %in{}% set <- value`       |
| `%in[]%<-`  | change elements inside a closed interval                                 | `x %in[]% interval <- value`  |
| `%in()%<-`  | change elements inside an open interval                                  | `x %in()% interval <- value`  |
| `%in[)%<-`  | change elements inside an interval open on the right                     | `x %in[)% interval <- value`  |
| `%in(]%<-`  | change elements inside an interval open on the left                      | `x %in(]% interval <- value`  |
| `%in~%<-`   | change elements matching a regular expression                            | `x %in~% pattern <- value`    |
| `%in~p%<-`  | change elements matching a regular perl expression                       | `x %in~p% pattern <- value`   |
| `%in~f%<-`  | change elements matching a regular fixed expression                      | `x %in~f% pattern <- value`   |
| `%in#%<-`   | change elements that occur specified number of times                     | `x %in#% count <- value`      |
| `%out%<-`   | change elements outside a set                                            | `x %out% set <- value`        |
| `%out{}%<-` | change elements outside a set                                            | `x %out{}% set <- value`      |
| `%out[]%<-` | change elements outside a closed interval                                | `x %out[]% interval <- value` |
| `%out()%<-` | change elements outside an open interval                                 | `x %out()% interval <- value` |
| `%out[)%<-` | change elements outside an interval open on the right                    | `x %out[)% interval <- value` |
| `%out(]%<-` | change elements outside an interval open on the left                     | `x %out(]% interval <- value` |
| `%out~%<-`  | change elements not matching a regular expression                        | `x %out~% pattern <- value`   |
| `%out~p%<-` | change elements not matching a regular perl expression                   | `x %out~p% pattern <- value`  |
| `%out~f%<-` | change elements not matching a regular fixed expression                  | `x %out~f% pattern <- value`  |
| `%out#%<-`  | change elements that occur other than specified number of times          | `x %out#% count <- value`     |

## Notes ##

To give an assignment counterpart to `<` we had to overload the `<<-` operator, which explains the message when attaching the package.
This doesn't affect the behavior of the `<<-` assignments.