formatters (version 0.5.12)

pag_indices_inner: Find pagination indices from pagination info data frame

Description

Pagination methods should typically call the make_row_df method for their object and then call this function on the resulting pagination info data.frame.

Usage

pag_indices_inner(
  pagdf,
  rlpp,
  lpp_or_cpp = NA_integer_,
  context_lpp_or_cpp = NA_integer_,
  min_siblings,
  nosplitin = character(),
  verbose = FALSE,
  row = TRUE,
  have_col_fnotes = FALSE,
  div_height = 1L,
  col_gap = 3L,
  has_rowlabels
)

Value

A list containing a vector of row numbers, broken up by page.

Arguments

pagdf

(data.frame)
a pagination info data.frame as created by either make_rows_df or make_cols_df.

rlpp

(numeric)
maximum number of row lines per page (not including header materials), including (re)printed header and context rows.

lpp_or_cpp

(numeric)
total maximum number of row lines or content (column-wise characters) per page (including header materials and context rows). This is only for informative results with verbose = TRUE. It will print NA if not specified by the pagination machinery.

context_lpp_or_cpp

(numeric)
total number of context row lines or content (column-wise characters) per page (including header materials). Uses NA if not specified by the pagination machinery and is only for informative results with verbose = TRUE.

min_siblings

(numeric)
minimum sibling rows which must appear on either side of pagination row for a mid-subtable split to be valid. Defaults to 2 for tables. It is automatically turned off (set to 0) for listings.

nosplitin

(character)
list of names of subtables where page breaks are not allowed, regardless of other considerations. Defaults to none.

verbose

(flag)
whether additional informative messages about the search for pagination breaks should be shown. Defaults to FALSE.

row

(flag)
whether pagination is happening in row space (TRUE, the default) or column space (FALSE).

have_col_fnotes

(flag)
whether the table-like object being rendered has column-associated referential footnotes.

div_height

(numeric(1))
the height of the divider line when the associated object is rendered. Defaults to 1.

col_gap

(numeric(1))
width of gap between columns, in same units as extent in pagdf (spaces under a particular font specification).

has_rowlabels

(logical(1))
whether the object being paginated has row labels.

Pagination Algorithm

Pagination is performed independently in the vertical and horizontal directions based solely on a pagination data frame, which includes the following information for each row/column:

• Number of lines/characters rendering the row will take after word-wrapping (self_extent)

• The indices (reprint_inds) and number of lines (par_extent) of the rows which act as context for the row

• The row's number of siblings and position within its siblings

Given lpp (cpp) is already adjusted for rendered elements which are not rows/columns and a data frame of pagination information, pagination is performed via the following algorithm with start = 1.

Core Pagination Algorithm:

1. Initial guess for pagination position is start + lpp (start + cpp)

2. While the guess is not a valid pagination position, and guess > start, decrement guess and repeat.

   • An error is thrown if all possible pagination positions between start and start + lpp (start + cpp) would be < start after decrementing

3. Retain pagination index

4. If pagination point was less than NROW(tt) (ncol(tt)), set start to pos + 1, and repeat steps (1) - (4).

Validating Pagination Position:

Given an (already adjusted) lpp or cpp value, a pagination is invalid if:

• The rows/columns on the page would take more than (adjusted) lpp lines/cpp characters to render including:

  • word-wrapping

  • (vertical only) context repetition

• (vertical only) footnote messages and/or section divider lines take up too many lines after rendering rows

• (vertical only) row is a label or content (row-group summary) row

• (vertical only) row at the pagination point has siblings, and it has less than min_siblings preceding or following siblings

• pagination would occur within a sub-table listed in nosplitin

Details

pab_indices_inner implements the core pagination algorithm (see below) for a single direction (vertical if row = TRUE (the default), horizontal otherwise) based on the pagination data frame and (already adjusted for non-body rows/columns) lines (or characters) per page.

Examples

mypgdf <- basic_pagdf(row.names(mtcars))

paginds <- pag_indices_inner(mypgdf, rlpp = 15, min_siblings = 0)
lapply(paginds, function(x) mtcars[x, ])