index_to_sprinkle {pixiedust}

Determine the Indices to Sprinkle

Description

The sprinkle methods accept the rows and columns that are to be modified as matrix coordinates. The dust object stores the table data in a long form. The tabular coordinates are translated into row indices using this function.

Usage

index_to_sprinkle(
  x,
  rows = NULL,
  cols = NULL,
  fixed = FALSE,
  part = c("body", "head", "foot", "interfoot"),
  recycle = c("none", "rows", "cols", "columns"),
  coll = NULL
)

Arguments

x

An object of class dust.

rows

Either a numeric vector of rows in the tabular object to be modified or an object of class call. When a call, generated by quote(expression), the expression resolves to a logical vector the same length as the number of rows in the table. Sprinkles are applied to where the expression resolves to TRUE.

cols

Either a numeric vector of columns in the tabular object to be modified, or a character vector of column names. A mixture of character and numeric indices is permissible.

fixed

logical(1) indicating if the values in rows and cols should be read as fixed coordinate pairs. See Details.

part

character string. Specifies if the sprinkles are being applied to the head, body, foot, or interfoot of the table. Partial matching is supported.

recycle

character string. Indicates how recycling is to be performed. Partial matching is supported. See Details.

coll

An optional AssertCollection object. When NULL, an AssertCollection object will be created and reported within the call to this function. When not NULL, any failed assertions will be added to the object in reported in the function that called index_to_sprinkle.

Details

When fixed = FALSE, sprinkles are applied at the intersection of rows and cols, meaning that the arguments do not have to share the same length. When fixed = TRUE, they must share the same length.

The value of recycle determines how sprinkles are managed when the sprinkle input doesn't match the length of the region to be sprinkled. By default, recycling is turned off. Recycling may be performed across rows first (left to right, top to bottom), or down columns first (top to bottom, left to right). "cols" and "columns" have the same effect. The two choices to specify are motivated by the fact that I sometimes get confused about which it should be. :)

Functional Requirements

1. Return the indices of the intersection of rows and cols

2. If rows = NULL, assume all rows.

3. If rows is an expression where no values resolve to TRUE, return x unchanged.

4. If any value in rows is not a valid row in the table, cast an error.

5. If cols = NULL, assume all columns.

6. If any value in cols does not identify a column in the table, cast an error.

7. If fixed = TRUE, length(rows) (or sum(rows), if an expression) and cols must have the same length.

8. Cast an error if fixed is not a logical(1)

9. Cast an error if part is not one of "body", "head", "foot", or "interfoot".

Author(s)

Benjamin Nutter

See Also

sprinkle