validate_fys_permitted: Verifying validity of financial years

In fy: Utilities for Financial Years

Verifying validity of financial years

Description

Many functions expect financial years. Determining that they are validly entered is often quite computationally costly, relative to the core calculations. These internal functions provide mechanisms to check validity quickly, while still providing clear, accurate error messages.

Usage

validate_fys_permitted(
  to_verify,
  permitted_fys = NULL,
  min.yr = NULL,
  max.yr = NULL,
  deparsed = deparse(substitute(to_verify)),
  allow.projection = TRUE,
  earliest_permitted_financial_year = "earliest permitted financial year",
  latest_permitted_financial_year = "latest permitted financial year",
  .retain_fmatches = FALSE
)

Arguments

to_verify	A user-provided value, purporting to be character vector of financial years.
permitted_fys	A character vector of valid financial years.
min.yr, max.yr	Integers specifying the range of to_verify. If NULL, no restriction on the upper or lower bound of the range.
deparsed	A string indicating the argument that the user provided. Should generally be provided explicitly as the default is unlikely to be user-friendly.
allow.projection	If FALSE emit a different error message.
earliest_permitted_financial_year, latest_permitted_financial_year	Text for earliest/latest permitted financial year when min.yr/max.yr condition is violated.
.retain_fmatches	If TRUE, the function may retain an attribute fy_fmatches an integer vector of the matches against the financial years "1900-01" to "2099-00". A trade-off between memory and runtime from not recalculating matches.

Details

The preferred form is "2012-13", and this function returns all elements of to_verify in this form. That is, it does not preserve the input form.

Other forms that are recognized (and converted) are:

• "201213"

• "2012 13"

• "2012\u201113"

• "2012\u201213"

• "2012\u201313"

• "2012\u201413"

• "2012-2013"

Value

If to_verify contains valid financial years they are returned all in the form 2013-14. If they were already in that form, they obtain the following attributes:

fy_all_fy

TRUE if all the financial years are valid.

fy_min_yr

An integer, the earliest year ending in to_verify.

fy_max_yr

An integer, the latest year ending in to_verify.

fy_fmatches

An integer vector, the matches with the prebuilt financial years.

Benchmarks

 x <- rep_len(yr2fy(2004L), 1e9)
 bench::system_time(validate_fys_permitted(x))
 #> process    real
 #>  3.578s  3.576s
 x <- rep_len(yr2fy(1980:2016), 1e9)

 bench::system_time(validate_fys_permitted(x))
 #> process    real
 #>  3.766s  3.753s

fy documentation built on Sept. 12, 2023, 9:06 a.m.