add %||% to base

git-svn-id: https://svn.r-project.org/R/trunk@85410 00db46b3-68df-0310-9c12-caf00c1e9a41

Author: maechler

doc/NEWS.Rd

@@ -197,6 +197,11 @@
 
       \item New option \code{catch.script.errors} provides a documented way
       to catch errors and continue in non-interactive use.
+
+      \item \code{L \%||\% R} newly in base is an expressive idiom for the
+      \code{if(!is.null(L)) L else R} or \code{if(is.null(L)) R else L}
+      phrases.
+
     }
   }
 

src/library/base/R/utils.R

@@ -1,7 +1,7 @@
 #  File src/library/base/R/utils.R
 #  Part of the R package, https://www.R-project.org
 #
-#  Copyright (C) 1995-2021 The R Core Team
+#  Copyright (C) 1995-2023 The R Core Team
 #
 #  This program is free software; you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
@@ -16,6 +16,9 @@
 #  A copy of the GNU General Public License is available at
 #  https://www.R-project.org/Licenses/
 
+## A pearl from Ruby -> ggplot2 et al.
+`%||%` <- function(x, y) if(is.null(x)) y else x
+
 shQuote <- function(string, type = c("sh", "csh", "cmd", "cmd2"))
 {
     if(missing(type) && .Platform$OS.type == "windows") type <- "cmd"

src/library/base/man/Control.Rd

@@ -1,9 +1,10 @@
 % File src/library/base/man/Control.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2022 R Core Team
+% Copyright 1995-2023 R Core Team
 % Distributed under GPL 2 or later
 
 \name{Control}
+\title{Control Flow}
 \alias{Control}
 \alias{if}
 \alias{else}
@@ -13,7 +14,7 @@
 \alias{repeat}
 \alias{break}
 \alias{next}
-\title{Control Flow}
+\alias{\%||\%}
 \description{
   These are the basic control-flow constructs of the \R language.  They
   function in much the same way as control statements in any Algol-like
@@ -28,18 +29,20 @@ while(cond) expr
 repeat expr
 break
 next
+
+x \%||\% y
 }
 \arguments{
   \item{cond}{A length-one logical vector that is not \code{NA}.
     Other types are coerced to logical if possible, ignoring any class.
-    (Conditions of length greater than one are an error.) 
+    (Conditions of length greater than one are an error.)
   }
   \item{var}{A syntactical name for a variable.}
   \item{seq}{An expression evaluating to a vector (including a list and
     an \link{expression}) or to a \link{pairlist} or \code{NULL}.  A
     factor value will be coerced to a character vector.  This can be a
     long vector.}
-  \item{expr, cons.expr, alt.expr}{
+  \item{expr, cons.expr, alt.expr, x, y}{
     An \emph{expression} in a formal sense.  This is either a
     simple expression or a so-called \emph{compound expression}, usually
     of the form \code{\{ expr1 ; expr2 \}}.
@@ -68,6 +71,12 @@ next
   but this will not affect the next iteration.  When the loop terminates,
   \code{var} remains as a variable containing its latest value.
 
+  \code{x \%||\% y} is a simple 1-line function, an idiomatic way to call
+  \preformatted{
+    if (is.null(x)) y else x
+                             # or equivalently, of course,
+    if(!is.null(x)) x else y }
+  Inspired by Ruby, it was first proposed by Hadley Wickham.
 }
 \value{
   \code{if} returns the value of the expression evaluated, or
@@ -101,6 +110,13 @@ for(n in c(2,5,10,20,50)) {
 }
 f <- factor(sample(letters[1:5], 10, replace = TRUE))
 for(i in unique(f)) print(i)
+
+res <- {}
+res \%||\% "alternative result"
+x <- head(x) \%||\% stop("parsed, but *not* evaluated..")
+
+res <- if(sum(x) > 7.5) mean(x) # may be NULL
+res \%||\% "sum(x) <= 7.5"
 }
 \keyword{programming}
 \keyword{iteration}

src/library/base/man/Logic.Rd

@@ -124,6 +124,9 @@ isFALSE(x)
 
   \code{\link{Syntax}} for operator precedence.
 
+  \code{L \link{\%||\%} R } which takes \code{L} if it is not \code{NULL},
+  and \code{R} otherwise.
+
   \code{\link{bitwAnd}} for bitwise versions for integer vectors.
 }
 \examples{

src/library/base/man/NULL.Rd

@@ -1,6 +1,6 @@
 % File src/library/base/man/NULL.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2022 R Core Team
+% Copyright 1995-2023 R Core Team
 % Distributed under GPL 2 or later
 
 \name{NULL}
@@ -53,6 +53,9 @@ is.null(x)
   \code{is.null} returns \code{TRUE} if its argument's value
   is \code{NULL} and \code{FALSE} otherwise.
 }
+\seealso{
+  \code{\link{\%||\%}}: \code{L \%||\% R} is equivalent to \code{ if(!is.null(L)) L else R }
+}
 \examples{
 is.null(list())     # FALSE (on purpose!)
 is.null(pairlist()) # TRUE

src/library/grDevices/R/device.R

@@ -49,8 +49,6 @@ deviceIsInteractive <- local({
 })
 
 
-`%||%` <- function(L,R) if(is.null(L)) R else L
-
 dev.list <- function()
 {
     n <- get0(".Devices") %||% list("null device")

src/library/stats/R/AIC.R

@@ -16,9 +16,6 @@
 #  A copy of the GNU General Public License is available at
 #  https://www.R-project.org/Licenses/
 
-## A pearl from ggplot2 et al.  NB: often needs '(..)' around RHS :   <lhs> %||% ( <rhs> )
-`%||%` <- function(L,R) if(is.null(L)) R else L
-
 
 #### Return the value of Akaike's Information Criterion
 ### originally from package nlne.

src/library/utils/R/str.R

@@ -1,7 +1,7 @@
 #  File src/library/utils/R/str.R
 #  Part of the R package, https://www.R-project.org
 #
-#  Copyright (C) 1995-2021 The R Core Team
+#  Copyright (C) 1995-2023 The R Core Team
 #
 #  This program is free software; you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by
@@ -16,9 +16,6 @@
 #  A copy of the GNU General Public License is available at
 #  https://www.R-project.org/Licenses/
 
-## A pearl from ggplot2 et al.  NB: often needs '(.)' :   <lhs> %||% ( <rhs> )
-## *not exported* [should rather be in 'base' than exported here]
-`%||%` <- function(L,R) if(is.null(L)) R else L
 
 ####------ str : show STRucture of an R object
 str <- function(object, ...) UseMethod("str")