Update fifelse documentation to reflect evaluation behavior

[joshhwuu]

Closes #4549

fifelse evaluates both yes and no arguments, regardless of the value of test. This makes it unfit for recursive functions as the evaluation will cause an infinite loop of calls.

Changed documentation to better reflect this behavior, along with a simple example to showcase the difference against base ifelse:

ifelse(1 == 1, print("yes"), print("no"))
# [1] "yes"
fifelse(1 == 1, print("yes"), print("no"))
# [1] "yes"
# [1] "no"

Also mentioned that fcase can be used instead for recursive calls. Does fcase documentation also need updating? I noticed that the when and value pair is evaluated, even if the when doesn't bind, which means:

gcd_dt <- function(x,y) {
  r <- x%%y;
  return(data.table::fcase(!r, y, r, gcd_dt(x, y)))
}

works, but

gcd_dt <- function(x,y) {
  r <- x%%y;
  return(data.table::fcase(!r, y, r, gcd_dt(x, y))) # (when value pair swapped)
}

doesn't, due to the same reason that fifelse doesn't.

[joshhwuu]

From R-CMD-Check:

  > # fcase can be used for recursion, unlike fifelse
  > gcd_dt <- function(x,y) {
  +   r <- x
  +   return(fcase(!r, y, r, gcd_dt(x, y))) # Recursive call must be in the last when-value pair
  + }
  > gcd_dt(10, 1)
  Error: evaluation nested too deeply: infinite recursion / options(expressions=)?
  Execution halted

not sure why mod operator isn't showing up here, will investigate

Edit:

Rd files have to use escaped percent symbols, otherwise it marks the beginning of an Rd comment

[tdhock]

i guess this is greatest common denominator? can you please add a comment to explain?

[tdhock]

looks good to me