Merge pull request #4 from rich-iannone/v0.2.0-rc

v0.2.0 Release Candidate

.Rbuildignore

@@ -2,13 +2,14 @@
 ^\.Rproj\.user$
 ^LICENSE\.md$
 ^README\.Rmd$
+^README\.md$
 ^index\.md$
-^CODE_OF_CONDUCT\.md$
-^data-raw$
+^\.github$
 ^_pkgdown\.yml$
-^docs$
-^pkgdown$
 ^codecov\.yml$
-^\.github$
+^data-raw$
+^pkgdown$
+^docs$
+man/figures/
 tests/testthat/test-fdf_ftf.R
 tests/testthat/test-standard_date_time.R

DESCRIPTION

@@ -1,17 +1,18 @@
 Type: Package
 Package: bigD
 Title: Flexibly Format Dates and Times to a Given Locale
-Version: 0.1.0.9000
+Version: 0.2.0
 Authors@R: person("Richard", "Iannone", , "riannone@me.com", c("aut", "cre"),
                   comment = c(ORCID = "0000-0003-3925-190X"))
 Description: Format dates and times flexibly and to whichever locales
-    make sense. Parses dates, times, and datetimes in various formats (including
-    string-based ISO-8601 constructions). The formatting syntax is quite
-    powerful; time zones in the input can be expressed in multiple ways and
-    there are many options for formatting time zones in the output as well.
-    Several of the provided helper functions allow for automatic generation of
-    locale-aware formatting patterns based on date/time skeleton formats and
-    standardized date/time formats with variable specificity.
+    make sense. Parses dates, times, and date-times in various formats
+    (including string-based ISO 8601 constructions). The formatting syntax gives
+    the user many options for formatting the date and time output in a precise
+    manner. Time zones in the input can be expressed in multiple ways and there
+    are many options for formatting time zones in the output as well. Several of
+    the provided helper functions allow for automatic generation of locale-aware
+    formatting patterns based on date/time skeleton formats and standardized
+    date/time formats with varying specificity.
 License: MIT + file LICENSE
 URL: https://github.com/rich-iannone/bigD
 BugReports: https://github.com/rich-iannone/bigD/issues

NAMESPACE

@@ -3,12 +3,15 @@
 export(fdt)
 export(fdt_locales_lst)
 export(fdt_locales_vec)
+export(first_day_of_week)
 export(flex_d_lst)
 export(flex_d_vec)
 export(flex_t12_lst)
 export(flex_t12_vec)
 export(flex_t24_lst)
 export(flex_t24_vec)
+export(names_months)
+export(names_wkdays)
 export(standard_date)
 export(standard_date_time)
 export(standard_time)

NEWS.md

@@ -1 +1,3 @@
-# bigD 0.1.0.9000
+# bigD 0.2.0
+
+* New package with everything you need to format dates and times.

R/days_months.R

