# JME¶

JME expressions are used by students to enter answers to algebraic questions, and by question authors to define variables. JME syntax is similar to what you’d type on a calculator.

## Variable names¶

Variable names are case-insensitive, so y represents the same thing as Y. The first character of a variable name must be an alphabet letter; after that, any combination of letters, numbers and underscores is allowed, with any number of ' on the end.

Examples:
• x
• x_1
• time_between_trials
• var1
• row1val2
• y''

e, i and pi are reserved names representing mathematical constants. They are rewritten by the interpreter to their respective numerical values before evaluation.

This screencast describes which variable names are valid, and gives some advice on how you should pick names:

### Variable name annotations¶

Names can be given annotations to change how they are displayed. The following annotations are built-in:

• verb – does nothing, but names like i, pi and e are not interpreted as the famous mathematical constants.
• op – denote the name as the name of an operator — wraps the name in the LaTeX operatorname command when displayed
• v or vector – denote the name as representing a vector — the name is displayed in boldface
• unit – denote the name as representing a unit vector — places a hat above the name when displayed
• dot – places a dot above the name when displayed, for example when representing a derivative
• m or matrix – denote the name as representing a matrix — displayed using a non-italic font

Any other annotation is taken to be a LaTeX command. For example, a name vec:x is rendered in LaTeX as \vec{x}, which places an arrow above the name.

You can apply multiple annotations to a single variable. For example, v:dot:x produces a bold x with a dot on top: $$\boldsymbol{\dot{x}}$$.

Names with different annotations are considered to represent different values, for the purpose of simplification and evaluation. For example, in the expression dot:x + x, the two terms will not be collected together.

## Data types¶

JME expressions are composed of the following data types. Some extensions add new data types.

number

A real or complex floating-point number.

i, e, infinity and pi are reserved keywords for the imaginary unit, the base of the natural logarithm, ∞ and π, respectively.

Examples: 0.0, -1.0, 0.234, i, e, pi

Numbers of this type are represented using JavaScript’s built-in Number object, which is a 64-bit IEEE 754 floating-point number. This representation offers a very good compromise between precision and the range of values that can be stored, but can behave in unexpected ways. Accuracy is easily lost when dealing with very big or very small numbers, and on division.

See functions related to Arithmetic, Number operations, Trigonometry and Number theory.

Automatically converts to:
integer

An element of the set of integers, $$\mathbb{Z}$$.

Examples: 0, 1, -2, 431.

Automatically converts to:
rational

A fraction; an element of the set of rationals, $$\mathbb{Q}$$. The numerator and denominator are integers.

Instances of this data type may be top-heavy, with numerator bigger than the denominator, and are not required to be reduced.

Examples: 1/1, -34/2, 3/4.

Automatically converts to:
decimal

A number with a guaranteed level of precision, and arbitrary order of magnitude.

Numbers of this type are represented using the Decimal.js library. They’re guaranteed to be accurate to 40 significant figures. The order of magnitude is stored separately from the significant digits, so there’s no less of precision for very big or very small numbers.

Examples: dec(0), dec("1.23e-5"), 6.0221409*10^23

Automatically converts to:
boolean

Booleans represent either truth or falsity. The logical operations and, or and xor operate on and return booleans.

Examples: true, false

See functions related to Logic and Control flow.

string

Use strings to create non-mathematical text. Either ' or " can be used to delimit strings.

You can escape a character by placing a single backslash character before it. The following escape codes have special behaviour:

 \n New-line \{ \{ \} \}

If you want to write a string which contains a mixture of single and double quotes, you can delimit it with triple-double-quotes or triple-single-quotes, to save escaping too many characters.

Examples: "hello there", 'hello there', """ I said, "I'm Mike's friend" """

See functions related to Strings.

list

An ordered list of elements of any data type.

Examples: [0,1,2,3], [a,b,c], [true,false,true]

See functions related to Lists.

dict

A ‘dictionary’, mapping key strings to values of any data type.

A dictionary is created by enclosing one or more key-value pairs (a string followed by a colon and any JME expression) in square brackets, or with the dict function.

Key strings are case-sensitive.

Examples:

• ["a": 1, "b": 2]
• ["name": "Tess Tuser", "age": 106, "hobbies": ["reading","writing","arithmetic"] ]
• dict("key1": 0.1, "key2": 1..3)
• dict([["key1",1], ["key2",2]])

Warning

Because lists and dicts use similar syntax, [] produces an empty list, not an empty dictionary. To create an empty dictionary, use dict().

See functions related to Dictionaries and JSON.

range

A range a..b#c represents (roughly) the set of numbers $$\{a+nc \: | \: 0 \leq n \leq \frac{b-a}{c} \}$$. If the step size is zero, then the range is the continuous interval $$[a,b]$$.

Examples: 1..3, 1..3#0.1, 1..3#0

See functions related to Ranges.

Automatically converts to:
set

An unordered set of elements of any data type. The elements are pairwise distinct - if you create a set from a list with duplicate elements, the resulting set will not contain the duplicates.

Examples: set(a,b,c), set([1,2,3,4]), set(1..5)

See functions related to Sets.

Automatically converts to:
vector

The components of a vector must be numbers.

When combining vectors of different dimensions, the smaller vector is padded with zeros to make up the difference.

Examples: vector(1,2), vector([1,2,3,4])

See functions related to Vector and matrix arithmetic.

Automatically converts to:
matrix

Matrices are constructed from lists of numbers, representing the rows.

When combining matrices of different dimensions, the smaller matrix is padded with zeros to make up the difference.

Examples: matrix([1,2,3],[4,5,6]), matrix(row1,row2,row3)

See functions related to Vector and matrix arithmetic.

Automatically converts to:
name

A variable name. When an expression is evaluated, all variable names are replaced withe their corresponding value in the current scope.

function

An application of a function.

Examples: f(x), sin(x)

op

An infix binary operation, or a pre-/post-fix unary operation.

Examples: x+y, n!, a and b

html

An HTML DOM node.

Examples: html("<div>things</div>")

See functions related to HTML.

expression

A JME sub-expression. Sub-expressions can be simplified, rearranged, pattern-matched, or evaluated using given values for their free variables.

See functions related to Sub-expressions.

### Automatic data type conversion¶

Some data types can be automatically converted to others when required. For example, the number-like types such as integer and decimal can be automatically converted to number values.

The data types of the arguments to a function application determine which version of the function is used. Ideally, this will do what you expect without you having to think about it. For reference, the process for deciding on what conversions to perform is as follows:

• If there is a version of the function which takes exactly the given data types, that is used.
• Otherwise, each definition of the function is compared by looking at each of the arguments, working from left to right.
• A definition which does not convert an argument is preferred to one that does.
• If both definitions being compared need to convert an argument, the type that occurs first in the input type’s list of automatic conversion methods is used. (This follows the order of the types under the “Automatically converts to” headers above)

