Streamlining method and function names

NAMESPACE

@@ -1,15 +1,18 @@
 # Generated by roxygen2: do not edit by hand
 
+export(CFcomplete)
 export(CFfactor)
 export(CFfactor_coverage)
 export(CFfactor_units)
 export(CFmonth_days)
 export(CFparse)
 export(CFtime)
 export(CFtimestamp)
+export(as_timestamp)
 export(calendar)
 export(definition)
 export(is_complete)
+export(month_days)
 export(offsets)
 export(origin)
 export(resolution)

R/CFfactor.R

@@ -55,7 +55,7 @@
 #'
 #' Creating factors for other periods is not supported by this function. Factors
 #' based on the timestamp information and not dependent on the calendar can
-#' trivially be constructed from the output of the [CFtimestamp()] function.
+#' trivially be constructed from the output of the [as_timestamp()] function.
 #'
 #' For non-epoch factors the attribute 'CFtime' of the result contains a CFtime
 #' instance that is valid for the result of applying the factor to a data set

R/CFformat.R

@@ -28,16 +28,16 @@
 #'
 #' @examples
 #' cf <- CFtime("hours since 2020-01-01", "standard", seq(0, 24, by = 0.25))
-#' CFtimestamp(cf, "timestamp")
+#' as_timestamp(cf, "timestamp")
 #'
 #' cf2 <- CFtime("days since 2002-01-21", "standard", 0:20)
-#' tail(CFtimestamp(cf2, asPOSIX = TRUE))
+#' tail(as_timestamp(cf2, asPOSIX = TRUE))
 #'
-#' tail(CFtimestamp(cf2))
+#' tail(as_timestamp(cf2))
 #'