@@ -0,0 +1,213 @@
+#' Get a vector of all the short weekday names
+#'
+#' @description
+#' The `names_wkdays()` function produces a vector of all short weekday names
+#' used by the **bigD** package.
+#'
+#' @return
+#' A character vector of short weekday names.
+#'
+#' @examples
+#' # Let's get all the short weekday names with
+#' # the `names_wkdays()` function
+#' names_wkdays()
+#'
+#' @export
+names_wkdays <- function() {
+  c(
+    "sun", "mon", "tue", "wed", "thu", "fri", "sat"
+  )
+}
+
+#' Get a vector of all the short month names
+#'
+#' @description
+#' The `names_months()` function produces a vector of all short month names
+#' used by the **bigD** package.
+#'
+#' @return
+#' A character vector of short month names.
+#'
+#' @examples
+#' # Let's get all the short month names with
+#' # the `names_months()` function
+#' names_months()
+#'
+#' @export
+names_months <- function() {
+  c(
+    "jan", "feb", "mar", "apr", "may", "jun",
+    "jul", "aug", "sep", "oct", "nov", "dec"
+  )
+}
+
+#' Get a named vector of all first-day-of-the-week names for different regions
+#'
+#' @description
+#' The `names_months()` function produces a vector of all short month names
+#' used by the **bigD** package.
+#'
+#' @return
+#' A character vector of short month names.
+#'
+#' @examples
+#' # Let's get a vector of regions where the
+#' # first day of the week is Saturday
+#' names(first_day_of_week()[first_day_of_week() == "sat"])
+#'
+#' @export
+first_day_of_week <- function() {
+  c(
+    "001" = "mon",
+    "AD" = "mon",
+    "AE" = "sat",
+    "AF" = "sat",
+    "AG" = "sun",
+    "AI" = "mon",
+    "AL" = "mon",
+    "AM" = "mon",
+    "AN" = "mon",
+    "AR" = "mon",
+    "AS" = "sun",
+    "AT" = "mon",
+    "AU" = "mon",
+    "AX" = "mon",
+    "AZ" = "mon",
+    "BA" = "mon",
+    "BD" = "sun",
+    "BE" = "mon",
+    "BG" = "mon",
+    "BH" = "sat",
+    "BM" = "mon",
+    "BN" = "mon",
+    "BR" = "sun",
+    "BS" = "sun",
+    "BT" = "sun",
+    "BW" = "sun",
+    "BY" = "mon",
+    "BZ" = "sun",
+    "CA" = "sun",
+    "CH" = "mon",
+    "CL" = "mon",
+    "CM" = "mon",
+    "CN" = "sun",
+    "CO" = "sun",
+    "CR" = "mon",
+    "CY" = "mon",
+    "CZ" = "mon",
+    "DE" = "mon",
+    "DJ" = "sat",
+    "DK" = "mon",
+    "DM" = "sun",
+    "DO" = "sun",
+    "DZ" = "sat",
+    "EC" = "mon",
+    "EE" = "mon",
+    "EG" = "sat",
+    "ES" = "mon",
+    "ET" = "sun",
+    "FI" = "mon",
+    "FJ" = "mon",
+    "FO" = "mon",
+    "FR" = "mon",
+    "GB" = "mon",
+    "GE" = "mon",
+    "GF" = "mon",
+    "GP" = "mon",
+    "GR" = "mon",
+    "GT" = "sun",
+    "GU" = "sun",
+    "HK" = "sun",
+    "HN" = "sun",
+    "HR" = "mon",
+    "HU" = "mon",
+    "ID" = "sun",
+    "IE" = "mon",
+    "IL" = "sun",
+    "IN" = "sun",
+    "IQ" = "sat",
+    "IR" = "sat",
+    "IS" = "mon",
+    "IT" = "mon",
+    "JM" = "sun",
+    "JO" = "sat",
+    "JP" = "sun",
+    "KE" = "sun",
+    "KG" = "mon",
+    "KH" = "sun",
+    "KR" = "sun",
+    "KW" = "sat",
+    "KZ" = "mon",
+    "LA" = "sun",
+    "LB" = "mon",
+    "LI" = "mon",
+    "LK" = "mon",
+    "LT" = "mon",
+    "LU" = "mon",
+    "LV" = "mon",
+    "LY" = "sat",
+    "MC" = "mon",
+    "MD" = "mon",
+    "ME" = "mon",
+    "MH" = "sun",
+    "MK" = "mon",
+    "MM" = "sun",
+    "MN" = "mon",
+    "MO" = "sun",
+    "MQ" = "mon",
+    "MT" = "sun",
+    "MV" = "fri",
+    "MX" = "sun",
+    "MY" = "mon",
+    "MZ" = "sun",
+    "NI" = "sun",
+    "NL" = "mon",
+    "NO" = "mon",
+    "NP" = "sun",
+    "NZ" = "mon",
+    "OM" = "sat",
+    "PA" = "sun",
+    "PE" = "sun",
+    "PH" = "sun",
+    "PK" = "sun",
+    "PL" = "mon",
+    "PR" = "sun",
+    "PT" = "sun",
+    "PY" = "sun",
+    "QA" = "sat",
+    "RE" = "mon",
+    "RO" = "mon",
+    "RS" = "mon",
+    "RU" = "mon",
+    "SA" = "sun",
+    "SD" = "sat",
+    "SE" = "mon",
+    "SG" = "sun",
+    "SI" = "mon",
+    "SK" = "mon",
+    "SM" = "mon",
+    "SV" = "sun",
+    "SY" = "sat",
+    "TH" = "sun",
+    "TJ" = "mon",
+    "TM" = "mon",
+    "TR" = "mon",
+    "TT" = "sun",
+    "TW" = "sun",
+    "UA" = "mon",
+    "UM" = "sun",
+    "US" = "sun",
+    "UY" = "mon",
+    "UZ" = "mon",
+    "VA" = "mon",
+    "VE" = "sun",
+    "VI" = "sun",
+    "VN" = "mon",
+    "WS" = "sun",
+    "XK" = "mon",
+    "YE" = "sun",
+    "ZA" = "sun",
+    "ZW" = "sun"
+  )
+}
+

R/dt_formatters.R