The following examples illustrate how this works.

 Expression Type of result Explanation 1+3.3 number The 1 is converted to a number, and then added to 3.3. 1+1/2 rational integer prefers to convert to rational over 1.23+dec("1.2") decimal decimal values are preferred to number because they’re more precise. 1/2+0.5 number rational can convert to number, but not the other way round, so number addition is used. set(1,2,3,4) except  list except() is only defined on list values, so the set is converted to a list automatically.

## Function reference¶

### Arithmetic¶

x+y

Definitions:
Examples:
• 1+23
• vector(1,2)+vector(3,4)vector(4,6)
• matrix([1,2],[3,4])+matrix([5,6],[7,8])matrix([6,8],[10,12])
• [1,2,3]+4[1,2,3,4]
• [1,2,3]+[4,5,6][1,2,3,4,5,6]
• "hi "+"there""hi there"
x-y

Subtraction.

Definitions:
Examples:
• 1-2-1
• vector(3,2)-vector(1,4)vector(2,-2)
• matrix([5,6],[3,4])-matrix([1,2],[7,8])matrix([4,4],[-4,-4])
x*y

Multiplication.

Definitions:
Examples:
• 1*22
• 2*vector(1,2,3)vector(2,4,6)
• matrix([1,2],[3,4])*2matrix([2,4],[6,8])
• matrix([1,2],[3,4])*vector(1,2)vector(5,11)
x/y

Division. Only defined for numbers.

Definitions:
Example:
• 3/40.75.
x^y

Exponentiation.

exp(x) is a synoynm for e^x.

Definitions:
Examples:
• 3^29
• e^(pi * i)-1

### Number operations¶

decimal(n)
decimal(x)

Construct a decimal value. Any string accepted by Decimal.js is accepted.

Definitions:
int(n)

Convert n to an integer, rounding to the nearest integer.

Definitions:
Example:
• int(3.0)3
abs(x)
len(x)
length(x)

Absolute value, or modulus.

Definitions:
Examples:
• abs(-8)8
• abs(3-4i)5
• abs("Hello")5
• abs([1,2,3])3
• len([1,2,3])3
• len(set([1,2,2]))2
• length(vector(3,4))5
• abs(vector(3,4,12))13
• len(["a": 1, "b": 2, "c": 1])3
arg(z)

Argument of a complex number.

Definitions:
Example:
• arg(-1)pi
re(z)

Real part of a complex number.

Definitions:
Example:
• re(1+2i)1
im(z)

Imaginary part of a complex number.

Definitions:
Example:
• im(1+2i)2
conj(z)

Complex conjugate.

Definitions:
Example:
• conj(1+i)1-i
isint(x)

Returns true if x is an integer - that is, it is real and has no fractional part.

Definitions:
Example:
• isint(4.0)true
iszero(n)

Returns true when n is exactly 0.

Definitions:
sqrt(x)
sqr(x)

Square root of a number.

Examples:
• sqrt(4)2
• sqrt(-1)i
root(x, n)

nth root of x.

Definitions:
Example:
• root(8,3)2.
ln(x)

Natural logarithm.

Definitions:
Example:
• ln(e)1
log(x, b)

Logarithm with base b, or base 10 if b is not given.

Definitions:
Example:
• log(100)2.
• log(343,7)3.
log(x, b)

Logarithm with base b.

Example:
• log(8,2)3.
degrees(x)

Definitions:
Example:
• degrees(pi/2)90
radians(x)

Example:
• radians(180)pi
sign(x)
sgn(x)

Sign of a number. Equivalent to $$\frac{x}{|x|}$$, or 0 when x is 0.

Definitions:
Examples:
• sign(3)1
• sign(-3)-1
max(a, b)

Greatest of the given numbers.

Definitions:
Example:
• max(46,2)46
• max([1,2,3])3
min(a, b)

Least of the given numbers.

Definitions:
Example:
• min(3,2)2
• min([1,2,3])1
clamp(x, a, b)

Return the point nearest to x in the interval $$[a,b]$$.

Equivalent to max(a,min(x,b)).

Definitions:
Example:
• clamp(1,0,2)1
• clamp(-1,0,2)0
• clamp(3,0,2)2
precround(n, d)

Round n to d decimal places. On matrices and vectors, this rounds each element independently.

Definitions:
Examples:
• precround(pi,5)3.14159
• precround(matrix([[0.123,4.56],[54,98.765]]),2)matrix([0.12,4.56],[54,98.77])
• precround(vector(1/3,2/3),1)vector(0.3,0.7)
siground(n, f)

Round n to f significant figures. On matrices and vectors, this rounds each element independently.

Definitions:
Examples:
• siground(pi,3)3.14
• siground(matrix([[0.123,4.56],[54,98.765]]),2)matrix([0.12,4.6],[54,99])
• siground(vector(10/3,20/3),2)vector(3.3,6.7)
withintolerance(a, b, t)

Returns true if $$b-t \leq a \leq b+t$$.

Definitions:
Example:
• withintolerance(pi,22/7,0.1)true
dpformat(n, d[, style])

Round n to d decimal places and return a string, padding with zeros if necessary.

If style is given, the number is rendered using the given notation style. See the page on Number notation for more on notation styles.

Definitions:
Example:
• dpformat(1.2,4)"1.2000"
countdp(n)

Assuming n is a string representing a number, return the number of decimal places used. The string is passed through cleannumber() first.

Definitions:
Example:
• countdp("1.0")1
• countdp("1")0
• countdp("not a number")0
sigformat(n, d[, style])

Round n to d significant figures and return a string, padding with zeros if necessary.

Definitions:
Example:
• sigformat(4,3)"4.00"
countsigfigs(n)

Assuming n is a string representing a number, return the number of significant figures. The string is passed through cleannumber() first.

Definitions:
Example:
• countsigfigs("1")1
• countsigfigs("100")1
• countsigfigs("1.0")2
• countsigfigs("not a number")0
togivenprecision(str, precisionType, precision, strict)

Returns true if str is a string representing a number given to the desired number of decimal places or significant figures.

precisionType is either "dp", for decimal places, or "sigfig", for significant figures.

If strict is true, then trailing zeroes must be included.

Definitions:
Examples:
• togivenprecision("1","dp",1,true)false
• togivenprecision("1","dp",1,false)true
• togivenprecision("1.0","dp",1,true)true
• togivenprecision("100","sigfig",1,true)true
• togivenprecision("100","sigfig",3,true)true
tonearest(a, b)

Round a to the nearest multiple of b.

Definitions:
Example:
• tonearest(1.234,0.1)1.2
formatnumber(n, style)

Render the number n using the given number notation style.

See the page on Number notation for more on notation styles.

Definitions:
Example:
• formatnumber(1234.567,"eu")"1.234,567"
cleannumber(str, styles)

