Merge pull request #6151 from Rdatatable/fifdoc

Update fifelse documentation to reflect evaluation behavior

Author: tdhock

man/fcase.Rd

@@ -11,6 +11,11 @@
 \item{...}{ A sequence consisting of logical condition (\code{when})-resulting value (\code{value}) \emph{pairs} in the following order \code{when1, value1, when2, value2, ..., whenN, valueN}. Logical conditions \code{when1, when2, ..., whenN} must all have the same length, type and attributes. Each \code{value} may either share length with \code{when} or be length 1. Please see Examples section for further details.}
 \item{default}{ Default return value, \code{NA} by default, for when all of the logical conditions \code{when1, when2, ..., whenN} are \code{FALSE} or missing for some entries. }
 }
+\details{
+\code{fcase} evaluates each when-value pair in order, until it finds a \code{when} that is \code{TRUE}. It then returns the corresponding \code{value}. During evaluation, \code{value} will be evaluated regardless of whether the corresponding \code{when} is \code{TRUE} or not, which means recursive calls should be placed in the last when-value pair, see \code{Examples}.
+
+\code{default} is always evaluated, regardless of whether it is returned or not.
+}
 \value{
   Vector with the same length as the logical conditions (\code{when}) in \code{...}, filled with the corresponding values (\code{value}) from \code{...}, or eventually \code{default}. Attributes of output values \code{value1, value2, ...valueN} in \code{...} are preserved.
 }
@@ -54,5 +59,13 @@ fcase(
 	x > 5L, 3L,
 	default = 5L
 )
+
+# fcase can be used for recursion, unlike fifelse
+# Recursive function to calculate the Greatest Common Divisor
+gcd_dt = function(x,y) {
+  r = x\%\%y
+  fcase(!r, y, r, gcd_dt(x, y)) # Recursive call must be in the last when-value pair
+}
+gcd_dt(10L, 1L)
 }
 \keyword{ data }

man/fifelse.Rd

@@ -15,12 +15,16 @@
 }
 \details{
 In contrast to \code{\link[base]{ifelse}} attributes are copied from the first non-\code{NA} argument to the output. This is useful when returning \code{Date}, \code{factor} or other classes.
+
+Unlike \code{\link[base]{ifelse}}, \code{fifelse} evaluates both \code{yes} and \code{no} arguments for type checking regardless of the result of \code{test}. This means that neither \code{yes} nor \code{no} should be recursive function calls. For recursion, use \code{fcase} instead.
 }
 \value{
 A vector of the same length as \code{test} and attributes as \code{yes}. Data values are taken from the values of \code{yes} and \code{no}, eventually \code{na}.
 }
 \seealso{
   \code{\link{fcoalesce}}
+
+  \code{\link{fcase}}
 }
 \examples{
 x = c(1:4, 3:2, 1:4)
@@ -37,5 +41,9 @@ fifelse(c(TRUE,FALSE,TRUE), yes, no)
 
 # Example of using the 'na' argument
 fifelse(test = c(-5L:5L < 0L, NA), yes = 1L, no = 0L, na = 2L)
+
+# Example showing both 'yes' and 'no' arguments are evaluated, unlike ifelse
+fifelse(1 == 1, print("yes"), print("no"))
+ifelse(1 == 1, print("yes"), print("no"))
 }
 \keyword{ data }