Functions

This section documents all available functions in alphabetical order (except for the short addressing/value fetching functions, which are listed together at the beginning). The functions are described in a C-like notation; you don't have to write the types when you use the function in a formula. For example, use @(0,0,0), not @(int 0, int 0, int 0). If no type is given for the result of a function, it means the result type depends on the arguments. Brackets mark optional arguments.

@([location l,][int x][,[int y][,[int z]]])

returns the value of the cell at the specified location. If any of x, y or z is specified, that value overrides the corresponding coordinate of the given location, which defaults to the location of the current cell if it is omitted.

location &([location l,][int x][, [int y][, [int z]]])

the arguments are interpreted in exactly the same way as for @(), but this fuction returns the location, not the value of the cell at that location. So note for example that a bare & with no arguments (with or without parentheses) evaluates to the location of the current cell.

D([location l,][int x][,[int y][,[int z]]])

Like &(), except that any of x, y, or z specified are added to the given location, which defaults to the current location; and as a special case, if only the location is given, i.e. D(l), then the location l is added to the current location. Think “D” for “displaced (by).” Thus, both D(-1) and D(left) return the location of the cell immediately to the left of this one, and D(,2,1) returns the location of the cell two below this one on the following layer, as does D(&(0,2,1)), but D(TABLE,1) returns the location of the cell just to the right of the one labeled “TABLE”.

R(args)

Shorthand for @(D(args)). Think “R” for “relative.” Thus R(-1) returns the value of the cell immediately to the left of this one, and R(1) returns the same cell as this one but on the following layer, as do R(&(0,0,1)) and R(below), but R(TABLE1) returns the value of the cell immediately down from the one labeled “TABLE”.

X(label to, label from, [fix_x], [fix_y], [fix_z])

“Excel reference”: returns the value of the cell at a computed target location. This target location is the one reached from the current cell via the same offset as the cell with label to has from label from. The idea is that if you label the source of data you want to reference, say with SRC, and the location of some place you want to start referring to it with REF, then you can use X(SRC,REF) to refer to the source data, and fill this formula to neighboring cells to refer to the neighbors of the source, and it will all continue to work if either the source or the reference is moved around in the sheet.
If the fix_DIM argument is the fix keyword (as opposed to an empty value), then the corresponding coordinate of the target cell is set to match that of to. This corresponds to fixing the row or column (or layer) of the reference, as with a “$” character in Excel. Thus X(SRC,REF,1,1,1) is identical to @(SRC), but you should certainly prefer the latter for clarity of expression.
There is a corresponding location function X&() as well, which takes exactly the same arguments with the same meanings, but it is rarely needed. It is provided for completeness.
See the FAQ below for further discussion of cell references.

string $(string env)

evaluates to the contents of the specified environment variable. If the variable does not exist, then an empty string will be returned.

above|below|left|right|up|down[([location l])]

As bare words (without any arguments and also without the parentheses) these symbols return a one-cell displacement in the named direction, e.g. D(above) gives the location of the same cell as the current on but in the previous layer and R(up) yields the value of the cell one up from the current cell. With parentheses, they act like @() but displaced by one cell in the named direction, so right() returns the value of the cell immediately to the right of the current one, and down(MYTABLE) gives the value one line down from the cell labeled MYTABLE, etc.

float abs(float x)

 

int abs(int x)

evaluates to the absolute value of x.

float acos(float|int x)

evaluates to the arc cosine of x, where x is given in radians.

float arcosh(float|int x)

evaluates to the arc hyperbolic cosine of x, where x is given in radians.

float arsinh(float|int x)

evaluates to the arc hyperbolic sine of x, where x is given in radians.

float artanh(float|int x)

evaluates to the arc hyperbolic tangent of x, where x is given in radians.

float asin(float|int x)

evaluates to the arc sine of x, where x is given in radians.

float atan(float|int x)

evaluates to the arc tangent of x, where x is given in radians.

style background(int c)

evaluates to a style token with the background color set to c (and no other fields set).

below[([location l])]

displacement by one cell in the positive z direction; see the fuller description at above.

int bitand(int v1, ...)

evaluates to the bitwise “and” of all the supplied values.

int bitor(int v1, ...)

evaluates to the bitwise “or” of all the supplied values.

style bold([bool b])

evaluates to a style token with the bold property set to b, which defaults to true (and no other fields set).

bool bool[([x])]

Converts x to a boolean value. This is very permissive; error values are unaffected; empty, integer 0, float 0.0, and boolean false values are false, and everything else is true. If x is omitted, defaults to the value of the current cell. If the parentheses are omitted as well, acts as a keyword, for example for testing types with is().

float ceil(float x)

evaluates to the smallest integral floating-point value greater than or equal to x.

center

keyword used as an argument to justify().

