---
title: "Getting started with toOrdinal"
author: "Damian W Betebenner"
date: "`r toOrdinal::toOrdinalDate()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with toOrdinal}
  %\VignetteEngine{knitr::rmarkdown}
  %\usepackage[utf8]{inputenc}
---

```{r include = FALSE}
library(toOrdinal)
is_html_output = function() {
  knitr::opts_knit$get("rmarkdown.pandoc.to")=="html"
}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "",
    prompt=TRUE,
    fig.dpi = 96
			)
if (is_html_output()) {
    options(width=1000)
}
```

# Introduction

The package **toOrdinal** contains a single function `toOrdinal` that converts a cardinal number (e.g., 9) into its ordinal counterpart (e.g., 9th).
Because such conversions are language specific, the conversions are specific to a supported language. At present, the package implements Dutch, English,
French, German, Spanish, and Swedish. For example,

* Dutch: toOrdinal(1, language="Dutch") returns '1ste'
* English: toOrdinal(1) returns '1st'
* German: toOrdinal(1, language="German") returns '1te'
* French: toOrdinal(1, language="French") returns '1re'
* Spanish: toOrdinal(1, language="Spanish") returns '1.er'
* Swedish: toOrdinal(1, language="Swedish") returns '1:a'


# Use

After [installing](https://centerforassessment.github.io/toOrdinal/#installation) the package from either CRAN or GitHub, it's simple to convert a cardinal to an ordinal number.

To convert cardinal to ordinal numbers in English (the default), supply the cardinal number to `toOrdinal`.

```{r}
toOrdinal(5)
```

Conversion in other languages are performed by supplying the appropriate language to the `language` argument:

```{r}
toOrdinal(5, language="Dutch")
toOrdinal(5, language="German")
toOrdinal(5, language="French")
toOrdinal(5, language="Spanish")
toOrdinal(5, language="Swedish")
```

Current languages supported include: English, German, French, Spanish, and Swedish.

Since Version 1.1, the function `toOrdinalDate` converts calendar dates to a long format, ordinal form.

```{r}
toOrdinalDate()
toOrdinalDate("2017-12-25")
```

If no argument is provided to `toOrdinalDate`, then the current date derived from `Sys.date()` is used to create the ordinal version of the calendar date.
If a date is supplied, then it must be supplied as a character string of the form "YYYY-MM-DD" that is then converted to the more formal date format. Like with the function `toOrdinal`
the potential exists for multiple language support with `toOrdinalDate`. However, the only language currently supported by `toOrdinalDate` is English.

## Examples

The first argument, `n`, is the cardinal number to be converted to an ordinal number:

```{r}
sapply(1:10, toOrdinal)
```



# Contributions & Requests

If you have contribution (for example, another language) or a feature request for the **toOrdinal** package, don't hesitate to write or set up an [issue on GitHub](https://github.com/CenterForAssessment/toOrdinal/issues). Current new features include the possiblity of converting cardinal numbers to ordinal words
(e.g., 8 to eighth).