The cols_merge_range() function is a specialized variant of the cols_merge() function. It operates by taking a two columns that constitute a range of values (col_begin and col_end) and merges them into a single column. What results is a column containing both values separated by a long dash (e.g., 12.0 — 20.0). The column specified in col_end is dropped from the output table.

cols_merge_range(data, col_begin, col_end, sep = "---")

## Arguments

data A table object that is created using the gt() function. A column that contains values for the start of the range. A column that contains values for the end of the range. The separator text that indicates the values are ranged.

## Value

An object of class gt_tbl.

## Details

This function could be somewhat replicated using cols_merge(), however, cols_merge_range() employs the following specialized semantics for NA handling:

1. NAs in col_begin result in missing values for the merged column (e.g., NA + 20.0 = NA)

2. NAs in col_end (but not col_begin) result in a display of only the col_begin values only for the merged column (e.g., 12.0 + NA = 12.0)

3. NAs both in col_begin and col_end result in missing values for the merged column (e.g., NA + NA = NA)

Any resulting NA values in the col_begin column following the merge operation can be easily formatted using the fmt_missing() function.

This function is part of a set of three column-merging functions. The other two are the general cols_merge() function and the specialized cols_merge_uncert() function. These functions operate similarly, where the second column specified is dropped from the output table. For all of the cols_merge*() functions, column removal occurs late in the rendering lifecycle so those secondary columns are still usable as column references (e.g., inside expressions provided to rows in the fmt*() functions).

## Figures

Other column modification functions: cols_align, cols_hide, cols_label, cols_merge_uncert, cols_merge, cols_move_to_end, cols_move_to_start, cols_move, cols_split_delim

## Examples

# Use gtcars to create a gt table,
# keeping only the model, mpg_c,
# and mpg_h columns; merge the mpg
# columns together as a single range
# column (which is labeled as MPG,
# in italics)
tab_1 <-
gtcars %>%
dplyr::select(model, starts_with("mpg")) %>%
dplyr::slice(1:8) %>%
gt() %>%
cols_merge_range(
col_begin = vars(mpg_c),
col_end = vars(mpg_h)) %>%
cols_label(
mpg_c = md("*MPG*")
)