Clean a string potentially representing a number. Remove space, and then try to identify a notation style, and rewrite to the plain-en style.

styles is a list of notation styles. If styles is given, str will be tested against the given styles. If it matches, the string will be rewritten using the matched integer and decimal parts, with punctuation removed and the decimal point changed to a dot.

Definitions:
Examples:
• cleannumber("100 000,02",["si-fr"])"100000.02"
• cleannumber(" 1 ")"1"
• cleannumber("1.0")"1.0"
matchnumber(str, styles)

Try to match a string representing a number in any of the given styles at the start of the given string, and return both the matched text and a corresponding number value.

Definitions:
Examples:
• matchnumber("1.234",["plain","eu"])[ "1.234", 1.234 ]
• matchnumber("1,234",["plain","eu"])[ "1,234", 1.234 ]
• matchnumber("5 000 things",["plain","si-en"])[ "5 000", 5000 ]
• matchnumber("apple",["plain"])[ "", NaN ]
parsenumber(string, style)

Parse a string representing a number written in the given style.

If a list of styles is given, the first that accepts the given string is used.

See the page on Number notation for more on notation styles.

Examples:
• parsenumber("1 234,567","si-fr")1234.567
• parsenumber("1.001",["si-fr","eu"])1001
parsenumber_or_fraction(string, style)

Works the same as parsenumber(), but also accepts strings of the form number/number, which it interprets as fractions.

Example:
• parsenumber_or_fraction("1/2")0.5
parsedecimal(string, style)

Parse a string representing a number written in the given style, and return a decimal value.

If a list of styles is given, the first that accepts the given string is used.

See the page on Number notation for more on notation styles.

Definitions:
Examples:
• parsedecimal("1 234,567","si-fr")1234.567
• parsedecimal("1.001",["si-fr","eu"])1001
parsedecimal_or_fraction(string, style)

Works the same as parsedecimal(), but also accepts strings of the form number/number, which it interprets as fractions.

Definitions:
Example:
• parsedecimal_or_fraction("1/2")0.5
isnan(n)

Is n the “not a number” value, NaN?

Definitions:
Examples:
• isnan(1)false
• isnan(parsenumber("a","en"))true

### Trigonometry¶

Trigonometric functions all work in radians, and have as their domain the complex numbers.

sin(x)

Sine.

Definitions:
cos(x)

Cosine.

Definitions:
tan(x)

Tangent: $$\tan(x) = \frac{\sin(x)}{\cos(x)}$$

Definitions:
cosec(x)

Cosecant: $$\csc(x) = \frac{1}{sin(x)}$$

Definitions:
sec(x)

Secant: $$\sec(x) = \frac{1}{cos(x)}$$

Definitions:
cot(x)

Cotangent: $$\cot(x) = \frac{1}{\tan(x)}$$

Definitions:
arcsin(x)

Inverse of sin(). When $$x \in [-1,1]$$, arcsin(x) returns a value in $$[-\frac{\pi}{2}, \frac{\pi}{2}]$$.

Definitions:
arccos(x)

Inverse of cos(). When $$x \in [-1,1]$$, arccos(x) returns a value in $$[0, \frac{\pi}]$$.

Definitions:
arctan(x)

Inverse of tan(). When $$x$$ is non-complex, arctan(x) returns a value in $$[-\frac{\pi}{2}, \frac{\pi}{2}]$$.

Definitions:
sinh(x)

Hyperbolic sine: $$\sinh(x) = \frac{1}{2} \left( \mathrm{e}^x - \mathrm{e}^{-x} \right)$$

Definitions:
cosh(x)

Hyperbolic cosine: $$\cosh(x) = \frac{1}{2} \left( \mathrm{e}^x + \mathrm{e}^{-x} \right)$$

Definitions:
tanh(x)

Hyperbolic tangent: $$\tanh(x) = \frac{\sinh(x)}{\cosh(x)}$$

Definitions:
cosech(x)

Hyperbolic cosecant: $$\operatorname{cosech}(x) = \frac{1}{\sinh(x)}$$

Definitions:
sech(x)

Hyperbolic secant: $$\operatorname{sech}(x) = \frac{1}{\cosh(x)}$$

Definitions:
coth(x)

Hyperbolic cotangent: $$\coth(x) = \frac{1}{\tanh(x)}$$

Definitions:
arcsinh(x)

Inverse of sinh().

Definitions:
arccosh(x)

Inverse of cosh().

Definitions:
arctanh(x)

Inverse of tanh().

Definitions:

### Number theory¶

x!

Factorial. When x is not an integer, $$\Gamma(x+1)$$ is used instead.

fact(x) is a synoynm for x!.

Definitions:
Examples:
• fact(3)6
• 3!6
• fact(5.5)287.885277815
factorise(n)

Factorise n. Returns the exponents of the prime factorisation of n as a list.

Definitions:
Examples
• factorise(18)[1,2]
• factorise(70)[1,0,1,1]
gamma(x)

Gamma function.

Definitions:
Examples:
• gamma(3)2
• gamma(1+i)0.4980156681 - 0.1549498283i
ceil(x)

Round up to the nearest integer. When x is complex, each component is rounded separately.

Definitions:
Examples:
• ceil(3.2)4
• ceil(-1.3+5.4i)-1+6i
floor(x)

Round down to the nearest integer. When x is complex, each component is rounded separately.

Definitions:
Example:
• floor(3.5)3
round(x)

Round to the nearest integer. 0.5 is rounded up.

Definitions:
Examples:
• round(0.1)0
• round(0.9)1
• round(4.5)5
• round(-0.5)0
trunc(x)

If x is positive, round down to the nearest integer; if it is negative, round up to the nearest integer.

Definitions:
Example:
• trunc(3.3)3
• trunc(-3.3)-3
fract(x)

Fractional part of a number. Equivalent to x-trunc(x).

Definitions:
Example:
• fract(4.3)0.3
rational_approximation(n[, accuracy])

Compute a rational approximation to the given number by computing terms of its continued fraction, returning the numerator and denominator separately. The approximation will be within $$e^{-\text{accuracy}}$$ of the true value; the default value for accuracy is 15.

Definitions:
Examples:
• rational_approximation(pi)[355,113]
• rational_approximation(pi,3)[22,7]
mod(a, b)

Modulo; remainder after integral division, i.e. $$a \bmod b$$.

Definitions:
Example:
• mod(5,3)2
perm(n, k)

Count permutations, i.e. $$^n \kern-2pt P_k = \frac{n!}{(n-k)!}$$.

Definitions:
Example:
• perm(5,2)20
comb(n, k)

Count combinations, i.e. $$^n \kern-2pt C_k = \frac{n!}{k!(n-k)!}$$.

Definitions:
Example:
• comb(5,2)10.
gcd(a, b)
gcf(a, b)

