---
title: "Function `swap()` function in the `permutations` package"
author: "Robin K. S. Hankin"
output: html_vignette
bibliography: permutations.bib
link-citations: true
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{dovs}
  %\usepackage[utf8]{inputenc}
---

```{r setup, include=FALSE}
set.seed(0)
library("permutations")
options(rmarkdown.html_vignette.check_title = FALSE)
knitr::opts_chunk$set(echo = TRUE)
knit_print.function <- function(x, ...){dput(x)}
registerS3method(
  "knit_print", "function", knit_print.function,
  envir = asNamespace("knitr")
)
```

```{r out.width='20%', out.extra='style="float:right; padding:10px"',echo=FALSE}
knitr::include_graphics(system.file("help/figures/permutations.png", package = "permutations"))
```

```{r, label=showdovs,comment=""}
swap
```

To cite the `permutations` package in publications, please use
@hankin2020.  Function `swap()` returns length-two cycles
corresponding to swapping its two arguments:

```{r showrform}
swap(3, 6)
```

If the two arguments are identical, the identity is returned:

```{r showidentity}
swap(7, 7)
```

It is vectorized:

```{r showvec}
swap(1, 1:8)
swap(1:8, 8:1)
```

Sometimes, printing in word form reveals structure:

```{r printswap}
print_word(swap(9:1, 1:9))
```


We may use `swap()` to effect substitution:

```{r}
options(perm_set = letters)
options(comma = FALSE)
allcyc(1:4)
allcyc(1:4) ^ swap(4, 26)  # replace "d" with "z"
```

Vignette `outer_automorphisms_of_S6` includes a nice use-case of
`swap()`.  Specifically, it uses the identity

$$ (abcd) = (1a)(1b)(1c)(1d)(1a),\qquad 1\not\in\left\lbrace b,c,d\right\rbrace$$

We note that if $a=1$ the identity reduces to $(1bcd) = (1b)(1c)(1d)$.
However, if (say) $c=1$ the conditions of the inequality are not
satisfied.  The right hand side becomes

$$(1a)(1b)(1d)(1a)=(abd)\neq(ab1d)$$.

In package idiom this does not arise because if `1` is present in a
cycle, it appears in the first place following `nicify_cyclist()`.
If, for some reason, we cannot rely on the placing of a possible `1`
we might use


$$(abcd) = (na)(nb)(nc)(nd)(na),\qquad
n\not\in\left\lbrace a,b,c,d\right\rbrace.$$

Observe that $a,b,c,d$ must be distinct, for otherwise the left hand
side is not well-defined.  In the package:

```{r showbad, error=TRUE}
as.cycle(c(3,4,3,6))
```


# References
