What does the function invisible() do?

R help explains invisible() as "a function that returns a temporarily invisible copy of an object". I have difficulty understanding what invisible() is used for. Would you be able to explain what invisible() does and when this function can be useful?

I've seen that invisible() is almost always used in method functions for the print(). Here is one example:

### My Method function:
print.myPrint <- function(x, ...){
  print(unlist(x[1:2]))
  invisible(x)
}

x = list(v1 = c(1:5), v2 = c(-1:-5) )
class(x) = "myPrint"
print(x)

I was thinking that without invisible(x), I wouldn't be able to do assignment like:

a = print(x)

But it's actually not the case. So, I'd like to know what invisible() does, where it can be useful, and finally what it's role is in the method print function above?

Thank you very much for your help.

From ?invisible:

> Details: > > This function can be useful when it is desired to have functions > return values which can be assigned, but which do not print when > they are not assigned.

So you can assign the result, but it will not be printed if not assigned. It's often used in place of return. Your print.myPrint method only prints because you explicitly call print. The call to invisible(x) at the end of your function simply returns a copy of x.

If you didn't use invisible, x would also be printed if not assigned. For example:

R> print.myPrint <- function(x, ...){
+   print(unlist(x[1:2]))
+   return(x)
+ }
R> print(x)
v11 v12 v13 v14 v15 v21 v22 v23 v24 v25 
  1   2   3   4   5  -1  -2  -3  -4  -5 
v11 v12 v13 v14 v15 v21 v22 v23 v24 v25 
  1   2   3   4   5  -1  -2  -3  -4  -5 

While invisible() makes its content temporary invisible and is often used instead of return() it should rather be used in combination with return() and not as its replacement.

While return() will stop function execution and return the value put into it, invisible() will do no such thing. It only makes its content invisible for a while.

Consider the following two examples:

f1 <- function(x){
  if( x > 0 ){
     invisible("bigger than 0")
  }else{
     return("negative number")
  }
  "something went wrong"
}

result <- f1(1)

result
## [1] "something went wrong"



f2 <- function(x){
  if( x > 0 ){
     return(invisible("bigger than 0"))
  }else{
     return("negative number")
  }
}

result <- f2(1)

result
## [1] "bigger than 0"

Having circumvented invisible()'s pitfall we can have a look at its working:

f2(1)

The function does not print its return value due to the use of invisible(). It does however pass on the value as usual:

res <- f2(1)
res 
## [1] "bigger than 0"

invisible()'s use cases are e.g. to prevent function return values that would produce page after page of output or when a function is called for its side effect and the return value is e.g. only used to give further information ...

This excerpt from the Tidyverse Design Guide book explains why it might be useful to return an invisible value.

> If a function is called primarily for its side-effects, it should > invisibly return a useful output. If there’s no obvious output, return > the first argument. This makes it possible to use the function with in > a pipeline.

https://design.tidyverse.org/out-invisible.html