R/distance.R

In btskinner/rscorecard: A Method to Download Department of Education College Scorecard Data

#' Subset results to those within specified area around zip code.
#'
#' @param sccall Current list of parameters carried forward from prior
#'     functions in the chain (ignore)
#' @param zip A 5-digit zipcode
#' @param distance An integer distance in miles or kilometers
#' @param km A boolean value set to \code{TRUE} if distance should be
#'     in kilometers (default is \code{FALSE} for miles)
#' @section Note: Zip codes with leading zeros (Northeast) can be
#'     called either using a string (\code{"02111"}) or as a numeric
#'     (\code{02111}). R will drop the leading zero from the second
#'     version, but \code{sc_zip()} will add it back before the
#'     call. The shortened version without the leading zero may also
#'     be used (2111 and "2111" both become "02111"), but is not
#'     recommended for clarity.
#' @examples
#' \dontrun{
#' sc_zip(37203)
#' sc_zip(37203, 50)
#' sc_zip(37203, 50, km = TRUE)
#' sc_zip("02111")              # 1. Using string
#' sc_zip(02111)                # 2. Dropped leading zero will be added
#' sc_zip(2111)                 # 3. Will become "02111" (not recommended)
#' }

#' @export
sc_zip <- function(sccall, zip, distance = 25, km = FALSE) {
  suppressWarnings({
    ## check first argument
    confirm_chain(sccall)

    ## check second argument
    if (missing(zip)) {
      stop("Must provide a 5-digit zip code.", call. = FALSE)
    }

    if (suppressWarnings(is.na(as.numeric(zip)))) {
      stop("Zip code must contain only digits.", call. = FALSE)
    }

    if (nchar(zip) > 5) {
      stop("Zip codes cannot be longer than 5 digits.", call. = FALSE)
    }

    if (nchar(zip) < 5) {
      zip <- sprintf("%05d", zip)
      message(paste("Note: Zip code has fewer than 5 characters.",
                    "Leading zero(s) added."))
    }

    ## check third argument
    if (suppressWarnings(is.na(as.numeric(distance)))) {
      stop("Distance may only contain digits.", call. = FALSE)
    }

    ## add to stub
    stub <- "&_zip=" %+% zip %+% "&_distance=" %+% distance

    if (km) {
      sccall[["zip"]] <- stub %+% "km"
    } else {
      sccall[["zip"]] <- stub
    }

    sccall
  })

}