R: Get string representation of cell references

to_string {cellranger} | R Documentation

## Get string representation of cell references

### 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")

[Package cellranger version 1.1.0 Index]