Greatest common divisor of integers a and b. Can also write gcf(a,b).

Definitions:
Example:
• gcd(12,16)4
gcd_without_pi_or_i(a, b)

Take out factors of $$\pi$$ or $$i$$ from a and b before computing their greatest common denominator.

Definitions:
Example:
• gcd_without_pi_or_i(6*pi, 9)3
coprime(a, b)

Are a and b coprime? True if their gcd() is $$1$$, or if either of a or b is not an integer.

Definitions:
Examples:
• coprime(12,16)false
• coprime(2,3)true
• coprime(1,3)true
• coprime(1,1)true
lcm(a, b)

Lowest common multiple of integers a and b. Can be used with any number of arguments; it returns the lowest common multiple of all the arguments.

Definitions:
Examples
• lcm(8,12)24
• lcm(8,12,5)120
x|y

x divides y.

Definitions:
Example:
• 4|8true

### Vector and matrix arithmetic¶

vector(a1, a2, ..., aN)

Create a vector with given components. Alternately, you can create a vector from a single list of numbers.

Definitions:
Examples:
• vector(1,2,3)
• vector([1,2,3])
matrix(row1, row2, ..., rowN)

Create a matrix with given rows, which should be either vectors or lists of numbers. Or, you can pass in a single list of lists of numbers.

Definitions:
Examples:
• matrix([1,2],[3,4])
• matrix([[1,2],[3,4]])
id(n)

Identity matrix with $$n$$ rows and columns.

Definitions:
Example:
• id(3)matrix([1,0,0],[0,1,0],[0,0,1])
numrows(matrix)

The number of rows in the given matrix

Definitions:
Example:
• numrows(matrix([1,2],[3,4],[5,6]))3
numcolumns(matrix)

The number of columns in the given matrix

Definitions:
Example:
• numcolumns(matrix([1,2],[3,4],[5,6]))2
rowvector(a1, a2, ..., aN)

Create a row vector ($$1 \times n$$ matrix) with the given components. Alternately, you can create a row vector from a single list of numbers.

Definitions:
Examples:
• rowvector(1,2)matrix([1,2])
• rowvector([1,2])matrix([1,2])
dot(x, y)

Dot (scalar) product. Inputs can be vectors or column matrices.

Definitions:
Examples:
• dot(vector(1,2,3),vector(4,5,6))32
• dot(matrix(,), matrix(,))11
cross(x, y)

Cross product. Inputs can be vectors or column matrices.

Definitions:
Examples:
• cross(vector(1,2,3),vector(4,5,6))vector(-3,6,-3)
• cross(matrix(,,), matrix(,,))vector(-3,6,-3)
angle(a, b)

Angle between vectors a and b, in radians. Returns 0 if either a or b has length 0.

Definitions:
Example:
• angle(vector(1,0),vector(0,1))0.5 pi
is_zero(x)

Returns true if every component of the vector x is zero.

Definitions:
Example:
• is_zero(vector(0,0,0))true
det(x)

Determinant of a matrix. Throws an error if used on anything larger than a 3×3 matrix.

Definitions:
Examples:
• det(matrix([1,2],[3,4]))-2
• det(matrix([1,2,3],[4,5,6],[7,8,9]))0
transpose(x)

Matrix transpose.

Definitions:
Examples:
• transpose(matrix([1,2],[3,4]))matrix([1,3],[2,4])
• transpose(vector(1,2,3))matrix([1,2,3])
sum_cells(m)

Calculate the sum of all the cells in a matrix.

Definitions:
Example:
• sum_cells(matrix([1,2],[3,4]))10

### Strings¶

x[n]

Get the Nth character of the string x. Indices start at 0.

Example:
• "hello""e"
x[a..b]

Slice the string x - get the substring between the given indices. Note that indices start at 0, and the final index is not included.

Example:
• "hello"[1..4]"ell"
substring in string

Test if substring occurs anywhere in string. This is case-sensitive.

Example:
• "plain" in "explains"true
string(x)

Convert x to a string.

Definitions:
Example:
• string(123)"123"
• string(x)"x"
latex(x)

Mark string x as containing raw LaTeX, so when it’s included in a mathmode environment it doesn’t get wrapped in a \textrm environment.

Note that backslashes must be double up, because the backslash is an escape character in JME strings.

Definitions:
Example:
• latex('\\frac{1}{2}').
safe(x)

Mark string x as safe: don’t substitute variable values into it when this expression is evaluated.

Use this function to preserve curly braces in string literals.

Definitions:
Example:
• safe('From { to }')
render(x, values)

Substitute variable values into the string x, even if it’s marked as safe (see safe()).

The optional dictionary values overrides any previously-defined values of variables.

Definitions:
Example:
• render(safe("I have {num_apples} apples."), ["num_apples": 5])"I have 5 apples."
• render(safe("Let $x = \\var{x}$"), ["x": 2])"Let $x = {2}$"

Note

The variable dependency checker can’t establish which variables will be used in the string until render is evaluated, so you may encounter errors if using render in the definition of a question variable. You can ensure a variable has been evaluated by including it in the values argument, e.g.:

render("a is {}",["a": a])


This function is intended for use primarily in content areas.

capitalise(x)

Capitalise the first letter of a string.

Definitions:
Example:
• capitalise('hello there').
pluralise(n, singular, plural)

Return singular if n is 1, otherwise return plural.

Definitions:
Example:
• pluralise(num_things,"thing","things")
upper(x)

Convert string to upper-case.

Definitions:
Example:
• upper('Hello there').
lower(x)

Convert string to lower-case.

Definitions:
Example:
• lower('CLAUS, Santa').
join(strings, delimiter)

Join a list of strings with the given delimiter.

Definitions:
Example:
• join(['a','b','c'],',')"a,b,c"
split(string, delimiter)

Split a string at every occurrence of delimiter, returning a list of the the remaining pieces.

Definitions:
Example:
• split("a,b,c,d",",")["a","b","c","d"]
split_regex(string, pattern, flags)

Split a string at every occurrence of a substring matching the given regular expression pattern, returning a list of the the remaining pieces.

Definitions:
Example:
• split_regex("a, b,c, d ",", *")["a","b","c","d"]
• split_regex("this and that AND THIS"," and ","i")["this","that","THIS"]
trim(str)

Remove whitespace from the start and end of str.

Definitions:
Example:
• trim(" a string  ")"a string"
currency(n, prefix, suffix)

Write a currency amount, with the given prefix or suffix characters.

Definitions:
Example:
• currency(123.321,"£","")"£123.32"
separateThousands(n, separator)

Write a number, with the given separator character between every 3 digits

To write a number using notation appropriate to a particular culture or context, see formatnumber().

Definitions:
Example:
• separateThousands(1234567.1234,",")"1,234,567.1234"
unpercent(str)

Get rid of the % on the end of a percentage and parse as a number, then divide by 100.

