README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

library(fracture)
# remotes::install_github("GuangchuangYu/badger")
library(badger)
library(MASS)
library(fractional)
```

# fracture <img src="man/figures/logo.png?raw=TRUE" align="right" height="138" />

<!-- badges: start -->
`r badge_cran_release(color = "brightgreen")`
`r badge_lifecycle("stable")`
`r badge_license(color = "blueviolet")`
`r badge_github_actions(action = "R-CMD-check")`
[![](https://codecov.io/gh/rossellhayes/fracture/branch/main/graph/badge.svg)](https://app.codecov.io/gh/rossellhayes/fracture)
`r badge_dependencies()`
<!-- badges: end -->

Convert decimals to fractions in R

## Installation

You can install the released version of **fracture** from [CRAN](https://cran.r-project.org/package=fracture) with:

``` {r eval = FALSE}
install.packages("fracture")
```

or the development version from [GitHub](https://github.com/rossellhayes/fracture) with:

``` {r eval = FALSE}
# install.packages("remotes")
remotes::install_github("rossellhayes/fracture")
```

## Usage

### Convert decimals to a character vector of fractions

**fracture** converts decimals into fractions.

```{r}
fracture(0.5)

fracture((1:11) / 12)
```

### Math with `fracture`s

`fracture`s are implemented using an S3 class. This means we can perform mathematical operations on them like real fractions.

```{r}
fracture(0.25) * 2

fracture(0.25) + fracture(1/6)
```

### Stylish `fracture`s

`frac_style()` uses Unicode to provide stylish formatting for inline fractions.

```{r eval = FALSE}
`r frac_style(pi, mixed = TRUE, max_denom = 500)`
```

`r frac_style(pi, mixed = TRUE, max_denom = 500)`

### Arguments

Additional arguments help you get exactly the result you expect:

#### Set denominator

```{r}
fracture((1:12) / 12, denom = 100)
```

#### Common denominators

```{r}
fracture((1:12) / 12, common_denom = TRUE)
```

#### Base-10 denominators

```{r}
fracture(1 / (2:12), base_10 = TRUE)
```

#### Maximum denominators

```{r}
fracture(sqrt(1 / (1:12)), max_denom = 100)
```

#### Mixed fractions

```{r}
fracture((1:9) / 3, mixed = TRUE)
```

### Convert decimals to a fraction matrix

For more advanced work, you may prefer to work with a fraction matrix:

```{r}
frac_mat((1:11) / 12)
```

`frac_mat()` accepts all the same arguments as `fracture()`.

When mixed fractions are used, `frac_mat()` has three rows:

```{r}
frac_mat((1:9) / 3, mixed = TRUE, common_denom = TRUE)
```

### Just a fun example

Use **fracture** to find the best approximations of π for each maximum denominator.

```{r}
unique(purrr::map_chr(1:50000, ~ fracture(pi, max_denom = .x)))
```

Isn't is interesting that there's such a wide gap between `r frac_style(355/113)` and `r frac_style(103993/33102)`?

## Advantages `r emo::ji("rocket")`

**fracture** is implemented using optimized C++ with [**Rcpp**](https://www.rcpp.org/) and S3 methods.
This allows it to run faster than alternatives like [`MASS::fractions()`](https://cran.r-project.org/package=MASS) or [`fractional::fractional()`](https://cran.r-project.org/package=fractional).*

```{r include = FALSE}
x <- round(runif(1000, 1, 1e6)) / round(runif(1000, 1, 1e6))

# Performance with a single value
single_benchmark <- bench::mark(
  print(fracture(x[1])),
  print(MASS::fractions(x[1])),
  print(fractional::fractional(x[1])),
  check = FALSE, relative = TRUE, filter_gc = FALSE
)

vector_benchmark <- bench::mark(
  print(fracture(x)),
  print(MASS::fractions(x)),
  print(fractional::fractional(x)),
  check = FALSE, relative = TRUE, filter_gc = FALSE
)
```

```{r}
# Performance with a single value
single_benchmark

# Performance with a vector of length 1000
vector_benchmark
```

\* `fractional()` does not compute a decimal's fractional equivalent until it is printed.
Therefore, benchmarking the time to print provides a fairer test of the three packages' capabilities.

---

Hex sticker fonts are [Source Sans](https://github.com/adobe-fonts/source-sans) and [Hasklig](https://github.com/i-tu/Hasklig).

Please note that **fracture** is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.