Date types

Introduction

As you would expect with a genealogical data format, dates form a major part of information contained within it. Within gedcomS7 there are a number of different date types that can be defined, and there is a helper function for each type to ensure it is formatted correctly.

Exact dates

Dates that occur on a specific defined date are defined using DateExact():

library(gedcomS7)

DateExact(1999, 7, 5)
#> Date:     5 JUL 1999
DateExact(1956, 12, 8)
#> Date:     8 DEC 1956
DateExact(2008, 4, 1)
#> Date:     1 APR 2008

As well as the GEDCOM formatted strings (printed above and also accessed through the @GEDCOM_STRING property), this date object can also be expressed as a date type:

DateExact(2008, 4, 1)@as_date
#> [1] "2008-04-01"

Calendar dates

Calendar dates are the most common type of date used. They can not only be used to create specific dates like DateExact(), they underpin the other date types described below. They can be created using DateGregorian():

DateGregorian(year = 1999, month = 4, day = 5)
#> Date:     5 APR 1999
DateGregorian(year = 1999, month = 4)
#> Date:     APR 1999
DateGregorian(year = 1999)
#> Date:     1999

Years before the Common Era can be defined using the bce parameter:

DateGregorian(year = 105, bce = TRUE)
#> Date:     105 BCE

No other calendars apart from the Gregorian calendar are supported by the package.

Approximate dates

Approximate dates (i.e. those expressing uncertainty) use the qualifiers ‘about’, ‘calculated’, or ‘estimated’ in conjunction with a DateGregorian() object:

DateGregorian(year = 1999, month = 4, day = 5) |> DateApprox(about = TRUE)
#> Date:     ABT 5 APR 1999
DateGregorian(year = 1999, month = 4, day = 5) |> DateApprox(calc = TRUE)
#> Date:     CAL 5 APR 1999
DateGregorian(year = 1999, month = 4, day = 5) |> DateApprox(est = TRUE)
#> Date:     EST 5 APR 1999

Date periods

Date periods can take one or two DateGregorian() objects:

DatePeriod(start_date = DateGregorian(1956, 7, 26),
           end_date = DateGregorian(1956, 9, 15))
#> Date:     FROM 26 JUL 1956 TO 15 SEP 1956
DatePeriod(start_date = DateGregorian(1956, 7, 26))
#> Date:     FROM 26 JUL 1956
DatePeriod(end_date = DateGregorian(1956, 9, 15))
#> Date:     TO 15 SEP 1956

Providing only one date gives a semi-infinite period.

Date ranges

Date ranges can be defined using DateRange(). Unlike DatePeriod(), they describe when an event occurred rather than a duration.

DateRange(start_date = DateGregorian(1956, 7, 26),
           end_date = DateGregorian(1956, 9, 15))
#> Date:     BET 26 JUL 1956 AND 15 SEP 1956
DateRange(start_date = DateGregorian(1956, 7, 26))
#> Date:     AFT 26 JUL 1956
DateRange(end_date = DateGregorian(1956, 9, 15))
#> Date:     BEF 15 SEP 1956

It’s important to note that approximate dates cannot be used in date ranges or date periods.

Date values

Date values can be defined with DateValue() and are a higher level of date expression than the elementary values given above. A calendar/approximate/range/period date can be used in conjunction with a date phrase (free text) and time. Instead of being single values, they are GEDCOM substructures:

my_date <- DateValue(
  date = DateGregorian(year = 1999, month = 4, day = 5),
  date_phrase = "Someone's birthday",
  time = Time(hour = 13, minute = 28, second = 57)
)

my_date
#> Date:     5 APR 1999 13:28:57Z (Someone's birthday)

my_date@GEDCOM
#> [1] "0 DATE 5 APR 1999"           "1 TIME 13:28:57Z"           
#> [3] "1 PHRASE Someone's birthday"

It’s also possible to only define a DateValue through a phrase:

DateValue(date = "", date_phrase = "March 14th")@GEDCOM
#> [1] "0 DATE"              "1 PHRASE March 14th"

A DateSorting() object is similar to DateValue() but it can only take Calendar dates as it is used for sorting.