Definitions:
Example:
• unpercent("2%")0.02
lpad(str, n, prefix)

Add copies of prefix to the start of str until the result is at least n characters long.

Definitions:
Example:
• lpad("3", 2, "0")"03"
rpad(str, n, suffix)

Add copies of suffix to the end of str until the result is at least n characters long.

Definitions:
Example:
• rpad("3", 2, "0")"30"
formatstring(str, values)

For each occurrence of %s in str, replace it with the corresponding entry in the list values.

Definitions:
Example:
• formatstring("Their name is %s",["Hortense"])"Their name is Hortense"
• formatstring("You should %s the %s",["simplify","denominator"])"You should simplify the denominator"
letterordinal(n)

Get the $$n$$th element of the sequence a, b, c, ..., aa, ab, ....

Note that the numbering starts from 0.

Definitions:
Examples:
• letterordinal(0)"a"
• letterordinal(1)"b"
• letterordinal(26)"aa"
match_regex(pattern, str, flags)

If str matches the regular expression pattern, returns a list of matched groups, otherwise returns an empty list.

This function uses JavaScript regular expression syntax.

flags is an optional string listing the options flags to use.

Definitions:
Examples:
• match_regex("\\d+","01234")["01234"]
• match_regex("a(b+)","abbbb")["abbbb","bbbb"]
• match_regex("a(b+)","ABBBB")[]
• match_regex("a(b+)","ABBBB","i")["ABBBB","BBBB"]
translate(str, arguments)

Translate the given string, if it’s in the localisation file.

Look at the default localisation file for strings which can be translated. This function takes a key representing a string to be translated, and returns the corresponding value from the current localisation file.

arguments is a dictionary of named substitutions to make in the string.

Definitions:
Examples:
• translate("question.header",["number": 2])"Question 2" (when the en-GB locale is in use)
• translate("question.header",["number": 2]) "Pregunta 2" (when the es-ES locale is in use)
isbool(str)

After converting to lower case, is str any of the strings "true", "false", "yes" or "no"?

Definitions:
Examples:
• isbool("true")true
• isbool("YES")true
• isbool("no")true
• isbool("y")false

### Logic¶

x<y

Returns true if x is less than y.

Definitions:
Example:
• 4<5
x>y

Returns true if x is greater than y.

Definitions:
Example:
• 5>4
x<=y

Returns true if x is less than or equal to y.

Definitions:
Example:
• 4<=4
x>=y

Returns true if x is greater than or equal to y.

Definitions:
Example:
• 4>=4
x<>y

Returns true if x is not equal to y. Returns true if x and y are not of the same data type.

Definitions:
Examples:
• 'this string' <> 'that string'
• 1<>2
• '1' <> 1
x=y

Returns true if x is equal to y. Returns false if x and y are not of the same data type.

Definitions:
Examples:
• vector(1,2)=vector(1,2,0)
• 4.0=4
isclose(x, y, rel_tol, abs_tol)

Returns true if x is close to y.

Equivalent to the following expression:

abs(x-y) <= max( rel_tol*max(abs(a),abs(b)), abs_tol )

Definitions:
resultsequal(a, b, checkingFunction, accuracy)

Returns true if a and b are both of the same data type, and “close enough” according to the given checking function.

Vectors, matrices, and lists are considered equal only if every pair of corresponding elements in a and b is “close enough”.

checkingFunction is the name of a checking function to use. These are documented in the Numbas runtime documentation.

Definitions:
Examples:
• resultsequal(22/7,pi,"absdiff",0.001)false
• resultsequal(22/7,pi,"reldiff",0.001)true
x and y
x && y
x & y

Logical AND. Returns true if both x and y are true, otherwise returns false.

Definitions:
Examples:
• true and true
• true && true
• true & true
not x

Logical NOT.

Definitions:
Examples:
• not true
• !true
x or y

Logical OR. Returns true when at least one of x and y is true. Returns false when both x and y are false.

Definitions:
Examples:
• true or false
• true || false
x xor y

Logical XOR. Returns true when at either x or y is true but not both. Returns false when x and y are the same expression.

Definitions:
Example:
• true XOR false.
x implies y

Logical implication. If x is true and y is false, then the implication is false. Otherwise, the implication is true.

Definitions:
Example:
• false implies true.

### Collections¶

x[y]

Get the yth element of the collection x.

For matrices, the yth row is returned.

For dictionaries, the value corresponding to the key y is returned. If the key is not present in the dictionary, an error will be thrown.

