3.2 Function Syntax

function is the reserved word in R that permits us to define functions. The general form of a function definition is as follows:

functionName <- function(parameter, parameter, ...) {
  Body of the Function ...
}

functionName is the variable that will refer to the function you define. Like any other identifier, it can contain letters, numbers, the dot and the underscore character, but is not permitted to begin with the dot followed by a number.

After the function reserved word we see a pair of matching parentheses. They contain the parameters of the function, which will be passed into the function as variables referred to by the parameter names.

The body of the function consists of one or more expressions that do the work of the function. Note that the body is enclosed with curly braces. This is only necessary, though, if the body consists of more than one expression. If the body had only one expression then that expression could appear without the braces, like this:

add3 <- function(x) x+3
add3(x = 5)

## [1] 8

add3(-7)

## [1] -4

In the add3() function above, x was a parameter. When the function is called the parameter is assigned a particular value called an argument. We see that add3() was called twice, once with an argument of 3 and again with an argument of -7. If the parameter is explicitly mentioned in the function call, then an equal-sign = separates the parameter and the argument. Note also that the parameter and = may be omitted if it is clear what parameter the argument will be matched to. In the case of add3 there is only one parameter x, so R knows that any value provided within the parentheses is to be assigned to x. R also knows to refer to the order of parameters within the function’s definition to determine which arguments go with which parameters. Thus, the following calls do the same thing:

manyCat(word = "Hello", n = 4)
manyCat(word = "Hello", 4)
manyCat("Hello", n = 4)
manyCat("Hello", 4)
manyCat(n = 4, word = "Hello")

On the other hand, the following would produce an error:

manyCat(4, "Hello")

## NAs introduced by coercion
## Error in rep(wordWithNewline, times = n) :
## invalid 'times' argument

If you don’t label your arguments with the parameters they are to match to, then you must at least write them in the order in which the parameters appear in the definition of the function.

In the definition of functions and in all calls to functions, commas must separate arguments. Thus the following would produce an error:

manyCat("Hello" 4)

## Error: unexpected numeric constant in "manyCat("Hello" 4"

If R cannot match all your arguments to a parameter it will throw an error;

manyCat("Hello", 4, 7)

## Error in manyCat("Hello", 4, 7) : unused argument (7)

You will have noticed by now that parentheses are essential when using a function. What would happen if we typed just the function’s name itself? Give it a try:

manyCat

## function(word, n) {
##   wordWithNewline <- paste(word, "\n", sep = "")
##   lines <- rep(wordWithNewline, times = n)
##   cat(lines, sep = "")
## }

What’s printed to the screen is the code that defines the function. The function itself is not called.

3.2.1 Practice Exercises

Consider the following function:

addThree <- function(n) {
  n +3
}

It adds three to any number you give it. Try it out:

addThree(n = 7)

## [1] 10

What, if anything, is wrong with the following code?
```
addThree(7)
```
What, if anything, is wrong with the following code?
```
addThree(n = 7, x = 5)
```
I’d like to add 3 to the number 15. What, if anything, is wrong with the following code?
```
addThree[15]
```

3.2.2 Solutions to the Practice Exercises

Nothing is wrong. You’ll get a result of 10. You don’t have to use the parameter name n when you call the function: R will figure out that you mean n to be 7.
There will be an error, because when the function was defined there was no parameter x. You can only give a function arguments for parameters that were included in its definition.
addThree is a function. The way you call it is to use parentheses around the arguments, like this: addThree(15). When you use brackets R will assume that you are trying to pick the third element out of a vector named addThree. When it can’t find such a vector, R will throw an error notifying you of that fact.