to_string: Get string representation of cell references

In cellranger: Translate Spreadsheet Cell Ranges to Rows and Columns

Description

Convert various representations of a cell reference to character

• to_string is not necessarily vectorized. For example, when the the input is of class ra_ref, it must of be of length one. However, to be honest, this will actually work for cell_addr, even when length > 1.

• to_string_v is guaranteed to be vectorized. In particular, input can be a cell_addr of length >= 1 or a list of ra_ref objects.

If either the row or column reference is relative, note that, in general, it's impossible to convert to an "A1" formatted string. We would have to know "relative to what?".

Usage

to_string(x, fo = c("R1C1", "A1"), strict = TRUE, sheet = NULL, ...)

to_string_v(x, fo = c("R1C1", "A1"), strict = TRUE, sheet = NULL, ...)

## S3 method for class 'ra_ref'
to_string(x, fo = c("R1C1", "A1"), strict = TRUE,
  sheet = NULL, ...)

## S3 method for class 'list'
to_string_v(x, fo = c("R1C1", "A1"), strict = TRUE,
  sheet = NULL, ...)

## S3 method for class 'cell_addr'
to_string(x, fo = c("R1C1", "A1"), strict = TRUE,
  sheet = FALSE, ...)

## S3 method for class 'cell_addr'
to_string_v(x, fo = c("R1C1", "A1"), strict = TRUE,
  sheet = FALSE, ...)

Arguments

x	a suitable representation of a cell or cell area reference: a single ra_ref object or a list of them or a cell_addr object
fo	either "R1C1" (the default) or "A1" specifying the cell reference format; in many contexts, it can be inferred and is optional
strict	logical, affects reading and writing of A1 formatted cell references. When strict = TRUE, references must be declared absolute through the use of dollar signs, e.g., $A$1, for parsing. When making a string, strict = TRUE requests dollar signs for absolute reference. When strict = FALSE, pure relative reference strings will be interpreted as absolute, i.e. A1 and $A$1 are treated the same. When making a string, strict = FALSE will cause dollars signs to be omitted in the reference string.
sheet	logical, indicating whether to include worksheet name; if NULL, worksheet is included if worksheet name is not NA
...	further arguments passed to or from other methods

Value

a character vector

Examples

## exactly one ra_ref --> string
to_string(ra_ref())
to_string(ra_ref(), fo = "A1")
to_string(ra_ref(), fo = "A1", strict = FALSE)
to_string(ra_ref(row_ref = 3, col_ref = 2))
to_string(ra_ref(row_ref = 3, col_ref = 2, sheet = "helloooo"))
(mixed_ref <- ra_ref(row_ref = 10, row_abs = FALSE, col_ref = 3))
to_string(mixed_ref)

## this will raise warning and generate NA, because row reference is
## relative and format is A1
to_string(mixed_ref, fo = "A1")

## a list of ra_ref's --> character vector
ra_ref_list <-
  list(ra_ref(), ra_ref(2, TRUE, 5, TRUE), ra_ref(2, FALSE, 5, TRUE))
to_string_v(ra_ref_list)

## cell_addr --> string
(ca <- cell_addr(3, 8))
to_string(ca)
to_string(ca, fo = "A1")

(ca <- cell_addr(1:4, 3))
to_string(ca)
to_string(ca, fo = "A1")
## explicitly go from cell_addr, length > 1 --> character vector
(ca <- cell_addr(1:4, 3))
to_string_v(ca)
to_string_v(ca, fo = "A1")

Example output

[1] "R1C1"
[1] "$A$1"
[1] "A1"
[1] "R3C2"
[1] "helloooo!R3C2"
<ra_ref>
   row: 10 (rel)
   col: 3 (abs)
 R[10]C3
[1] "R[10]C3"
[1] NA
Warning message:
Only absolute references can be converted to an A1 formatted string ... NAs generated 
[1] "R1C1"   "R2C5"   "R[2]C5"
<cell_addr: 1 cells>
# A tibble: 1 x 2
    row   col
  <int> <int>
1     3     8

[1] "R3C8"
[1] "$H$3"
<cell_addr: 4 cells>
# A tibble: 4 x 2
    row   col
  <int> <int>
1     1     3
2     2     3
3     3     3
4     4     3

[1] "R1C3" "R2C3" "R3C3" "R4C3"
[1] "$C$1" "$C$2" "$C$3" "$C$4"
<cell_addr: 4 cells>
# A tibble: 4 x 2
    row   col
  <int> <int>
1     1     3
2     2     3
3     3     3
4     4     3

[1] "R1C3" "R2C3" "R3C3" "R4C3"
[1] "$C$1" "$C$2" "$C$3" "$C$4"

cellranger documentation built on May 2, 2019, 11:26 a.m.