easyformatr

Brandon Taylor

2016-07-13

Import the package. We will also make heavy usage of magrittr for chaining, dplyr for filtering, and knitr for printing.

library(easyformatr)
library(magrittr)
library(dplyr)
library(knitr)

Base Components

Let’s see what kind of componenets we can use in our time formats. This can be done by filtering the format info table.

Times

filter_info(type == "time" & component == "base")
code base
p am_pm
C century
F date
c datetime
d day
w day_of_week
j day_of_year
H hour
M minute
m month
n newline
S second
R time
s timestamp
Z timezone
V week_of_year
t tab
Y year

Numbers

filter_info(type == "number" & component == "base")
code base
i integer
o octal
x hex
f double
e scientific
g auto
a binary

Each of these base components can be used in a formats.

easy_format(year, month, day, integer, octal, double)
## %Y%m%d%.i%.o%.f

Mutant documentation

Each base component can be modified in special ways.

Time

Each time base can be modified in different ways. Let’s look at ways to modify second:

filter_info(type == "time" & component == "mutant" & base == "second")
code decimal digits
0S TRUE NA
0S0 NA 0
0S1 NA 1
0S2 NA 2
0S3 NA 3
0S4 NA 4
0S5 NA 5
0S6 NA 6

Along the top, you can see the names of flags and options. Flags change logical variables, and options change numeric variables.

Numbers

It is slightly easier to see modifiers for numbers because there is a fixed set.

Flags

filter_info(type == "number" & component == "flag")
code flag
- left_justify
+ always_sign
prefix_space
0 zero_pad
# hex_prefix
# always_decimal
# remove_zeros

Options

filter_info(type == "number" & component == "option")
option description
before_decimal number of digits before the decimal place
after_decimal number of digits after the decimal place
use_input sprintf input argument number

Transformations

To transform a base into a mutant, you must use a flag or option function. These functions take two arguments. The first is an object to modify:

easy_format(second %>% decimal)
## %0S

or a list of objects to modify:

easy_format(list(integer, 
                 double) %>% 
              always_decimal)
## %#.i%#.f

or even a nested list of objects to modify

easy_format(list(month, 
                 list(day,
                      minute) ) %>% 
            roman)
## %0m%0d%0M

In the case of times, flags or options that aren’t relevant to a particular base (that is, aren’t listed in the mutant table for a particular base) have no effect. Flags and options always have an effect on numbers.

easy_format(second %>% roman) ==
  easy_format(second)
## [1] TRUE

The second argument

The second argument of a transformation is what to change the value to.

Flags

For flags, the second argument defaults to true.

easy_format(second %>% decimal) == 
  easy_format(second %>% decimal(TRUE) )
## [1] TRUE

Flags can be undone by resetting the value to NA.

easy_format(second %>% 
              decimal %>% 
              decimal(NA) ) ==
  easy_format(second)
## [1] TRUE

Options

For options, this second value defaults to NA. So options will have no effect if no number is chosen.

easy_format(double %>% before_decimal) == 
  easy_format(double)
## [1] TRUE

Options can be turned of by resetting them to NA

easy_format(double %>% before_decimal(3) %>% before_decimal) == 
  easy_format(double)
## [1] TRUE

Errors

For times, it is possible to specify a mutant that has no corresponding code. For example,

easy_format(second %>%
              decimal %>%
              digits(1) ) 
## Error in function_list[[k]](value): 
## 
## base     decimal    digits
## -------  --------  -------
## second   TRUE            1
## 
##  has no corresponding code

Strings

Easy format leaves strings unchanged. However, percentage signs will be doubled.

easy_format("We are the 99%")
## We are the 99%%

This only happens once.

easy_format(easy_format("We are the 99%") )
## We are the 99%%

Modifications also leave strings unchanged.

easy_format(roman("I am Spartacus"))
## I am Spartacus

There is an optional sep argument that defaults to "", but can be changed.

easy_format("We", "are", "the 99%", sep = " ")
## We are the 99%%

More Info

For more information, codes can be looked up in the ?strptime and the ?sprintf documentation. Note that many formats are possible to build but will not work when used.