sprinkle_border: Sprinkle Changes to Cell Borders

View source: R/sprinkle_border.R

sprinkle_borderR Documentation

Sprinkle Changes to Cell Borders

Description

Cell borders may be used to give visual structure to a table. Borders may generate distinction between sets of results, groups, or types of output.

Usage

sprinkle_border(
  x,
  rows,
  cols,
  border = c("all", "bottom", "left", "top", "right"),
  border_color = "black",
  border_style = "solid",
  border_thickness = 1,
  border_units = c("pt", "px"),
  part = c("body", "head", "foot", "interfoot", "table"),
  fixed = FALSE,
  recycle = c("none", "rows", "cols", "columns"),
  ...
)

## Default S3 method:
sprinkle_border(
  x,
  rows = NULL,
  cols = NULL,
  border = c("all", "bottom", "left", "top", "right"),
  border_color = "black",
  border_style = "solid",
  border_thickness = 1,
  border_units = c("pt", "px"),
  part = c("body", "head", "foot", "interfoot", "table"),
  fixed = FALSE,
  recycle = c("none", "rows", "cols", "columns"),
  ...
)

## S3 method for class 'dust_list'
sprinkle_border(
  x,
  rows = NULL,
  cols = NULL,
  border = c("all", "bottom", "left", "top", "right"),
  border_color = "black",
  border_style = "solid",
  border_thickness = 1,
  border_units = c("pt", "px"),
  part = c("body", "head", "foot", "interfoot", "table"),
  fixed = FALSE,
  recycle = c("none", "rows", "cols", "columns"),
  ...
)

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.

border

One or more of "all", "bottom", "left", "top", or "right". Partial matching is supported. Designates the side of the chosen cells for which borders should be modified.

border_color

character(1) A character string giving a color for the background of the chosen cells. NULL makes no change to the current value.

border_style

character(1) setting the border style for the cell. One of "solid", "dashed", "dotted", "double", "groove", "ridge", "inset", "outset", "hidden", or "none". NULL makes no change to the current value.

border_thickness

numeric(1). Sets the thickness of the border. NULL makes no change to the current value.

border_units

character(1). Sets the unit of measure for the border thickness. May be either "pt", "px". NULL makes no change to the current value.

part

A character string denoting which part of the table to modify.

fixed

logical(1) indicating if the values in rows and cols should be read as fixed coordinate pairs. By default, 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.

recycle

A character one that 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).

...

Additional arguments to pass to other methods. Currently ignored.

Details

This sprinkle has no effect on console and markdown output.

HTML output accepts all of the possible values of border_style.

For LaTeX output, when hhline = FALSE, "solid", "dashed", "dotted", "hidden", and "none" are accepted. "dotted" will silently be treated as "dashed", and "hidden" is the equivalent of "none".

For LaTeX output when hhline = TRUE, "solid", "double", "hidden", and "none" are accepted. "hidden" is the equivalent of "none".

When a value of border_style is not recognized by an output format, it is silently ignored.

Functional Requirements

  1. Correctly reassigns the left_border, right_border, top_border and bottom_border columns in the table part.

  2. Casts an error if x is not a dust object.

  3. Casts an error if any element of border is not one of "all", "bottom", "left", "top", or "right".

  4. Casts an error if border_color is not a character(1)

  5. Casts an error if border_color is not a valid color format.

  6. Casts an error if border_style is not one of "solid", "dashed", "dotted", "double", "groove", "ridge", "inset", "outset", "hidden", "none"

  7. Casts an error if border_thickness is not a numeric(1).

  8. Casts an error if border_units is not one of "pt" or "px".

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

  10. Casts an error if fixed is not a logical(1)

  11. Casts an error if recycle is not one of "none", "rows", or "cols"

  12. Cast an error if recycle = "none" and border_color does not have length 1.

  13. Cast an error if recycle = "none" and border_style does not have length 1.

  14. Cast an error if recycle = "none" and border_thickness does not have length 1.

  15. Quietly restrict border_units to just the first element if is has length > 1 and recycle = "none".

Author(s)

Benjamin Nutter

See Also

sprinkle, index_to_sprinkle


pixiedust documentation built on Oct. 10, 2023, 9:07 a.m.