Introduction to theRefdate

Overview

theRefdate provides simple and fast date manipulation functions operating on character strings. By default the strings have the format "DD.MM.YYYY" (flavour "dmy"), exactly as in version 1.0.0. The package does not convert dates to a date class, which keeps it simple and fast.

flavour and setFlavour

A flavour is the date format the package works with. Three flavours exist:

Without any setting the flavour is "dmy", and every function returns the same results as in version 1.0.0. flavour() returns the active flavour:

flavour()
#> [1] "dmy"

setFlavour() selects another flavour for the whole R session. Call it once, at the start of a session or in the initialization of the code that uses the package. Calling it later with a different flavour gives a warning, because two formats in one session usually indicate a mistake. The old identifiers "LP" (= "dmy") and "VK" (= "iso") are still accepted.

setFlavour("iso")
jahr("2002-02-02")
#> [1] 2002
dateAddMonths("2002-02-02", 11)
#> [1] "2003-01-02"
setFlavour("dmy")
#> Warning: theRefdate: Flavour wechselt von 'iso' auf 'dmy' innerhalb der Sitzung

For a single call the argument format overrides the session flavour:

jahr("2002-02-02", format = "iso")
#> [1] 2002

Errors instead of NA

Input that is not a date in the active format stops with an error that names the argument, its class and value, and the expected format. This includes NA and the empty string, for which version 1.0.0 returned NA:

jahr(NA_character_)
#> Error: theRefdate: Argument 'datumstring' (Klasse 'character', Wert 'NA'): enthaelt keine Zahl, erwartet Format TT.MM.JJJJ
jahr("2002-02-02")   # ISO date while the flavour is "dmy"
#> Warning in jahr("2002-02-02"): NAs durch Umwandlung erzeugt
#> Error: theRefdate: Argument 'datumstring' (Klasse 'character', Wert '2002-02-02'): enthaelt keine Zahl, erwartet Format TT.MM.JJJJ

jahr

Extracts the year as a numeric value:

jahr("02.02.2002")
#> [1] 2002

monat

Extracts the month as a numeric value:

monat("14.06.1789")
#> [1] 6

tag

Extracts the day as a numeric value:

tag("03.02.2000")
#> [1] 3

dateDiff

Computes the difference between two dates. Returns a list with four elements: diffJ (years), diffM (months), diffDauer (duration as fraction of years), diffDauerM (total months):

result <- dateDiff("01.12.1999", "01.01.2000")
result$diffJ
#> [1] 0
result$diffM
#> [1] 1
result$diffDauer
#> [1] 0.08333333
result$diffDauerM
#> [1] 1

dateAddMonths

Adds or subtracts whole months from a date. The day is left unchanged and the year is written with four digits:

dateAddMonths("01.01.2000",   1)   # add 1 month
#> [1] "01.02.2000"
dateAddMonths("01.01.2000",  -1)   # subtract 1 month
#> [1] "01.12.1999"
dateAddMonths("01.01.2000",  12)   # add 1 year
#> [1] "01.01.2001"
dateAddMonths("01.01.2000", -13)   # subtract 13 months
#> [1] "01.12.1998"