@@ -707,7 +707,7 @@ dt_E <- function(input, locale = NULL) {
   cldr_dates_bigd(
     locale = locale,
     element = dates_elements_bigd$days_standalone_abbrev
-  )[[cldr_wkdays()[dow]]]
+  )[[names_wkdays()[dow]]]
 }
 
 # Day of Week Name // wide ("Tuesday")
@@ -718,7 +718,7 @@ dt_EEEE <- function(input, locale = NULL) {
   cldr_dates_bigd(
     locale = locale,
     element = dates_elements_bigd$days_standalone_wide
-  )[[cldr_wkdays()[dow]]]
+  )[[names_wkdays()[dow]]]
 }
 
 # Day of Week Name // narrow ("T")
@@ -729,7 +729,7 @@ dt_EEEEE <- function(input, locale = NULL) {
   cldr_dates_bigd(
     locale = locale,
     element = dates_elements_bigd$days_standalone_narrow
-  )[[cldr_wkdays()[dow]]]
+  )[[names_wkdays()[dow]]]
 }
 
 # Day of Week Name // short ("Tu")
@@ -740,7 +740,7 @@ dt_EEEEEE <- function(input, locale = NULL) {
   cldr_dates_bigd(
     locale = locale,
     element = dates_elements_bigd$days_standalone_short
-  )[[cldr_wkdays()[dow]]]
+  )[[names_wkdays()[dow]]]
 }
 
 # Local Day of Week Name/Number // 1 digit
@@ -844,23 +844,23 @@ dt_a <- function(input, locale = NULL) {
   cldr_dates_bigd(
     locale = locale,
     element = dates_elements_bigd$dayperiods_format_abbrev
-  )[[format(input, format = "%p")]]
+  )[[tolower(format(input, format = "%p"))]]
 }
 
 # Period: am, pm // wide
 dt_aaaa <- function(input, locale = NULL) {
   cldr_dates_bigd(
     locale = locale,
     element = dates_elements_bigd$dayperiods_format_wide
-  )[[format(input, format = "%p")]]
+  )[[tolower(format(input, format = "%p"))]]
 }
 
 # Period: am, pm // narrow
 dt_aaaaa <- function(input, locale = NULL) {
   cldr_dates_bigd(
     locale = locale,
     element = dates_elements_bigd$dayperiods_format_narrow
-  )[[format(input, format = "%p")]]
+  )[[tolower(format(input, format = "%p"))]]
 }
 
 # Period: am, pm, noon, midnight // abbreviated (b..bbb)

R/fdt.R

@@ -457,15 +457,21 @@
 #'   `POSIXct` objects. Refer to the *Valid Input Values* section for more
 #'   information.
 #' @param format The formatting string to apply to all `input` values. If not
-#'   provided, the inputs will be formatted to ISO 8601 datetime strings.
+#'   provided, the inputs will be formatted to ISO 8601 datetime strings. The
+#'   *Date/Time Format Syntax* section has detailed information on how to create
+#'   a formatting string.
 #' @param use_tz A tzid (e.g., `"America/New_York"`) time-zone designation for
 #'   precise formatting of related outputs. This overrides any time zone
-#'   information available in string-based input values and is applied to all
-#'   vector components.
+#'   information available in `character`-based input values and is applied to
+#'   all vector components.
 #' @param locale The output locale to use for formatting the input value
 #'   according to the specified locale's rules. Example locale names include
 #'   `"en"` for English (United States) and `"es-EC"` for Spanish (Ecuador). If
-#'   a locale isn't provided the `"en"` locale will be used.
+#'   a locale isn't provided the `"en"` locale will be used. The
+#'   [fdt_locales_vec] vector contains the valid locales and [fdt_locales_lst]
+#'   list provides an easy way to obtain a valid locale.
+#'
+#' @return A character vector of formatted dates, times, or datetimes.
 #'
 #' @section Examples:
 #'

R/fdt_locales.R

@@ -7,6 +7,16 @@
 #' @return
 #' A character vector of supported locale IDs.
 #'
+#' @examples
+#' # Let's get all the `ar` locales that exist
+#' # in the vector produced by `fdt_locales_vec()`
+#' fdt_locales_vec()[grep("^ar", fdt_locales_vec())]
+#'
+#' # Let's get all the locales that pertain to the
+#' # `CH` territory in the vector produced by
+#' # `fdt_locales_vec()`
+#' fdt_locales_vec()[grep("CH", fdt_locales_vec())]
+#'
 #' @export
 fdt_locales_vec <- function() {
   c(