---
title: "Date types"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Date types}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

As you would expect with a genealogical data format, dates form a major part of information contained within it. Within `tidyged` 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 the `date_exact()` function:

```{r}
library(tidyged)

date_exact(1999, 7, 5)
date_exact(1956, 12, 8)
date_exact(2008, 4, 1)
```

## Calendar dates

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

```{r}
date_calendar(year = 1999, month = 4, day = 5)
date_calendar(year = 1999, month = 4)
date_calendar(year = 1999)
date_calendar(month = 4, day = 5)
```

English dates before 1752 were often given in dual format. This can be achieved using the `year_is_dual` parameter:

```{r}
date_calendar(year = 1745, month = 4, day = 5, year_is_dual = TRUE)
```

Years before the Common Era can be defined using the `year_is_bce` parameter:

```{r}
date_calendar(year = 105, year_is_bce = TRUE)
```

Note that only the Gregorian calendar is currently supported.

## Approximate dates

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

```{r}
date_calendar(year = 1999, month = 4, day = 5) |> date_approximated(about = TRUE)
date_calendar(year = 1999, month = 4, day = 5) |> date_approximated(calc = TRUE)
date_calendar(year = 1999, month = 4, day = 5) |> date_approximated(est = TRUE)
```


## Date periods

Date periods can take one or two `date_calendar()` objects:

```{r}
date_period(start_date = date_calendar(1956, 7, 26),
            end_date = date_calendar(1956, 9, 15))
date_period(start_date = date_calendar(1956, 7, 26))
date_period(end_date = date_calendar(1956, 9, 15))
```

Providing only one date gives a semi-infinite period.


## Date ranges

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

```{r}
date_range(start_date = date_calendar(1956, 7, 26),
           end_date = date_calendar(1956, 9, 15))
date_range(start_date = date_calendar(1956, 7, 26))
date_range(end_date = date_calendar(1956, 9, 15))
```

It's important to note that approximate dates cannot be used in date ranges or date periods. The GEDCOM specification does allow arbitrary "date phrases" enclosed in parentheses, but recommends these are added as notes instead. The `tidyged` package doesn't allow you to create date phrases (only as notes) but will accept them from imported files.

<p style="text-align: right;"><a href="https://jl5000.github.io/tidyged/articles/summarising.html">Next article: Summarising tidyged objects ></a></p>