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).
- The default character for the ready prompt is "> ", but
the default character for the continuation prompt is "+ ".
- On Windows, each line cannot contain more than 128 characters.
If you have a complicated expression, you might need to continue
the expression on more than one line.
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
}
# ...
}