Find colname by character string or pattern matching

find_colname(
  pattern,
  x,
  max = 1,
  index = FALSE,
  require_non_na = TRUE,
  verbose = FALSE,
  ...
)

Arguments

pattern

character vector containing text strings or regular expression patterns.

x

input data.frame or other R object that contains colnames.

max

integer maximum number of results to return.

index

logical indicating whether to return the column index as an integer vector. When index=FALSE it returns the matching colnames(x); when index=TRUE it returns the matching column numbers as an integer vector.

require_non_na

logical indicating whether to require the column to contain non-NA values, default is TRUE. The intent of this function is to find colnames whose data will match expectations, and when require_non_na is TRUE, this function will continue until it finds a column with non-NA values.

...

additional arguments are passed to jamba::provigrep().

Value

character vector with length max, or if no pattern match is found it returns NULL. Also if there are no colnames(x) then it returns NULL.

Details

This function is intended to help find a colname given a character vector of expected values or regular expression patterns. By default it returns the first matching value, but can return multiple if max=Inf.

If there are no colnames(x) then NULL is returned.

The order of operations:

  1. Match exact string.

  2. Match exact string in case-insensitive manner.

  3. Match the start of each string using jamba::provigrep().

  4. Match the end of each string using jamba::provigrep().

  5. Match each string using jamba::provigrep().

The results from the first successful operation is returned.

When there are duplicate colnames(x) only the first unique name is returned.