# WARNING - Generated by {fusen} from dev/flat_detect_chars_structure.Rmd: do not edit by hand

#' Detect character structure
#' Detect if values within a character variable match at least one of defined patterns
#'
#' @param vector Character. Input vector to detect pattern from
#' @param patterns Character. Patterns to detect within vector. Regex is supported
#' @param verbose Logical 1L. If TRUE, additional details related to the pattern detection are provided
#' @return Logical 1L. If verbose is set to TRUE, the function returns a list with the following elements in order: 
#'    - "Any defined structure" : Logical 1L. TRUE if the pattern is detected anywhere from the input vector
#'    - "Which" : Character. Unique values of input vector matching the defined patterns
#'    - "Where" : Integer. Indexes of values from input vector matching the defined patterns
#' @export
#'
#' @examples
#' detect_chars_structure(
#'   vector = c("ABCD1234", "4567EF", "89GHIJ10"), 
#'   patterns = "[:alpha:]{4}" # detect four consecutive alphabetic values
#' )
#'
#' detect_chars_structure(
#'   vector = c("ABCD1234", "4567EF", "89GHIJ10"), 
#'   patterns = "[:alpha:]{4}", 
#'   verbose = TRUE
#' )
detect_chars_structure <- function (vector, patterns, verbose = FALSE) {
  
  if (isFALSE(is.character(vector))) {
    stop("vector must be of type character")
  }
  
  uniques <- stats::na.omit(unique(as.character(vector)))
  detect <- stringr::str_detect(uniques, paste0(patterns, collapse = "|"))
  check <- isTRUE(any(detect))
  
  if (isFALSE(verbose)) {
    check
  } else {
    
    which <- unique(uniques[detect])
    where <- which(vector %in% which)
    
    list("Any defined structure" = check, 
         "Which" = which, 
         "Where" = where)
  }
}
