durationy: Create a 'durationy' from an annual duration

In datey: Exact Date and Duration Arithmetic on an Annual Grid

Create a durationy from an annual duration

Description

durationy() to create a durationy from the following types:

• integer. The value is interpreted as the specified number of years.

• double. The value is interpreted as the specified number of years, rounded to fixed precision of a durationy. This means that durationy(0.5) is precise but durationy(0.01) is not.

• datey_interval. The duration of the interval provided it is proper (i.e. start <= end). If the interval is improper then the result is NA_durationy_. When x is a datey_interval then x$duration is identical to durationy(x). (strict is ignored.)

• character. Valid text is of the form ⁠[S]...Y[.F...][ U...]⁠ where:

  • ⁠[S]⁠ is an optional plus or a minus sign, i.e. one of '+' (U+002B), true minus (U+2212) or ASCII hyphen-minus '-' (U+002D).

  • ...Y is number of whole years (leading zeros allowed).

  • ⁠[.F...]⁠ is an optional fractional part of year, including '.' to represent the decimal point.

  • ⁠[ U...]⁠ is the unit name for one year preceded by a space if the unit name is not blank. The unit name cannot be longer than 20 UTF-8 bytes or contain control characters.

  If blank_is_NA is TRUE then blanks are treated as NA. If strict is TRUE (the default) then non-compliant text will stop execution. If the text is NA then NA is returned. This is the same format as produced by as.character.durationy().

• durationy. Value is passed through unchanged.

NA arguments of the appropriate type result in NA_durationy_ – they do not stop execution (regardless of strict). Note that NA is logical and therefore it will cause an error.

Usage

durationy(x, ...)

## Default S3 method:
durationy(x, ...)

## S3 method for class 'durationy'
durationy(x, ...)

## S3 method for class 'integer'
durationy(x, strict = TRUE, ...)

## S3 method for class 'double'
durationy(x, strict = TRUE, ...)

## S3 method for class 'datey_interval'
durationy(x, ...)

## S3 method for class 'character'
durationy(x, strict = TRUE, blank_is_NA = FALSE, year_unit = "yr", ...)

Arguments

x	The argument to convert to a durationy.
...	Not used.
strict	How non-compliant non-NA x, e.g. years greater than 2000 in magnitude or invalid text, should be handled. If strict is TRUE – the default – then execution is stopped. If strict is FALSE then NA is returned.
blank_is_NA	Whether blanks should be treated as NA. Defaults to FALSE.
year_unit	The year unit name to expect. If not blank then the value is expected to be followed by a space and this unit text. Cannot be more than 20 characters (UTF-8 bytes) or contain control characters. Defaults to "yr".

Value

A vector of durationy.

See Also

datey, datey_interval, text_from_durationy, as_years_durationy, ops, is_NA, vignette("why-datey", package = "datey") for the annual-grid design, vignette("datey", package = "datey") for a worked introduction

Examples

durationy(1)    # 1 yr
durationy(0.5)  # 0.5 yr
durationy(-2.3) # -2.3 yr
durationy(2001 %to% 2002) # 1 yr
durationy(2002 %to% 2001) # `NA_durationy_` because interval is improper

# NA:
durationy(NA_real_)
try(durationy(NA)) # NA is logical, not numeric

# Invalid durations:
try(durationy(3000.1)) # default strict = TRUE
durationy(3000.1, strict = FALSE)

# Text:
durationy("10 yr")
durationy("+10 yr")
durationy("-10 yr")
durationy("10", year_unit = "")
durationy("10 a", year_unit = "a")

# Text round trips:
d <- durationy(1.234)
identical(d, durationy(as.character(d))) # TRUE

# Handling blank text:
try(durationy(""))
durationy("", blank_is_NA = TRUE)

# Invalid text:
try(durationy("abc"))
try(durationy("2000.000001 yr"))
durationy("abc", strict = FALSE) # NA
durationy("2000.000001 yr", strict = FALSE) # NA
durationy("2000.000000 yr") # This is valid

datey documentation built on July 14, 2026, 5:06 p.m.