Syntax
The Structure of Expressions

Description

Describes using the engine and the structure of the language, including constructing functions and the precedence of operators, and how to use the engine.

Details

The following sections describe common tasks for constructing functions and expressions.
Assign a value to a name
Use the arrow ( <- ) assignment operator or use the assign function. (For more information, see Assignment.)
Use arithmetic binary operators
Place the binary operators between (the names of) two vectors. (For more information, see Arithmetic.)
Specify order of evaluation
Enclose an expression in parentheses to increase the precedence of the evaluation and force the function to evaluate this inner expression and return the value first. You can use this convention to enforce a given evaluation order in a complex expression. For example, aa * (bb+cc) ensures that bb+cc is evaluated before multiplying the sum by aa. For more information about the order of evaluation, see the precedence table in the section Formal Description.
Define a function
Use function followed by a set of parentheses that enclose the names of the arguments separated by commas. Specify default values in the name = default.value format. Include ... to allow passing an arbitrary number of arguments to the function. To construct a function call, use the following form:
  • Name of the function.
  • Opening parenthesis.
  • List of arguments (if any) where items in the argument list are separated by commas. (Arguments that are listed out of order must be in the name = value format.)
  • Closing parenthesis.
In general, you do not need to type argument names in full; you need type only sufficient characters to identify the argument uniquely. The exception is when an argument follows the dot-dot-dot construction (...) in the definition. In this case, the argument must be given in the name = value form, with the name specified exactly.
Subscript from vectors and arrays
Use vname[ expr ]. (For more information, see Subscript).
Extract portions of a list
Use lname[ expr ], lname[[ expr ]], or lname$fname.
  • Use single square brackets to return a sublist of lname.
  • Use double square brackets or the $ operator to return one component of lname. The advantage of the double bracket form is that you can extract components by their order in the list, as well as by their names. You do not need to specify the entire component name; you need only specify enough of the name's beginning to identify the component uniquely.
Treat more than one expression as a single expression
Place braces ( "{" and "}" ) around a set of expressions. This convention is useful when you write functions, or when you use if, for, while, or repeat expressions. Within braces, you should separate multiple expressions by carriage returns or semicolon (;) characters. An expression enclosed in a set of braces is evaluated by evaluating each of the elements in order, and then returning the value of the last one. An empty brace expression evaluates to NULL.
Continue a typed expression on subsequent lines
End each line where the line is obviously incomplete, with a trailing comma or operator, or with more opening parentheses than closing parentheses (implying more closing parentheses follow).
Place two or more expressions on a single line
Use a semi-colon (;) to separate each expression on a single line.
Control the flow in loops
Use next and break to control the flow in for, while, and repeat loops. When the engine encounters:
  • next, the next iteration starts immediately.
  • break, the loop terminates.