-#' tail(CFtimestamp(cf2 + 1.5))
-CFtimestamp <- function(cf, format = NULL, asPOSIX = FALSE) {
-  if (!(methods::is(cf, "CFtime"))) stop("First argument to CFtimestamp must be an instance of the `CFtime` class")
+#' tail(as_timestamp(cf2 + 1.5))
+as_timestamp <- function(cf, format = NULL, asPOSIX = FALSE) {
+  if (!(methods::is(cf, "CFtime"))) stop("First argument to `as.timestamp()` must be an instance of the `CFtime` class")
   if (asPOSIX && cf@datum@cal_id != 1L) stop("Cannot make a POSIX timestamp on a non-standard calendar")
 
   time <- .offsets2time(cf@offsets, cf@datum)

R/CFtime-package.R

@@ -24,10 +24,10 @@
 #' * [`Compare`][CFtime-equivalent] two CFtime instances
 #' * [`Merge`][CFtime-merge] two CFtime instances
 #' * [`Append`][CFtime-append] additional time steps to a CFtime instance
-#' * [CFtimestamp()] and [format()]: Generate a vector of character or `POSIXct` timestamps from a CFtime instance
+#' * [as_timestamp()] and [format()]: Generate a vector of character or `POSIXct` timestamps from a CFtime instance
 #' * [range()]: Timestamps of the two endpoints in the time series
 #' * [is_complete()]: Does the CFtime instance have a complete time series between endpoints?
-#' * [CFmonth_days()]: How many days are there in a month using the CFtime calendar?
+#' * [month_days()]: How many days are there in a month using the CFtime calendar?
 #'
 #' **Factors and coverage**
 #' * [CFfactor()] and [cut()]: Create factors for different time periods

R/CFtime.R

@@ -154,7 +154,7 @@ resolution <- function(cf) cf@resolution
 #'
 #' @examples
 #' cf <- CFtime("days since 2024-01-01", "standard", seq(0.5, by = 1, length.out = 366))
-#' CFtimestamp(cf)[1:3]
+#' as_timestamp(cf)[1:3]
 #' bounds(cf) <- rbind(0:365, 1:366)
 #' bounds(cf)[, 1:3]
 #' bounds(cf, "%d-%b-%Y")[, 1:3]
@@ -201,7 +201,7 @@ setMethod("length", "CFtime", function(x) length(x@offsets))
 #' as.character(cf)
 setMethod("as.character", "CFtime", function(x) {
   if (length(x@offsets) > 0)
-    CFtimestamp(x)
+    as_timestamp(x)
 })
 
 setMethod("show", "CFtime", function(object) {
@@ -244,7 +244,7 @@ setMethod("show", "CFtime", function(object) {
 #' Week information, including weekday names, is not supported at all as a
 #' "week" is not defined for non-standard CF calendars and not generally useful
 #' for climate projection data. If you are working with observed data and want
-#' to get pretty week formats, use the [CFtimestamp()] function to generate
+#' to get pretty week formats, use the [as_timestamp()] function to generate
 #' `POSIXct` timestamps (observed data generally uses a standard calendar) and
 #' then use the [base::format()] function which supports the full set of
 #' specifiers.
@@ -264,7 +264,7 @@ setMethod("show", "CFtime", function(object) {
 #' format(cf, "%Y-%b")
 #'
 #' # Use system facilities on a standard calendar
-#' format(CFtimestamp(cf, asPOSIX = TRUE), "%A, %x")
+#' format(as_timestamp(cf, asPOSIX = TRUE), "%A, %x")
 #'
 setMethod("format", "CFtime", function(x, format) {
   if (!requireNamespace("stringr", quietly = TRUE))
@@ -419,7 +419,7 @@ setGeneric("indexOf", function(x, y, ...) standardGeneric("indexOf"), signature
 #'
 #' @examples
 #' cf <- CFtime("days since 2020-01-01", "360_day", 1440:1799 + 0.5)
-#' CFtimestamp(cf)[1:3]
+#' as_timestamp(cf)[1:3]
 #' x <- c("2024-01-01", "2024-01-02", "2024-01-03")
 #' indexOf(x, cf)
 #' indexOf(x, cf, method = "linear")

R/CFutils.R

@@ -23,16 +23,16 @@
 #' @examples
 #' dates <- c("2021-11-27", "2021-12-10", "2022-01-14", "2022-02-18")
 #' cf <- CFtime("days since 1850-01-01", "standard")
-#' CFmonth_days(cf, dates)
+#' month_days(cf, dates)
 #'
 #' cf <- CFtime("days since 1850-01-01", "360_day")
-#' CFmonth_days(cf, dates)
+#' month_days(cf, dates)
 #'
 #' cf <- CFtime("days since 1850-01-01", "all_leap")
-#' CFmonth_days(cf, dates)
+#' month_days(cf, dates)
 #'
-#' CFmonth_days(cf)
-CFmonth_days <- function(cf, x = NULL) {
+#' month_days(cf)
+month_days <- function(cf, x = NULL) {
   stopifnot(methods::is(cf, "CFtime"))
   cal_id <- cf@datum@cal_id
 

R/deprecated.R

@@ -0,0 +1,46 @@
+#' @name deprecated_functions
+#' @title Deprecated functions
+#'
+#' @description
+#' These functions are deprecated and should no longer be used in new code. The
+#' below table gives the replacement function to use instead. The function
+#' arguments of the replacement function are the same as those of the deprecated
+#' function if no arguments are given in the table.
+#'
+#' | **Deprecated function** | **Replacement function** |
+#' | ------------------- | -------------------- |
+#' | CFcomplete()        | [is_complete()]      |
+#' | CFmonth_days()      | [month_days()]       |
+#' | CFrange()           | [range()]            |
+#' | CFsubset()          | [slab()]             |
+#' | CFtimestamp()       | [as_timestamp()]     |
+#'
+#' @param cf,x,format,asPOSIX See replacement functions.
+#'
+#' @returns See replacement functions.
+
+#' @rdname deprecated_functions
+#' @export
+CFtimestamp <- function(cf, format = NULL, asPOSIX = FALSE) {
+  warning("Function `CFtimestamp()` is deprecated. Use `as_timestamp()` instead.")
+  as_timestamp(cf, format, asPOSIX)
+}
+
+#' @rdname deprecated_functions
+#' @export
+CFmonth_days <- function(cf, x = NULL) {
+  warning("Function `CFmonth_days()` is deprecated. Use `month_days()` instead.")
+  month_days(cf, x)
+}
+
+#' @rdname deprecated_functions
+#' @export
+CFcomplete <- function(x) {
+  warning("Function `CFcomplete()` is deprecated. Use `is_complete()` instead.")
+  is_complete(x)
+}
+
+CFsubset <- function(x, extremes) {
+  warning("Function `CFsubset()` is deprecated. Use `slab()` instead.")
+  slab(x, extremes)
+}

README.Rmd

@@ -32,7 +32,7 @@ library(CFtime)
 as.Date("1949-12-01") + 43289
 
 # CFtime calculation on a "360_day" calendar
-CFtimestamp(CFtime("days since 1949-12-01", "360_day", 43289))
+as_timestamp(CFtime("days since 1949-12-01", "360_day", 43289))
 ```
 
 That's a difference of nearly 21 months! (And yes, 30 February is a valid date on a `360_day` calendar.)
@@ -136,7 +136,7 @@ nc_close(nc2041)
 nc_close(nc2046)
 
 # Optionally - Set the time dimension to the timestamps from the time object
-dimnames(pr)[[3]] <- CFtimestamp(time)
+dimnames(pr)[[3]] <- as_timestamp(time)
 
 # Create the month factor from the time object
 f_month <- CFfactor(time, "month")
@@ -149,7 +149,7 @@ pr_month_time <- attr(f_month, "CFtime")
 # Now sum the daily data to monthly data
 # Dimensions 1 and 2 are longitude and latitude, the third dimension is time
 pr_month <- aperm(apply(pr, 1:2, tapply, f_month, sum), c(2, 3, 1))
-dimnames(pr_month)[[3]] <- CFtimestamp(pr_month_time)
+dimnames(pr_month)[[3]] <- as_timestamp(pr_month_time)
 
 ```
 

README.md

@@ -49,7 +49,7 @@ as.Date("1949-12-01") + 43289
 #> [1] "2068-06-08"
 
 # CFtime calculation on a "360_day" calendar
-CFtimestamp(CFtime("days since 1949-12-01", "360_day", 43289))
+as_timestamp(CFtime("days since 1949-12-01", "360_day", 43289))
 #> [1] "2070-02-30"
 ```
 
@@ -196,7 +196,7 @@ nc_close(nc2041)
 nc_close(nc2046)
 
 # Optionally - Set the time dimension to the timestamps from the time object
-dimnames(pr)[[3]] <- CFtimestamp(time)
+dimnames(pr)[[3]] <- as_timestamp(time)
 
 # Create the month factor from the time object
 f_month <- CFfactor(time, "month")
@@ -209,7 +209,7 @@ pr_month_time <- attr(f_month, "CFtime")
 # Now sum the daily data to monthly data
 # Dimensions 1 and 2 are longitude and latitude, the third dimension is time
 pr_month <- aperm(apply(pr, 1:2, tapply, f_month, sum), c(2, 3, 1))
-dimnames(pr_month)[[3]] <- CFtimestamp(pr_month_time)
+dimnames(pr_month)[[3]] <- as_timestamp(pr_month_time)
 ```
 
 ## Coverage