Definitions:
Examples:
• [0,1,2,3]1
• vector(0,1,2)2
• matrix([0,1,2],[3,4,5],[6,7,8])vector(0,1,2)
• ["a": 1, "b": 2]["a"]1
x[a..b]
x[a..b#c]

Slice the collection x - return elements with indices in the given range. Note that list indices start at 0, and the final index is not included.

Definitions:
Example:
• [0,1,2,3,4,5][1..3][1,2]
• [0,1,2,3,4,5][1..6#2][1,3,5]
x in collection

Is element x in collection?

Definitions:
Examples:
• 3 in [1,2,3,4]true
• 3 in (set(1,2,3,4) and set(2,4,6,8))false
• "a" in ["a": 1]true
• 1 in ["a": 1] throws an error because dictionary keys must be strings.

### Ranges¶

a..b

Define a range. Includes all integers between and including a and b.

Definitions:
Examples:
• 1..5
• -6..6
range#step

Set the step size for a range. Default is 1. When step is 0, the range includes all real numbers between the limits.

Definitions:
Examples:
• 0..1 # 0.1
• 2..10 # 2
• 0..1#0
a except b

Exclude a number, range, or list of items from a list or range.

Definitions:
Examples:
• -9..9 except 0
• -9..9 except [-1,1]
• 3..8 except 4..6
• [1,2,3,4,5] except [2,3]

### Lists¶

repeat(expression, n)

Evaluate expression n times, and return the results in a list.

Definitions:
Example:
• repeat(random(1..4),5) [2, 4, 1, 3, 4]
all(list)

Returns true if every element of list is true.

Definitions:
Examples:
• all([true,true])true
• all([true,false])false
• all([])true
some(list)

Returns true if at least one element of list is true.

Definitions:
Examples:
• some([false,true,false])true
• some([false,false,false])false
• some([])false
map(expression,name[s],d)

Evaluate expression for each item in list, range, vector or matrix d, replacing variable name with the element from d each time.

You can also give a list of names if each element of d is a list of values. The Nth element of the list will be mapped to the Nth name.

Note

Do not use i or e as the variable name to map over - they’re already defined as mathematical constants!

Definitions:
Examples:
• map(x+1,x,1..3)[2,3,4]
• map(capitalise(s),s,["jim","bob"])["Jim","Bob"]
• map(sqrt(x^2+y^2),[x,y],[ [3,4], [5,12] ])[5,13]
• map(x+1,x,id(2))matrix([2,1],[1,2])
• map(sqrt(x),x,vector(1,4,9))vector(1,2,3)
filter(expression, name, d)

Filter each item in list or range d, replacing variable name with the element from d each time, returning only the elements for which expression evaluates to true.

Note

Do not use i or e as the variable name to map over - they’re already defined as mathematical constants!

Definitions:
Example:
• filter(x>5,x,[1,3,5,7,9])[7,9]
take(n, expression, name, d)

Take the first n elements from list or range d, replacing variable name with the element from d each time, returning only the elements for which expression evaluates to true.

This operation is lazy - once n elements satisfying the expression have been found, execution stops. You can use this to filter a few elements from a large list, where the condition might take a long time to calculate.

Note

Do not use i or e as the variable name to map over - they’re already defined as mathematical constants!

Definitions:
Example:
• take(3,gcd(x,6)=1,x,10..30)[11,13,17]
let(name, definition, ..., expression)
let(definitions, expression)

Evaluate expression, temporarily defining variables with the given names. Use this to cut down on repetition. You can define any number of variables - in the first calling pattern, follow a variable name with its definition. Or you can give a dictionary mapping variable names to their values. The last argument is the expression to be evaluated.

Definitions:
Examples:
• let([a,b,c],[1,5,6],d,sqrt(b^2-4*a*c), [(-b+d)/2, (-b-d)/2])[-2,-3] (when [a,b,c] = [1,5,6])
• let(x,1, y,2, x+y)3
• let(["x": 1, "y": 2], x+y)3
sort(x)

Sort list x.

Definitions:
Example:
• sort([4,2,1,3])[1,2,3,4]
sort_destinations(x)

Return a list giving the index that each entry in the list will occupy after sorting.

Definitions:
Example:
• sort_destinations([4,2,1,3])[3,1,0,2]
• sort_destinations([1,2,3,4])[0,1,2,3]
sort_by(key, list)

Sort the given list of either list or dict values by their entries corresponding to the given key. When sorting a list of lists, the key is a number representing the index of each list to look at. When sorting a list of dictionaries, the key is a string.

Definitions:
Examples:
• sort_by(0, [[5,0], [3,2], [4,4]])[[3,2], [4,4], [5,0]]
• sort_by("width", [["label": "M", "width": 20], ["label": "L", "width": 30], ["label": "S", "width": 10]])[["label": "S", "width": 10], ["label": "M", "width": 20], ["label": "L", "width": 30]]
group_by(key, list)

Group the entries in the given list of either list or dict values by their entries corresponding to the given key. The returned value is a list of lists of the form [key, group], where key is the value all elements of the list group have in common.

When grouping a list of lists, the key argument is a number representing the index of each list to look at. When grouping a list of dictionaries, the key argument is a string.

Definitions:
Examples:
• group_by(0, [[0,0], [3,2], [0,4]])[[0, [[0,0], [0,4]]], [3, [[3,2]]]]
• group_by("a", [["a": 1, "b": "M"], ["a": 2, "b": "S"], ["a": 1, "b": "XL"]])[[1,[["a": 1, "b": "M"], ["a": 1, "b": "XL"]]], [2, [["a": 2, "b": "S"]]]]
reverse(x)

Reverse list x.

Definitions:
Example:
• reverse([1,2,3])[3,2,1]
indices(list, value)

Find the indices at which value occurs in list.

Definitions:
Examples:
• indices([1,0,1,0],1)[0,2]
• indices([2,4,6],4)
• indices([1,2,3],5)[]
distinct(x)

Return a copy of the list x with duplicates removed.

Definitions:
Example:
• distinct([1,2,3,1,4,3])[1,2,3,4]
list(x)

Convert a value to a list of its components (or rows, for a matrix).

Definitions:
Examples:
• list(set(1,2,3))[1,2,3] (note that you can’t depend on the elements of sets being in any order)
• list(vector(1,2))[1,2]
• list(matrix([1,2],[3,4]))[[1,2], [3,4]]
make_variables(definitions)

Evaluate a dictionary of variable definitions and return a dictionary containing the generated values.

definitions is a dictionary mapping variable names to expression values corresponding to definitions.

The definitions can refer to other variables to be evaluated, or variables already defined in the current scope. Variables named in the dictionary which have already been defined will be removed before evaluation begins.

Definitions:
Example:
• make_variables(["a": expression("random(1..5)"), "b": expression("a^2")]) ["a": 3, "b": 9]
satisfy(names, definitions, conditions, maxRuns)

Each variable name in names should have a corresponding definition expression in definitions. conditions is a list of expressions which you want to evaluate to true. The definitions will be evaluated repeatedly until all the conditions are satisfied, or the number of attempts is greater than maxRuns. If maxRuns isn’t given, it defaults to 100 attempts.

Note

This function is deprecated, and retained only for backwards compatibility. Use make_variables() instead.

Definitions:
Example:
• satisfy([a,b,c],[random(1..10),random(1..10),random(1..10)],[b^2-4*a*c>0])
sum(numbers)

Add up a list of numbers

Definitions:
Example:
• sum([1,2,3])6
• sum(vector(4,5,6))15
prod(list)

Multiply a list of numbers together

Definitions:
Example:
• prod([2,3,4])24
product(list1, list2, ..., listN) or product(list, n)

Cartesian product of lists. In other words, every possible combination of choices of one value from each given list.

If one list and a number are given, then the n-th Cartesian power of the list is returned: the Cartesian product of n copies of the list.

Definitions:
Example:
• product([1,2],[a,b])[ [1,a], [1,b], [2,a], [2,b] ]
• product([1,2],2)[ [1,1], [1,2], [2,1], [2,2] ]
zip(list1, list2, ..., listN)

Combine two (or more) lists into one - the Nth element of the output is a list containing the Nth elements of each of the input lists.

Definitions:
Example:
• zip([1,2,3],[4,5,6])[ [1,4], [2,5], [3,6] ]
combinations(collection, r)

All ordered choices of r elements from collection, without replacement.

Definitions:
Example:
• combinations([1,2,3],2)[ [1,2], [1,3], [2,3] ]
combinations_with_replacement(collection, r)

All ordered choices of r elements from collection, with replacement.

Definitions:
Example:
• combinations_with_replacement([1,2,3],2)[ [1,1], [1,2], [1,3], [2,2], [2,3], [3,3] ]
permutations(collection, r)

All choices of r elements from collection, in any order, without replacement.

Definitions:
Example:
• permutations([1,2,3],2)[ [1,2], [1,3], [2,1], [2,3], [3,1], [3,2] ]

### Dictionaries¶

dict[key]

Get the value corresponding to the given key string in the dictionary d.

If the key is not present in the dictionary, an error will be thrown.

Definitions:
Example:
• ["a": 1, "b": 2]["a"]1
get(dict, key, default)

Get the value corresponding to the given key string in the dictionary.

If the key is not present in the dictionary, the default value will be returned.

Definitions:
Examples:
• get(["a":1], "a", 0)1
• get(["a":1], "b", 0)0
dict(a:b, c:d, ...)
dict(pairs)

Create a dictionary with the given key-value pairs. Equivalent to [ .. ], except when no key-value pairs are given: [] creates an empty list instead.

You can alternately pass a list of pairs of the form [key, value], to transform a list into a dictionary.

Definitions:
Examples:
• dict()
• dict("a": 1, "b": 2)
• dict([ ["a",1], ["b",2] ])
keys(dict)

A list of all of the given dictionary’s keys.

Definitions:
Example:
• keys(["a": 1, "b": 2, "c": 1])["a","b","c"]
values(dict[, keys])

A list of the values corresponding to each of the given dictionary’s keys.

If a list of keys is given, only the values corresponding to those keys are returned, in the same order.

Definitions:
Examples:
• values(["a": 1, "b": 2, "c": 1])[1,2,1]
• values(["a": 1, "b": 2, "c": 3], ["b","a"])[2,1]
items(dict)

A list of all of the [key,value] pairs in the given dictionary.

Definitions:
Example:
• items(["a": 1, "b": 2, "c": 1])[ ["a",1], ["b",2], ["c",1] ]

### Sets¶

set(a,b,c,...) or set([elements])

Create a set with the given elements. Either pass the elements as individual arguments, or as a list.

Definitions:
Examples:
• set(1,2,3)
• set([1,2,3])
union(a, b)

Union of sets a and b

Definitions:
Examples:
• union(set(1,2,3),set(2,4,6))set(1,2,3,4,6)
• set(1,2,3) or set(2,4,6)set(1,2,3,4,6)
intersection(a, b)

Intersection of sets a and b, i.e. elements which are in both sets.

Definitions:
Examples:
• intersection(set(1,2,3),set(2,4,6))set(2)
• set(1,2,3) and set(2,4,6)set(2)
a-b

Set minus - elements which are in a but not b

Example:
• set(1,2,3,4) - set(2,4,6)set(1,3)

### Randomisation¶

random(x)

Pick uniformly at random from a range, list, or from the given arguments.

Definitions:
Examples:
• random(1..5)
• random([1,2,4])
• random(1,2,3)
deal(n)

Get a random shuffling of the integers $$[0 \dots n-1]$$

Definitions:
Example:
• deal(3) [2,0,1]
shuffle(x) or shuffle(a..b)

Random shuffling of list or range.

Definitions:
Examples:
• shuffle(["a","b","c"]) ["c","b","a"]
• shuffle(0..4) [2,3,0,4,1]

### Control flow¶

award(a, b)

Return a if b is true, else return 0.

Definitions:
Example:
• award(5,true)5
if(p, a, b)

If p is true, return a, else return b. Only the returned value is evaluated.

Definitions:
Example:
• if(false,1,0)0
switch(p1, a1, p2, a2, ..., pn, an, d)

Select cases. Alternating boolean expressions with values to return, with the final argument representing the default case. Only the returned value is evaluated.

Definitions:
Examples:
• switch(true,1,false,0,3)1
• switch(false,1,true,0,3)0
• switch(false,1,false,0,3)3
assert(condition, value)

If condition is false, then return value, otherwise don’t evaluate value and return false. This is intended for use in marking scripts, to apply marking feedback only if a condition is met.

Definitions:
Example:
• assert(studentAnswer<=0, correct("Student answer is positive"))
try(expression, name, except)

Try to evaluate expression. If it is successfully evaluated, return the result. Otherwise, evaluate except, with the error message available as name.

Definitions:
Examples:
• try(eval(expression("x+")),err, "Error: "+err)"Error: Not enough arguments for operation <code>+</code>"
• try(1+2,err,0)3

### HTML¶

html(x)

Parse string x as HTML.

Definitions:
Example:
• html('<div>Text!</div>')
isnonemptyhtml(str)

Does str represent a string of HTML containing text? Returns false for the empty string, or HTML elements with no text content.

Definitions:
Examples:
• isnonemptyhtml("<p>Yes</p>")true
• isnonemptyhtml("<p></p>")false
table(data), table(data, headers)

Create an HTML with cell contents defined by data, which should be a list of lists of data, and column headers defined by the list of strings headers.

Definitions:
Examples:
• table([[0,1],[1,0]], ["Column A","Column B"])
• table([[0,1],[1,0]])
image(url)

Create an HTML img element loading the image from the given URL. Images uploaded through the resources tab are stored in the relative URL resources/images/<filename>.png, where <filename> is the name of the original file.

Definitions:
Examples:

### JSON¶

JSON is a lightweight data-interchange format. Many public data sets come in JSON format; it’s a good way of encoding data in a way that is easy for both humans and computers to read and write.

For an example of how you can use JSON data in a Numbas question, see the exam Working with JSON data.

json_decode(json)

Decode a JSON string into JME data types.

JSON is decoded into numbers, strings, booleans, lists, or dictionaries. To produce other data types, such as matrices or vectors, you will have to post-process the resulting data.

Warning

The JSON value null is silently converted to an empty string, because JME has no “null” data type. This may change in the future.

Definitions:
Example:
• json_decode(safe(' {"a": 1, "b": [2,true,"thing"]} '))["a": 1, "b": [2,true,"thing"]]
json_encode(data)

Convert the given object to a JSON string.

Numbers, strings, booleans, lists, and dictionaries are converted in a straightforward manner. Other data types may behave unexpectedly.

Definitions:
Example:
• json_encode([1,"a",true])"[1,\"a\",true]"

### Sub-expressions¶

expression(string)

Parse a string as a JME expression. The expression can be substituted into other expressions, such as the answer to a mathematical expression part, or the \simplify LaTeX command.

parse(string) is a synonym for expression(string).

Definitions:
Example:
eval(expression, values)

Evaluate the given sub-expression.

If values is given, it should be a dictionary mapping names of variables to their values.

Definitions:
Example:
• eval(expression("1+2"))3
• eval(expression("x+1"), ["x":1])2
args(expression)

Returns the arguments of the top-level operation of expression, as a list of sub-expressions. If expression is a data type other than an operation or function, an empty list is returned.

Binary operations only ever have two arguments. For example, 1+2+3 is parsed as (1+2)+3.

Definitions:
Examples:
• args(expression("f(x)"))[expression("x")]
• args(expression("1+2+3"))[expression("1+2"), expression("3")]
• args(expression("1"))[]
type(expression)

Returns the name of the data type of the top token in the expression, as a string.

Definitions:
Examples:
• type(expression("x"))"name"
• type(expression("1"))"integer"
• type(expression("x+1"))"op"
• type(expression("sin(x)"))"function"
name(string)

Construct a name token with the given name.

Definitions:
Example:
• name("x")x
op(name)

Construct an operator with the given name.

Definitions:
Example:
• op("+") +
function(name)

Construct a function token with the given name.

Definitions:
Example:
• function("sin") sin
exec(op, arguments)

Returns a sub-expression representing the application of the given operation to the list of arguments.

Definitions:
Example:
• exec(op("+"), [2,1])expression("2+1")
• exec(op("-"), [2,name("x")])expression("2-x")
findvars(expression)

Return a list of all unbound variables used in the given expression. Effectively, this is all the variables that need to be given values in order for this expression to be evaluated.

Bound variables are those defined as part of operations which also assign values to those variables, such as map or let.

Definitions:
Examples:
• findvars(expression("x+1"))["x"]
• findvars(expression("x + x*y"))["x","y"]
• findvars(expression("map(x+2, x, [1,2,3])"))[]
substitute(variables, expression)

Substitute the given variable values into expression.

variables is a dictionary mapping variable names to values.

Definitions:
Examples:
• substitute(["x": 1], expression("x + y"))expression("1 + y")
• substitute(["x": 1, "y": expression("sqrt(z+2)")], expression("x + y"))expression("1 + sqrt(z + 2)")
simplify(expression, rules)

Apply the given simplification rules to expression, until no rules apply.

rules is a list of names of rules to apply, given either as a string containing a comma-separated list of names, or a list of strings.

Unlike the \simplify command in content areas, the basic rule is not turned on by default.

See Substituting variables into displayed maths for a list of rules available.

Definitions:
Examples:
• simplify(expression("1*x+cos(pi)"),"unitfactor")expression("x+cos(pi)")
• simplify(expression("1*x+cos(pi)"),["basic","unitfactor","trig"])expression("x-1")
canonical_compare(expr1, expr2)

Compare expressions a and b using the “canonical” ordering. Returns -1 if a should go before b, 0 if they are considered “equal”, and 1 if a should go after b.

Expressions are examined in the following order:

• Names used: all variable names used in each expression are collected in a depth-first search and the resulting lists are compared lexicographically.
• Data type: if a and b are of different data types, op and function go first, and then they are compared using the names of their data types.
• Polynomials: terms of the form x^b or a*x^b, where a and b are numbers and x is a variable name, go before anything else.
• Function name: if a and b are both function applications, they are compared using the names of the functions. If the functions are the same, the arguments are compared. Powers, or multiples of powers, go after anything else.
• Number: if a and b are both numbers, the lowest number goes first. Complex numbers are compared by real part and then by imaginary part.
• Elements of other data types are considered to be equal to any other value of the same data type.
Definitions:
Examples:
• canonical_compare(a,b)-1
• canonical_compare(f(y),g(x))1
• canonical_compare(f(x),g(x))-1
• canonical_compare("a","b")0
numerical_compare(a, b)

Compare expression a and b by substituting random values in for the free variables.

Returns true if a and b have exactly the same free variables, and produce the same results when evaluated against the randomly chosen values.

For more control over the evaluation, see resultsequal().

Definitions:
Example:
• numerical_compare(expression("x^2"), expression("x*x"))true
• numerical_compare(expression("x^2"), expression("2x"))false
• numerical_compare(expression("x^2"), expression("y^2"))false

### Pattern-matching sub-expressions¶

match(expr, pattern, options)

If expr matches pattern, return a dictionary of the form ["match": boolean, "groups": dict], where "groups" is a dictionary mapping names of matches to sub-expressions.

If you don’t need to use any parts of the matched expression, use matches() instead.

Definitions:
Examples:
• match(expression("x+1"),"?;a + ?;b")["match": true, "groups": ["a": expression("x"), "b": expression("1"), "_match": expression("x+1")]]
• match(expression("sin(x)"), "?;a + ?;b")["match": false, "groups": dict()]
• match(expression("x+1"),"1+?;a")["match": true, "groups": ["a": expression("x"), "_match": expression("x+1")]]
matches(expr, pattern, options)

Return true if expr matches pattern.

Use this if you’re not interested in capturing any parts of the matched expression.

Definitions:
Examples:
• matches(expression("x+1"),"?;a + ?;b")true
• matches(expression("sin(x)"), "?;a + ?;b")false
replace(pattern, replacement, expr)

Replace occurrences of pattern in expr with the expression created by substituting the matched items into replacement.

Definitions:
Examples:
• replace("?;x + ?;y", "x*y", expression("1+2"))expression("1*2")
• replace("?;x + ?;y", "f(x,y)", expression("1+2+3"))expression("f(f(1,2),3)")
• replace("0*?", "0", expression("0*sin(x) + x*0 + 2*cos(0*pi)"))expression("0 + 0 + 2*cos(0)")

### Identifying data types¶

type(x)

Returns the name of the data type of x.

Example:
• type(1)"integer"
x isa type

Returns true if x is of the data type type.

Definitions:
Examples:
• 1 isa "number"true
• x isa "name"true (if x is not defined in this scope)
• x isa "number" true (if x has a numerical value in this scope)
x as type

Convert x to the given data type, if possible.

If x can not be automatically converted to type, an error is thrown.

Definitions:
Examples:
• dec(1.23) as "number"1.23
• set(1,2,3) as "list"[1,2,3]
infer_variable_types(expression)

Attempt to infer the types of free variables in the given expression.

There can be more than one valid assignment of types to the variables in an expression. For example, in the expression a+a, the variable a can be any type which has a defined addition operation.

Returns the first possible assignment of types to variables, as a dictionary mapping variable names to the name of its type. If a variable name is missing from the dictionary, the algorithm can’t establish any constraint on it.

Definitions:
Examples:
• infer_variable_types(expression("x^2"))["x": "number"]
• infer_variable_types(expression("union(a,b)"))["a": "set", "b": "set"]
• infer_variable_types(expression("k*det(a)"))[ "k": "number", "a": "matrix" ]
infer_type(expression)

Attempt to infer the type of the value produced by the given expression, which may contain free variables.

First, the types of any free variables are inferred. Then, definitions of an operations or functions in the function are chosen to match the types of their arguments.

Returns the name of the expression’s output type as a string, or "?" if the type can’t be determined.

Definitions:
Examples:
• infer_type(expression("x+2"))"number"
• infer_type(expression("id(n)"))"matrix"
• infer_type(expression("random(2,true)"))"?"

### Inspecting the evaluation scope¶

definedvariables()

Returns a list containing the names of every variable defined in the current scope, as strings.

Definitions:
isset(name)

Returns true if the variable with the given name has been defined in the current scope.

Definitions:
unset(names, expression)

Temporarily remove the named variables, functions and rulesets from the scope, and evaluate the given expression.

names is a dictionary of the form ["variables": list, "functions": list, "rulesets": list]`.

Definitions: