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

```{r setup, include=FALSE}
library("clifford")
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='15%', out.extra='style="float:right; padding:10px"',echo=FALSE}
knitr::include_graphics(system.file("help/figures/clifford.png", package = "clifford"))
```

```{r showgetcoeffs}
getcoeffs
```

To cite the `clifford` package in publications please use
@hankin2022_clifford.  This short document discusses function
`getcoeffs()` in the `clifford` R package which, as its name suggests,
retrieves specific coefficients from a clifford object.  It is a
relatively low-level helper function that is a wrapper for a `C`
routine.  It takes as arguments a clifford object and a list of terms:

```{r use_getcoeffs}
set.seed(0)
(a <- rcliff())
getcoeffs(a,list(1:2, 0, c(2,5), c(1,5,6), c(2,6), 1:2))
```

Note that the first and last element of the returned vector are both
the coefficient of $e_{12}$, _viz._ `-9`.  The coefficients are
returned in the form of a numeric vector [not a `disord` object: the
order of the elements is determined by the order of argument `B`].
Compare standard extraction, e.g. `a[index]`, which returns a
`clifford` object.  Also, compare `coeffs()` which extracts _all_
coefficients of a clifford object:

```{r showcoeffs}
coeffs(a)
```

The index for the constant is formally `list(numeric(0))`, but this is
a pain to type, so there is special dispensation for argument `B`
having list elements of zero, which are translated by helper function
`list_modifier()` to `numeric(0)` and listified if necessary.  The
upshot is that a zero list element in argument `B` works as expected
extracting the constant.  Also, passing `B=0` works as expected,
returning the constant (there is no need to coerce to a list: coercion
is performed by `list_modifier)`.  A similar scheme is used in the
square bracket extraction and replacement methods

Attempting to extract a coefficient of a term that includes a negative
index will throw an error.  The coefficient of a term including an
index larger than indicated by `maxyterm()` will return zero.

# References