Exit a function
Use return( expr ) to exit a function.
Specify a string literal
Enclose the string literal in matching single (') or double (") quotation marks. You can escape the characters inside string literals by preceding them with the backslash (\) character. The backslash character is used as follows:
  • \n (line feed)
  • \t (tab)
  • \r (carriage return)
  • \b (backspace)
  • \ (backslash)
  • \ (backslash) followed by one to three octal digits represents the character with the corresponding octal representation in ASCII. Note that \0 is not allowed, because it is used as the string terminator character, as in the C language.
  • \ (backslash) followed by any other character causes the backslash to be ignored (for example, "\w" == "w"), following C language conventions.
Specify a raw string literal
An alternative way to specify a string literal is by using a "raw string literal", which makes it easier to specify strings including single and double quotes and backslashes. A raw string literal contains the following sequence of characters, in order:
  • The character "r" or "R".
  • A single or double quote character.
  • Zero or more dash characters.
  • An open parenthesis, bracket, or curly brace character.
  • Any number of characters, as long as they don't include the sequence of characters described below. The backslash character is not treated specially, but is just another single characer.
  • A close parenthesis, bracket, or curly brace character, matching the open character above.
  • Zero or more dashes, matching the number of dashes above.
  • A single or double quote character, matching the quote character above.

Examples: Both "r'(abc)'" and "R"--[abc]--"" specify the string "abc".

Execute an expression as a shell (Unix or DOS) command
Precede the expression with an exclamation point ("!") to execute an expression as a shell command. On Windows, for the DOS shell, you must use double backslashes in such expressions to represent one backslash.
Use an exclamation point in an expression to mean "not"
Use an exclamation point (!) in an expression to negate the expression. For example, to enter not equal to, you must use (!=). You can use braces to avoid having the exclamation point "!" as the first character in an expression.
Define an infix operator
Enclose any sequence of characters (except a new line character) with matching "%" characters.
Infix Operators By Precedence
The parser recognizes the following infix operators. They are listed in decreasing precedence. In the event of ties, evaluation is from left to right.
OPERATOR DESCRIPTION PRECEDENCE
$ component selection High
@ slot selection |
[, [[ subscripts, elements |
^ exponentiation |
- unary minus |
: sequence operator |
%anything% special operator |
*, / multiply, divide |
+, -, ? add, subtract, documentation |
< >, <=, >=, ==, != comparison |
! not |
&, |, &&, || and, or |
~ formulas |
<<- permanent assignment to working data V
<-, -> assignment Low
Expressions
Expressions are typed by the user, parsed, and then evaluated. The following rules define the expressions considered legal by the parser, and the mode of the corresponding object. You can use mode to inspect the mode of an object.
LITERALS MODE
number "numeric"
string "character"
name "name"
comment "comment"
complex "complex"
Function Definitions
function ( formals ) expr "function"
Calls
expr infix expr "call"
expr %anything% expr
unaryexpr
expr( arglist )
expr[ arglist ]
expr[[ arglist ]]
expr$ fname
Assignment
expr <- expr "<-"
expr -> expr "<-"
expr <<- expr "<<-"
Conditional
if( expr ) expr "if"
if( expr ) expr else expr "if"
Iteration
for( name in expr ) expr "for"
repeat expr "repeat"
while ( expr ) expr "while"
Flow
break "break"
next "next"
return ( expr ) "return"
( expr ) "("
{ exprlist } "{"
The additional syntactic forms introduced in the above rules are defined as follows:
exprlist: expr
exprlist ; expr
arglist: arg
arglist , arg
formals: empty
formal
formals , formal
arg: empty
expr
fname =
fname = expr
formal: name
...
name = expr
fname: name
string
Notice that the above rules are rules of syntax, and that there might be additional semantic rules that determine what expressions can be evaluated. In particular, the left side of an assignment expression is syntactically an expression, but only some of them, involving subscripts, attributes, and names, are allowable at the time of execution.
Numeric Literals
Numeric literals (numbers) are defined by the following rules:
numeric: integer
float
complex: numeric "i"
numeric [+\-] numeric "i"
name: (.|letter) (.|letter|digit)*
integer: digit+
exponent: "e" [+\-] integer
float: integer exponent
integer "." digit* exponent
"." integer exponent
A numeric followed by a capital "L" is taken to be an integer, unless it has a fractional part or is too large to be represented as an integer (in which case it is parsed as a floating-point numeric). If there is no trailing L, a sequence of digits is considered an integer (if not bigger than the largest possible integer) and other forms of numbers are considered floating point.
Names
Names are defined by:
name: (.|letter) (.|letter|digit)*
To use a variable name that does not fit this pattern, place backward single quotation marks before and after the variable name, as in `Graduation %` <- 81.2 or log(`2nd Dose`).
References
Becker, R. A., Chambers, J. M., and Wilks, A. R. 1988. The New S Language. Pacific Grove, CA: Wadsworth & Brooks/Cole Advanced Books and Software.
See Also
cat, factor, for, paste, parse, if, ifelse, assign, Assignment, Subscript, Methods, attr, attributes, dim, names, Arithmetic, Complex, Comparison
Examples
1.2e3  # twelve hundred 
1.2e-2  # twelve-thousandths 
3.9+4.5i # a complex number 
function(...) { 
	# ...
	for(i in 1:10) { 
		# ...
		if(test1) next # go immediately to the next iteration 
		                # if test1 is TRUE 
		if(test2) break # exit the for loop 
		                # if test2 is TRUE 
		if(test3) return(x) # exit the function with the value x 
		                # if test3 is TRUE 
	} 
        # ...
}
Package base version 6.1.4-13
Package Index