clock(integer condition,[location[,location])

conditionally clocks the specified cell if the condition is not 0. If two locations are given, all cells in that range will be clocked. The return value of clock is empty. Note that the clocked expression of a cell can clock itself; indeed, that's the only way that a cell can be clocked more than once in a single recalculation. Take care with the condition expression to avoid recalculation becoming stuck in an infinite loop, however.

compact

used as a keyword to the string() function; listed here to record that this identifier may not be used as a cell label.

float cos(float|int x)

evaluates to the cosine of x, where x is given in radians.

float cosh(float|int x)

evaluates to the hyperbolic cosine of x, where x is given in radians.

decimal

used as a keyword to the string() function; listed here to record that this identifier may not be used as a cell label.

float deg2rad(float|int x)

evaluates to the degrees that are equivalent to x radians.

style dim([bool b])

evaluates to a style token with the dim property set to b, which defaults to true (and no other fields set).

down[([location l])]

displacement by one cell in the positive y direction; see the fuller description at above.

float e[()]

evaluates to the Euler constant e. Note the parentheses are optional.

empty[(args)]

ignores all of its arguments and returns the empty value. Without parentheses, acts as a keyword, typically for is().

error error[([message])]

converts its argument to a string just as with the string() function, and then returns an error with that string as the message. Without parentheses, acts as a keyword, e.g. for is().

eval(location)

evaluates to the value of the expression in the cell at the given location, but evaluated in the context of the cell using eval(). This function may not be used nested any deeper than 32 times.

boolean false

represents the false Boolean value.

fident

a keyword indicating the token type of “function identifier,” provided for the sake of completeness. There is probably little practical call for this type.

find(expr, location stride[,location start])

examines cells in turn, returning the location of the first one at which expr evaluates to true, or boolean false if the boundary of the sheet is encountered. The second argument stride must not have all zero components, and is added to the location being examined at each iteration. Often it is useful to use a direction constant like up for the stride. The search begins at location start, which defaults to the current location plus the stride if it is not specified.

fix

used as a keyword to the X() and X&() functions; listed here to record that this identifier may not be used as a cell label.

float float[([float|string|int|empty s])]

converts into a floating point number the given float, string, int, or empty value (the latter converts to 0.0). If the argument is omitted, the value of the current cell is used. If the parentheses are omitted, acts as a keyword, e.g., for type testing with is().

style floatfmt(decimal|scientific|compact|hexact)

evaluates to a style token with the floating-point format set to the specified format, given as a bare word (and no other fields set).

float floor(float x)

evaluates to the largest integral floating-point value less than or equal to x.

style foreground(int c)

evaluates to a style token with the foreground color set to c (and no other fields set).

float frac(float x)

evaluates to the fractional part of x.

funcall

a keyword indicating the “funcall” token type used to encode expressions as tokens; may be used with is() for example.

hexact

used as a keyword to the string() function; listed here to record that this identifier may not be used as a cell label.

int int[([int|float|string|empty x][, direction])]

converts to an integer the given integer, float, string, or empty value x. (The latter converts to 0.) The optional second argument must be the name of one of the functions that produces a floating point integral value from a float, i.e., ceil, floor, round, or trunc, and it directs how to convert floating point values to an integer. (The default is trunc, see the documentation of the corresponding functions for a description of the conversion behavior.) If x is omitted, the value of the current cell is used. If in addition the parentheses are omitted, acts as a keyword, e.g., for value testing with is().

is[([x][, type1, type2,...])]

Boolean-valued type testing. Returns true if the given value x is any of the listed types. Each type may be any of the keywords bool, empty, error, fident, float, funcall, int, lident, location, number, operator, string, or style. Each of these identifies a single type, except number, which is a shorthand for empty, float, int. If no types are specified, returns true for any non-empty value. (In other words, is(x) is a boolean-valued version of n(x), without the special behavior when x is a location.) If x is omitted, defaults to the value of the current cell; the parentheses may be omitted as well, so bare is tests whether the current cell is non-empty.

style italic([bool b])

evaluates to a style token with the italic property set to b, which defaults to true (and no other fields set).

style justify(left|right|center)

evaluates to a style token with the justification set to the specified direction, given as a bare word. No other fields are set in the result.

left[([location l])]

displacement by one cell in the negative x direction; see the fuller description at above.

string len(string s)

evaluates to the length of s.

lident

a keyword indicating the “label identifier” token type. This type is not generally accessible, as labels always evaluate to their locations (or error if there is no such label).

float log(float|int x[, float|int y])

evaluates to the logarithm of x. If y is not specified, the result will be the natural logarithm, otherwise it will be the logarithm to the base of y.

location

currently this is only a keyword, e.g., for use with is(). Use &() to convert three integers to a location.

location max(location l1, location l2) | max(v1, v2, ...)

evaluates to the maximum in the same way min does for the minimum.

location min(location l1, location l2) | min(v1, v2, ...)

The first form evaluates to the location of the minimum of all values in the block marked by the corners pointed to by l1 and l2. Note that the empty cell is equal to 0, 0.0 and , so if the first minimum is an empty cell, the result will be a pointer to this cell, too. If you are not interested in the location of the minimum but the value itself, use @(min(l1, l2)). The second form simply returns the smallest of the specified values, returning an error if it encounters two that are not comparable (like a string and an integer).

int n([location l1[, location l2]) | n( v1, v2, ...)

The first form evaluates to the number of non-empty cells in the block with corners at locations l1 and l2. Location l2 defaults to l1; i.e., with a single location argument n(l1) just tests whether the cell at l1 is empty. Location l1 defaults to the current location. The second form simply returns the number of its arguments which are nonempty.

number[([bool|empty|int|float|string x])]

Converts its argument, which defaults to the value of the current cell, to the most appropriate number type. Thus, it leaves ints and floats alone, converts boolean values to integers 1 or 0, converts empty to integer 0, and converts numeric strings to ints if they don't have a decimal point and floats if they do. Without parentheses, acts as a keyword for is(), abbreviating the combination of float, int, and empty.

operator

A keyword indicating the “operator” token type, representing symbols like parentheses, plus signs, commas, etc.

poly(float|integer x, float|integer cn[, ...])

evaluates the polynomial $c_{n}\cdot x^{n}+\ldots+c_{0}\cdot x^{0}$.

style precision(int x)

evaluates to a style token in which the precision is set to x (and no other fields are set).

float rad2deg(float|int x)

evaluates to the radians that are equivalent to x degrees.

right[([location l])]

displacement by one cell in the positive x direction; see the fuller description at above.

float rnd()

evaluates to a pseudo-random number between 0.0 and 1.0, changing each time the expression is evaluated.

float round(float x)

evaluates to the argument x rounded to an integral value. Unless the system floating-point rounding direction has been changed, this will be the integral value nearest to x.

scientific

Used as a keyword argument to the string() function; listed here to record that this identifier may not be used as a cell label.

style shadowed([bool b])

evaluates to a style token with the shadowed property set to b, which defaults to true (and no other fields set).

float sin(float|int x)

evaluates to the sine of x, where x is given in radians.

float sinh(float|int x)

evaluates to the hyperbolic sine of x, where x is given in radians.

float sqrt(float|int x)

evaluates to the square root of x.

string strftime(string f [, integer t])

evaluates to the time t formatted according to the format specified in f. Times in t are counted in seconds since epoch (1970-1-1 0:00). If t is empty or 0, the actual time is used. For the format specifications consult the man page of your c library, strftime (3). Example: @(now)=int(strftime(%s)) sets the field with label now to the actual time.

string string(x[, [integer precision][, format]])

evaluates to the string representation of its first argument. The optional second argument gives the precision used for converting floating point numbers to string form. The optional third argument may be one of the keywords “decimal”, “scientific”, “compact”, or “hexact”, controlling the format for converting floating point numbers to string form. If the optional arguments are not specified, current defaults are used.

int strptime(string f, string datetime)

evaluates to the seconds since epoch (1970-1-1 0:00) of the datetime string, parsed according to the format specified in f. For the format specifications consult the man page of your c library, strptime (3).

style style[([x])]

attempts to convert x to a style; this currently only succeeds if x already is a style; or if it is a location, it extracts the current style of that location. x defaults to the current location. Without parentheses as a bare word, style is a keyword used for example by is() to test the type of an entity.

string substr(string s, integer x [,integer y])

evaluates to the substring of s between x and y, which start at 0. If is omitted, the substring proceeds to the end of the string.

sum(location l1, location l2) | sum( v1,  v2,  ... )

The first form evaluates to the sum of all values in the block with corners at locations l1 and l2. The second form simply adds all of its arguments.

float tan(float|int x)

evaluates to the tangent of x, where x is given in radians.

float tanh(float|int x)

evaluates to the hyperbolic tangent of x, where x is given in radians.

float tau[()]

evaluates to the circle constant $\tau$, the ratio of circumference to radius of any circle. (Note $\tau=2\pi$.)

int time[()]

each time this expression is evaluated, it gives the time in seconds since the epoch.

style transparent([bool b])

evaluates to a style token with the transparent property set to b, which defaults to true (and no other fields set).

boolean true

represents the true Boolean value.

float trunc(float x)

evaluates to the integer part of x in floating-point form; generally this should be the same as x - frac(x).

style underline([bool b])

evaluates to a style token with the underline property set to b, which defaults to true (and no other fields set).

up[([location l])]

displacement by one cell in the negative y direction; see the fuller description at above.)

int x([location l])

 

int y([location l])

 

int z([location l])

evaluate to the x, y and z position of the given location, of the currently updated cell if none is given. These functions are usually used in combination with the @ function for obtaining information from other cells, but see also the convenience functions R() and D() for relative references.