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.

Syntax¶

Expressions are strings of text, made of variable names, literal values, grouped terms, function applications, operators, collections and indices.

Whitespace (space characters, tabs, newlines, etc.) can be used to separate literal values, for example a 2 is not interpreted the same as a2. For all other purposes, whitespace is ignored.

Variable names¶

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''

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
diff - denote the name as a differential - the name is prefixed with \mathrm{d} when displayed, e.g. $\mathrm{d}x$
degrees - denote the name as representing an angle in degrees - the name has a suffix of ^{\circ} when displayed, e.g. $x^{\circ}$

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.

Literal values¶

boolean, integer, number and string data types can be constructed with literal values.

Examples: true, 1, 4.3, "Numbas"

There are also some built-in constants which are interpreted as number values:

pi or π - the ratio of a circle’s circumference to its diameter;
e - the base of the natural logarithm;
i - the square root of -1;
infinity, infty or ∞ - infinity;
nan - “Not a number”, sometimes returned by JavaScript functions.

You can disable, override or define new constants in the question editor’s Constants tab.

Grouped terms¶

Use parentheses ( ) to group terms. For example:

(a+2)(a+1)

No other symbols can be used to group terms - square brackets [ ] and curly braces { } have other meanings in Numbas.

Function application¶

A name followed immediately by a bracketed group is interpreted as a function application. Function names can be annotated similarly to variables.

A function takes one or more arguments, separated by commas. Each argument is a JME expression.

Examples:

f(x)
g(a,b)

Operators¶

There are three kinds of operators:

Binary¶: A symbol written between two terms, for example a + b (“$a$ plus $b$”). Each binary operator has a precedence which determines when it is evaluated in relation to other operators.
Prefix¶: A symbol written to the left of a term, for example !a (“not $a$”).
Postfix¶: A symbol written to the right of a term, for example a! (“$a$ factorial”).

Relations¶

Some binary operators are marked as relations. Relations can be chained together, for example a<b<c is interpreted as a<b and b<c.

The relation operators are <, <=, >, >=, =, <> and in.

Collections¶

There are two kinds of collection: lists and dictionaries.

Both are written as a series of terms written between square brackets and separated by commas.

For a dictionary, each term is a keypair: a variable name or string followed by a colon and an expression. For example, [a: 1, "first name": "Owen"] is a dictionary with keys "a" and "first name".

A collection made of any other kind of term is interpreted as a list.

An empty pair of brackets [] is interpreted as an empty list. To construct an empty dictionary, use dict().

Examples:

[1,2,3]
[a]
[]

Indices¶

Many JME data types support indexing.

An index is a single term inside square brackets immediately following another term.

The first element in a list has index 0.

Negative indices read from the end: the index -1 corresponds to the last item.

Examples:

[1,2,3][0] produces the first element in the list, 1.
x[3..7] produces the fourth to the eighth elements of the list x.
id(4)[1] produces the second row of a $4 \times 4$ identity matrix, vector(0,1,0,0).
info["name"] returns the value corresponding to the key "name" in the dictionary info.
"Numbas"[0] produces the first letter of the string "Numbas", "N".

Implicit multiplication¶

JME supports implicit multiplication in some cases, allowing you to omit the multiplication symbol:

A bracket followed by an :data:integer`, number or name.
An integer, number or name followed by a name.

Examples:

(a+1)2 = (a+1)*2
(x+y)z = (x+y)*z
2x = 2*x
x y = x*y

Warning

Note that a name followed by a bracket is not always interpreted as implicit multiplication. Instead, it’s interpreted as a function application.

To interpret such expressions as products, in a mathematical expression part turn off the Allow unknown function names? option, and when dealing with expression values, use expand_juxtapositions.

Case-sensitivity¶

The default behaviour of variable and function names in JME expressions is that they are considered case-insensitively: two names are considered equivalent if they are exactly equal when converted to lower-case.

You can force the JME system to be case-sensitive using the scope_case_sensitive function.

Synonymous keywords and characters¶

JME interprets some keywords and characters as synonyms for others, when there are multiple conventional ways of writing the same thing, and there’s no ambiguity about what they mean.

Often there is a single Unicode character for a mathematical symbol which can also be written in JME as a combination of ASCII characters.

Keyword	Synonyms
`and`	`&`, `&&`, `∧`
`or`	`\|\|`, `∨`
`not`	`¬`
`\|`	`divides`
`*`	`×`
`/`	`÷`
`in`	`∈`
`implies`	`⟹`
`<>`	`≠`
`>=`	`≥`
`<=`	`≤`
`^`	`ˆ`
`sqrt`	`sqr`
`gcd`	`gcf`
`sign`	`sgn`
`abs`	`len`, `length`
`dec`	`decimal`

Superscript characters are interpreted as exponents, without the ^ character. For example:

x⁻² = x^(-2)

The following superscript characters are recognised:

⁰ ¹ ² ³ ⁴ ⁵ ⁶ ⁷ ⁸ ⁹ ⁽ ⁾ ⁺ ⁻ ⁼ ⁿ ⁱ

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 normally defined as the imaginary unit, the base of the natural logarithm, ∞ and π, respectively. Within a question you can remove or override these using the Constants tab.

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:

decimal

integer¶

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

Examples: 0, 1, -2, 431.

Automatically converts to:

number
rational
decimal

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:

number
decimal

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 loss of precision for very big or very small numbers.

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

Automatically converts to:

number

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:

list - a list of number values corresponding to the numbers included in the range. If the step size is zero, an error is thrown.

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:

list

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:

list - a list of number values corresponding to the components of the vector.

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.

To retrieve the n th row of a matrix m, write m[n]. The row is returned as a vector value. To retrieve the cell in row a and column b, write m[a][b]. Rows and columns are both numbered starting from zero.

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

See functions related to Vector and matrix arithmetic.

Automatically converts to:

list - a list of vector values corresponding to the rows of the matrix.

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 `number`.
`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 [2]`	`list`	`except()` is only defined on `list` values, so the `set` is converted to a `list` automatically.

Function reference¶

Arithmetic ¶

x+y¶

Addition.

Definitions:

number, number → number
list, list → list - concatenate two lists
list, anything → list - add an item to the end of a list
dict, dict → dict - merge two dictionaries, with values from the right-hand side taking precedence when the same key is present in both dictionaries.
string, anything → string - convert the right-hand argument to a string, and concatenate
anything, string → string - convert the left-hand argument to a string, and concatenate
vector, vector → vector
matrix, matrix → matrix
integer, integer → integer
rational, rational → rational
decimal, decimal → decimal
number, decimal → decimal

Examples:

1+2 → 3
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:

number, number → number
vector, vector → vector
matrix, matrix → matrix
integer, integer → integer
rational, rational → rational
decimal, decimal → decimal
number, decimal → decimal
set, set → set

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:

number, number → number
number, vector → vector
vector, number → vector
matrix, vector → vector
number, matrix → matrix
matrix, number → matrix
matrix, matrix → matrix
vector, matrix → vector
integer, integer → integer
rational, rational → rational
decimal, decimal → decimal
number, decimal → decimal

Examples:

1*2 → 2
2*vector(1,2,3) → vector(2,4,6)
matrix([1,2],[3,4])*2 → matrix([2,4],[6,8])
matrix([1,2],[3,4])*vector(1,2) → vector(5,11)

x/y¶

Division. Only defined for numbers.

Definitions:

number, number → number
matrix, number → matrix
vector, number → vector
integer, integer → rational
rational, rational → rational
decimal, decimal → decimal
number, decimal → decimal

Example:

1.2/3 → 0.4.

x^y¶

Exponentiation.

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

Definitions:

number, number → number
integer, integer → number
rational, integer → rational
decimal, decimal → decimal

Examples:

3^2 → 9
e^(pi * i) → -1

exp(x)¶

$e^x$ - a synonym for e^x.

Definitions:

number → number

Examples:

exp(1) → e

Number operations ¶

decimal(n)

decimal(x)

dec(x)¶

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

Definitions:

number → decimal
string → decimal

rational(n)

Convert n to a rational number, taking an approximation when necessary.

Definition:

number → rational

Example:

rational(pi) → 355/113

int(n)¶

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

Definitions:

number → integer

Example:

int(3.0) → 3

abs(x)¶

len(x)¶

length(x)¶

Absolute value, length, or modulus.

Definitions:

number → number
string → number - the number of characters
list → number - the number of elements
range → number - the difference between the upper and lower bound
vector → number
dict → number - the number of keys
decimal → decimal
set → number - the number of elements

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:

number → number

Example:

arg(-1) → pi

re(z)¶

Real part of a complex number.

Definitions:

number → number

Example:

re(1+2i) → 1

im(z)¶

Imaginary part of a complex number.

Definitions:

number → number

Example:

im(1+2i) → 2

conj(z)¶

Complex conjugate.

Definitions:

number → number

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:

number → boolean
decimal → boolean

Example:

isint(4.0) → true

iszero(n)¶

Returns true when n is exactly 0.

Definitions:

decimal → boolean

Examples:

iszero(0) → true
iszero(1) → false
iszero(dec(0)) → true
iszero(sin(pi/2)-1) → true

sqrt(x)¶

sqr(x)¶

Square root of a number.

Examples:

sqrt(4) → 2
sqrt(-1) → i

root(x, n)¶

n^th root of x.

Definitions:

number, number → number

Example:

root(8,3) → 2.

ln(x)¶

Natural logarithm.

Definitions:

number → number
decimal → decimal

Example:

ln(e) → 1

log(x, b)¶

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

Definitions:

number → number
number, number → number
decimal → decimal
decimal, decimal → decimal

Example:

log(100) → 2.
log(343,7) → 3.

degrees(x)¶

Convert radians to degrees.

Definitions:

number → number

Example:

degrees(pi/2) → 90

radians(x)¶

Convert degrees to radians.

Example:

radians(180) → pi

sign(x)¶

sgn(x)¶

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

Definitions:

number → number

Examples:

sign(3) → 1
sign(-3) → -1

max(a, b)¶

Greatest of the given numbers.

Definitions:

number, number → number
list of number → number
integer, integer → integer
list of integer → integer
rational, rational → rational
list of rational → rational
decimal, decimal → decimal
list of decimal → decimal

Example:

max(46,2) → 46
max([1,2,3]) → 3

min(a, b)¶

min(numbers)

Least of the given numbers.

Definitions:

number, number → number
list of number → number
integer, integer → integer
list of integer → integer
rational, rational → rational
list of rational → rational
decimal, decimal → decimal
list of decimal → decimal

Example:

min(3,2) → 2
min([1,2,3]) → 1
min(1/2, 2/3) → 1/2

clamp(x, a, b)¶

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

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

Definitions:

number, number, number → number

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:

number, number → number
matrix, number → matrix
vector, number → vector
decimal, integer → decimal

Examples:

precround(pi,5) → 3.14159
precround(21.3,5) → 21.30000
precround(matrix([[0.123,4.56],[54,98.765]]),2) → matrix([0.12,4.56],[54.00,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:

number, number → number
matrix, number → matrix
vector, number → vector
decimal, integer → decimal

Examples:

siground(pi,3) → 3.14
siground(21.3,5) → 21.300
siground(matrix([[0.123,4.56],[54,98.765]]),2) → matrix([0.12,4.6],[54,99])
siground(vector(10/3,20/3,1),2) → vector(3.3,6.7,1.0)

withintolerance(a, b, t)¶

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

Definitions:

number, number, number → boolean

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:

number, number → string
number, number, string → string
decimal, integer → string

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:

string → number
decimal → integer

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:

number, number → string
number, number, string → string
decimal, integer → string

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:

string → number
decimal → integer

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:

string, string, number, boolean → boolean

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

togivenprecision_scientific(str, precisionType, precision)¶

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

This looks only at the significand part.

A significand of the form D.DD is considered to be given to 2 decimal places, or three significant figures.

Trailing zeros must be given: 1.2 is only considered to be given to 1 decimal place, and 1.20 is only considered to be given to 2 decimal places.

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

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

Definitions:

string, string, number, boolean → boolean

Examples:

togivenprecision_scientific("1e2","dp",0) → true
togivenprecision_scientific("1.0e2","dp",0) → false
togivenprecision_scientific("1.0e2","dp",1) → true
togivenprecision_scientific("1e2","sigfig",1) → true
togivenprecision_scientific("1.0e2","sigfig",1) → false
togivenprecision_scientific("1.0e2","sigfig",2) → true
togivenprecision_scientific("1.23e2","sigfig",3) → true
togivenprecision_scientific("1.23e2","dp",2) → true

tonearest(a, b)¶

Round a to the nearest multiple of b.

Definitions:

decimal, decimal → decimal

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:

number, string → string

Example:

formatnumber(1234.567,"eu") → "1.234,567"

scientificnumberlatex(n)¶

Return a LaTeX string representing the given number in scientific notation, $a \times 10^b$.

This function exists because scientific notation may use superscripts, which aren’t easily typeset in plain text.

Definitions:

number → string
decimal → string

Example:

scientificnumberlatex(123) → "1.23 \\times 10^{2}"

scientificnumberhtml(n)¶

Return an HTML element representing the given number in scientific notation, $a \times 10^b$.

This function exists because scientific notation may use superscripts, which aren’t easily typeset in plain text.

Definitions:

number → html
decimal → html

Example:

scientificnumberhtml(123) → html(safe("<span>1.23 × 10<sup>2</sup></span>"))

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:

string, list of string → string

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:

string, list of string → list

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:

string, string → decimal
string, list of string → decimal

Examples:

parsedecimal("1 234,567","si-fr") → dec("1234.567")
parsedecimal("1.001",["si-fr","eu"]) → dec("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:

string, string → number

Example:

parsedecimal_or_fraction("1/2") → dec("0.5")

tobinary(n)¶

Write the given number in binary: base 2.

Definitions:

integer → string

Example:

tobinary(13) → "1101"

tooctal(n)¶

Write the given number in octal: base 8.

Definitions:

integer → string

Example:

tooctal(13) → "15"

tohexadecimal(n)¶

Write the given number in hexadecimal: base 16.

Definitions:

integer → string

Example:

tohexadecimal(44) → "2c"

tobase(n, base)¶

Write the given number in the given base. base can be any integer between 2 and 36.

Definitions:

integer, integer → string

Example:

tobase(13,4) → "31"
tobase(13,5) → "23"
tobase(50,20) → "2a"

frombinary(s)¶

Convert a string representing a number written in binary (base 2) to a integer value.

Definitions:

string → integer

Example:

frombinary("1010") → 10

fromoctal(s)¶

Convert a string representing a number written in octal (base 8) to a integer value.

Definitions:

string → integer

Example:

fromoctal("54") → 44

fromhexadecimal(s)¶

Convert a string representing a number written in hexadecimal (base 16) to a integer value.

Definitions:

string → integer

Example:

fromhexadecimal("b4") → 180

frombase(s, base)¶

Convert a string representing a number written in the given base to a integer value. base can be any integer between 2 and 36.

Definitions:

string, integer → integer

Example:

frombase("b4",20) → 224
frombase("321",5) → 86
frombase("621",5) → NaN

isnan(n)¶

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

Definitions:

number → boolean
decimal → boolean

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:

number → number
decimal → decimal

Examples:

sin(0) → 0
sin(pi/2) → 1

cos(x)¶

Cosine.

Definitions:

number → number
decimal → decimal

Examples:

cos(0) → 1
cos(pi/2) → 0

tan(x)¶

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

Definitions:

number → number
decimal → decimal

Examples:

tan(0) → 0
tan(pi/4) → 1

cosec(x)¶

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

Definitions:

number → number

Examples:

cosec(pi/2) → 1
cosec(pi/6) → 2

sec(x)¶

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

Definitions:

number → number

Examples:

sec(0) → 1
sec(pi/3) → 2

cot(x)¶

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

Definitions:

number → number

Example:

cot(pi/4) → 1

arcsin(x)¶

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

Definitions:

number → number
decimal → decimal

Example:

arcsin(0) → 0
arcsin(1) → 1.5707963268

arccos(x)¶

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

Definitions:

number → number
decimal → decimal

Example:

arccos(1) → 0
arccos(0) → 1.5707963268

arctan(x)¶

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

Definitions:

number → number
decimal → decimal

Example:

arctan(0) → 0
arctan(1) → 0.7853981634

atan2(y, x)¶

The angle in radians between the positive $x$-axis and the line through the origin and $(x,y)$. This is often equivalent to arctan(y/x), except when $x \lt 0$, when $pi$ is either added or subtracted from the result.

Definitions:

number, number → number
decimal, decimal → decimal

Examples:

atan2(0,1) → 0
atan2(sin(1),cos(1)) → 1
atan2(sin(pi/4), cos(pi/4)) / pi → 0.25
atan2(sin(pi/4), -cos(pi/4)) / pi → 0.75

sinh(x)¶

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

Definitions:

number → number
decimal → decimal

Examples:

sinh(0) → 0
sinh(1) → 1.1752011936

cosh(x)¶

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

Definitions:

number → number
decimal → decimal

Examples:

cosh(0) → 1
cosh(1) → 1.5430806348

tanh(x)¶

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

Definitions:

number → number
decimal → decimal

Examples:

tanh(0) → 0
tanh(1) → 0.761594156

cosech(x)¶

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

Definitions:

number → number

Example:

cosech(1) → 0.8509181282

sech(x)¶

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

Definitions:

number → number

Examples:

sech(0) → 1
sech(1) → 0.6480542737

coth(x)¶

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

Definitions:

number → number

Example:

coth(1) → 1.3130352855

arcsinh(x)¶

Inverse of sinh.

Definitions:

number → number
decimal → decimal

Examples:

arcsinh(0) → 0
arcsinh(1) → 0.881373587

arccosh(x)¶

Inverse of cosh.

Definitions:

number → number
decimal → decimal

Examples:

arccosh(1) → 0
arccosh(2) → 1.3169578969

arctanh(x)¶

Inverse of tanh.

Definitions:

number → number
decimal → decimal

Examples:

arctanh(0) → 0
arctanh(0.5) → 0.5493061443

Number theory ¶

x!¶

fact(x)

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

fact(x) is a synonym for x!.

Definitions:

number → number

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:

number → list

Examples

factorise(18) → [1,2]
factorise(70) → [1,0,1,1]

divisors(n)¶

Returns the divisors of n as a list: positive integers $d$ such that $d \| n$.

Definitions:

number → list

Examples

divisors(18) → [1,2,3,6,9,18]

divisors(100) → [1,2,4,5,10,20,25,50,100]

proper_divisors(n)¶

Returns the proper divisors of n as a list: positive integers $d < n$ such that $d \| n$. That is, the divisors of n, excluding n itself.

Definitions:

number → list

Examples

proper_divisors(18) → [1,2,3,6,9]

proper_divisors(100) → [1,2,4,5,10,20,25,50]

largest_square_factor(n)¶

The largest perfect square factor of the given number.

When the prime factorisation of $n$ is $p_1^{x_1} \times \ldots \times p_k^{x_k}$, the largest perfect square factor is p_1^{2 lfloor x_1/2 rfloor} times … times p_k^{2 lfloor x_k/2}.

Definitions:

number → number

Examples

largest_square_factor(15) → 1
largest_square_factor(18) → 9
largest_square_factor(144) → 144

gamma(x)¶

Gamma function.

Definitions:

number → number

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:

number → number
decimal → decimal

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:

number → number
decimal → decimal

Example:

floor(3.5) → 3

round(x)¶

Round to the nearest integer. 0.5 is rounded up.

Definitions:

number → number
decimal → decimal

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:

number → number
decimal → decimal

Example:

trunc(3.3) → 3
trunc(-3.3) → -3

fract(x)¶

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

Definitions:

number → number
decimal → decimal

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:

number → list
number, number → list

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:

number, number → number
integer, integer → integer
decimal, decimal → decimal

Example:

mod(5,3) → 2

perm(n, k)¶

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

Definitions:

number, number → number

Example:

perm(5,2) → 20

comb(n, k)¶

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

Definitions:

number, number → number

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:

number, number → number

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:

number, number → number

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:

number, number → boolean

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:

number, number → number
list of number → number

Examples

lcm(8,12) → 24
lcm(8,12,5) → 120

x|y¶

x divides y

x divides y.

Definitions:

number, number → boolean

Example:

4|8 → true

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:

multiple number → vector
list of number → vector

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:

list of vector → matrix
list of list of number → matrix
list of number → matrix - a matrix with one row.
multiple list of number → matrix

Examples:

matrix([1,2],[3,4])
matrix([[1,2],[3,4]])

id(n)¶

Identity matrix with $n$ rows and columns.

Definitions:

number → matrix

Example:

id(3) → matrix([1,0,0],[0,1,0],[0,0,1])

numrows(matrix)¶

The number of rows in the given matrix

Definitions:

matrix → number

Example:

numrows(matrix([1,2],[3,4],[5,6])) → 3

numcolumns(matrix)¶

The number of columns in the given matrix

Definitions:

matrix → number

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:

multiple number → matrix
list of number → matrix

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:

vector, vector → number
matrix, vector → number
vector, matrix → number
matrix, matrix → number

Examples:

dot(vector(1,2,3),vector(4,5,6)) → 32
dot(matrix([1],[2]), matrix([3],[4])) → 11

cross(x, y)¶

Cross product. Inputs can be vectors or column matrices.

Definitions:

vector, vector → vector
matrix, vector → vector
vector, matrix → vector
matrix, matrix → vector

Examples:

cross(vector(1,2,3),vector(4,5,6)) → vector(-3,6,-3)
cross(matrix([1],[2],[3]), matrix([4],[5],[6])) → 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:

vector, vector → number

Example:

angle(vector(1,0),vector(0,1)) → 1.5707963268

is_zero(x)¶

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

Definitions:

vector → boolean

Example:

is_zero(vector(0,0,0)) → true

is_scalar_multiple(u, v[, rel_tol][, abs_tol])¶

Returns true if u is a scalar multiple of v. That is, if u = k*v for some real number k.

The optional arguments rel_tol and abs_tol specify the relative and absolute tolerance of the equality check for each component; see isclose.

Definitions:

vector, vector, number, number → boolean

Example:

is_scalar_multiple(vector(1,2,3), vector(2,4,6)) → true
is_scalar_multiple(vector(1,2,3), vector(3,4,5)) → false
is_scalar_multiple(vector(1.01,2.01,3.01), vector(2,4,6), 0.1, 0.1) → true

det(x)¶

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

Definitions:

matrix → number

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:

vector → matrix - returns a single-row matrix.
matrix → matrix

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:

matrix → number

Example:

sum_cells(matrix([1,2],[3,4])) → 10

augment(m1, m2)¶

combine_horizontally(m1, m2)¶

Combine two matrices horizontally: given a $r_1 \times c_1$ matrix m1 and a $r_2 \times c_2$ matrix m2, returns a new $\max(r_1,r_2) \times (c_1+c_2)$ matrix formed by putting the two matrices side, and padding with zeros where necessary.

Definitions:

matrix, matrix → matrix

Example:

augment(id(2), matrix([3],[4],[5])) → matrix([1,0,3],[0,1,4],[0,0,5])

stack(m1, m2)¶

combine_vertically(m1, m2)¶

Combine two matrices vertically: given a $r_1 \times c_1$ matrix m1 and a $r_2 \times c_2$ matrix m2, returns a new $(r_1 + r_2) \times \max(c_1,c_2)$ matrix formed by putting m1 above m2, and padding with zeros where necessary.

Definitions:

matrix, matrix → matrix

Example:

stack(id(3), matrix([3,4])) → matrix([1,0,0],[0,1,0],[0,0,1],[3,4,0])

combine_diagonally(m1, m2)¶

Combine two matrices diagonally: given a $r_1 \times c_1$ matrix m1 and a $r_2 \times c_2$ matrix m2, returns a new $(r_1 + r_2) \times (c_1 + c_2)$ matrix whose top-left quadrant is m1 and bottom-right quadrant is m2.

Definitions:

matrix, matrix → matrix

Example:

combine_diagonally(id(3), matrix([3,4],[5,6])) → matrix([1,0,0,0,0],[0,1,0,0,0],[0,0,1,0,0],[0,0,0,3,4],[0,0,0,5,6])

Strings ¶

x[n]¶

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

Example:

"hello"[1] → "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.

When converting a expression value to a string, you can give a list of display options as a second argument, either as a comma-separated string or a list of strings.

Definitions:

number → string - rendered using the plain-en notation style.
integer → string
rational → string
decimal → string
name → string
expression → string
expression, string or list of string → string

Example:

string(123) → "123"
string(x) → "x"
string(expression("0.5")) → "0.5"
string(expression("0.5"),"fractionNumbers") → "1/2"

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.

If x is a expression value, it’s rendered to LaTeX.

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

Definitions:

string → string
expression → string

Example:

latex('\\frac{1}{2}').
latex(expression("x^2 + 3/4")) → "x^{2} + \\frac{3}{4}"

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:

string → string

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:

string, optional dict → string

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:

string → string

Example:

capitalise('hello there') → "Hello there"

pluralise(n, singular, plural)¶

Return singular if n is 1, otherwise return plural.

Definitions:

number, string, string → string

Example:

pluralise(0,"thing","things") → "things"
pluralise(1,"thing","things") → "thing"
pluralise(2,"thing","things") → "things"

upper(x)¶

Convert string to upper-case.

Definitions:

string → string

Example:

upper('Hello there') → "HELLO THERE"

lower(x)¶

Convert string to lower-case.

Definitions:

string → string

Example:

lower('CLAUS, Santa') → "claus, santa"

join(strings, delimiter)¶

Join a list of strings with the given delimiter.

Definitions:

list, string → string

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:

string, string → list

Example:

split("a,b,c,d",",") → ["a","b","c","d"]

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. If it’s not given, the default value of "u" is used.

Definitions:

string, string → list
string, string, string → list

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"]

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.

flags is an optional string listing the options flags to use. If it’s not given, the default value of "u" is used.

Definitions:

string, string → list
string, string, string → list

Example:

split_regex("a, b,c, d ",", *") → ["a","b","c","d"]
split_regex("this and that AND THIS"," and ","i") → ["this","that","THIS"]

replace_regex(pattern, replacement, string, flags)¶

Replace a substring of string matching the given regular expression pattern with the string replacement.

flags is an optional string listing the options flags to use. If it’s not given, the default value of "u" is used.

Remember that backslashes must be doubled up inside JME strings, and curly braces are normally used to substitute in variables. You can use the safe() function to avoid this behaviour.

To replace all occurrences of the pattern, add the flag "g".

Definitions:

string, string, string → string
string, string, string, string`→ :data:`string

Example:

replace_regex("day","DAY","Monday Tuesday Wednesday") → "MonDAY Tuesday Wednesday"
replace_regex("day","DAY","Monday Tuesday Wednesday","g") → "MonDAY TuesDAY WednesDAY"
replace_regex("a","o","Aardvark") → "Aordvark"
replace_regex("a","o","Aardvark","i") → "oardvark"
replace_regex("a","o","Aardvark","ig") → "oordvork"
replace_regex(safe("(\\d+)x(\\d+)"),"$1 by $2","32x24") → "32 by 24"
replace_regex(safe("a{2}"),"c","a aa aaa") → "a c aaa"

trim(str)¶

Remove whitespace from the start and end of str.

Definitions:

string → string

Example:

trim(" a string ") → "a string"

currency(n, prefix, suffix)¶

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

Definitions:

number, string, string → string

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:

number, string → string

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:

string → number

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:

string, number, string → string

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:

string, number, string → string

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:

string, list → string

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:

number → string

Examples:

letterordinal(0) → "a"
letterordinal(1) → "b"
letterordinal(26) → "aa"

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:

string → string
string, dict → string

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:

string → boolean

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:

number, number → boolean
decimal, decimal → boolean

Examples:

4 < 5 → true
-4 < -5 → false

x>y¶

Returns true if x is greater than y.

Definitions:

number, number → boolean
decimal, decimal → boolean

Examples:

5 > 4 → true
-5 > -4 → false

x<=y¶

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

Definitions:

number, number → boolean
decimal, decimal → boolean
decimal, number → boolean

Examples:

3 <= 4 → true
4 <= 4 → true
5 <= 4 → false

x>=y¶

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

Definitions:

number, number → boolean
decimal, decimal → boolean
decimal, number → boolean

Examples:

3 >= 4 → false
4 >= 4 → true
5 >= 4 → true

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:

anything, anything → boolean

Examples:

'this string' <> 'that string' → true
1<>2 → true
'1' <> 1 → true
1 <> 1 → false

x=y¶

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

Definitions:

anything, anything → boolean

Examples:

vector(1,2) = vector(1,2,0) → true
4.0 = 4 → true
1/3 = 0.3 → false

isclose(x, y[, rel_tol][, abs_tol])¶

Returns true if x is close to y.

The arguments rel_tol and abs_tol are optional, with default values of $10^{-15}$.

Equivalent to the following expression:

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

Definitions:

number, number, number, number → boolean

Examples:

isclose(1/3, 0.3) → false
isclose(1/3, 0.3, 0.01) → false
isclose(1/3, 0.3, 0.1) → true
isclose(1/3, 0.3, 0.01, 0.1) → true
isclose(10/3, 3, 0.01, 0.1) → false

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:

anything, anything, string, number → boolean

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:

boolean, boolean → boolean
set, set → set

Examples:

true and true → true
true && true → true
true & true → true
true and false → false
false and false → false

not x¶

Logical NOT.

Definitions:

boolean → boolean

Examples:

not true → false
not false → true
!true → false

x or y¶

x || 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:

boolean, boolean → boolean
set, set → set - equivalent to union(x,y)

Examples:

true or false → true
false or false → false
true || false → true

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:

boolean, boolean → boolean

Examples:

true XOR false → true
true XOR true → false
false XOR false → 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:

boolean, boolean → boolean

Example:

true implies true → true
true implies false → false
false implies true → true
false implies false → true

Collections ¶

x[y]

Get the y^th element of the collection x.

For matrices, the y^th 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:

dict, string → unspecified
string, number → string
list, number → unspecified
vector, number → number
matrix, number → vector

Examples:

[0,1,2,3][1] → 1
vector(0,1,2)[2] → 2
matrix([0,1,2],[3,4,5],[6,7,8])[0] → 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:

string, range → string
list, range → list
vector, range → vector
matrix, range → matrix

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:

number, range → boolean
string, dict → boolean - returns true if the dictionary has a key x
string, string → boolean
anything, list → boolean
anything, set → boolean

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:

number, number → range

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:

range, number → range

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:

range, range → list
range, list → list - exclude the given list of numbers
range, number → list - exclude the given number
list, range → list - exclude all numbers in the given range
list, list → list
list, anything → list - exclude the given element

Examples:

-2..2 except 0 → [-2,-1,1,2]
-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:

anything, number → list

Example:

repeat(0,3) → [0,0,0]
repeat(random(1..4),5) → [2, 4, 1, 3, 4] (other values can be produced)

all(list)¶

Returns true if every element of list is true.

Definitions:

list of boolean → boolean

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:

list of boolean → boolean

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.

Definitions:

anything, name or list of name, anything → list

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.

Definitions:

anything, name, anything → list

Example:

filter(x>5,x,[1,3,5,7,9]) → [7,9]

foldl(expression, accumulator_name, item_name, first_value, d)¶

Accumulate a value by iterating over a collection. This can be used as an abstraction of routines such as “sum of a list of numbers”, or “maximum value in a list”.

Evaluate expression for each item in the list, range, vector or matrix d, accumulating a single value which is returned.

At each iteration, the variable item_name is replaced with the corresponding value from d. The variable accumulator_name is replaced with first_value for the first iteration, and the result of expression from the previous iteration subsequently.

Definitions:

anything, name, name, anything, anything → unspecified

Examples:

foldl(total + x, total, x, 0, [1,2,3]) → 6
foldl(if(len(x)>len(longest),x,longest), longest, x, "", ["banana","pineapple","plum"]) → "pineapple"

iterate(expression, name, initial, times)¶

Iterate an expression on the given initial value the given number of times, returning a list containing the values produced at each step.

You can also give a list of names. The Nth element of the value will be mapped to the Nth name.

Definitions:

anything, name or list of name, anything, number → list

Example:

iterate(x+1, x, 0, 3) → [0,1,2,3]
iterate([b,a+b], [a,b], [1,1], 3) → [ [1,1], [1,2], [2,3], [3,5] ]
iterate(l[1..len(l)]+[l[0]], l, ["a","b","c"], 3) → [ ["a","b","c"], ["b","c","a"], ["c","a","b"], ["a","b","c"] ]

iterate_until(expression, name, initial, condition, max_iterations)¶

Iterate an expression on the given initial value until the condition is satisfied, returning a list containing the values produced at each step.

You can also give a list of names. The Nth element of the value will be mapped to the Nth name.

max_iterations is an optional parameter specifying the maximum number of iterations that may be performed. If not given, the default value of 100 is used. This parameter prevents the function from running indefinitely, when the condition is never met.

Definitions:

anything, name or list of name, anything, boolean, number → list

Example:

iterate_until(if(mod(x,2)=0,x/2,3x+1), x, 5, x=1) → [ 5, 16, 8, 4, 2, 1 ]
iterate_until([b,mod(a,b)], [a,b], [37,32], b=0) → [ [ 37, 32 ], [ 32, 5 ], [ 5, 2 ], [ 2, 1 ], [ 1, 0 ] ]

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.

Definitions:

number, anything, name, anything → list

Example:

take(3,gcd(x,6)=1,x,10..30) → [11,13,17]

flatten(lists)¶

“Flatten” a list of lists, returning a single list containing the concatenation of all the entries in lists.

Definitions:

list of list → list

Example:

flatten([ [1,2], [3,4] ]) → [1,2,3,4]

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:

dict, anything or multiple name, anything or list of name, list of anything, anything → list

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:

list → list

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:

list → list

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:

number, list of list → list
string, list of dict → list

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:

number, list of list → list
string, list of dict → list

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:

list → list

Example:

reverse([1,2,3]) → [3,2,1]

indices(list, value)

Find the indices at which value occurs in list.

Definitions:

list, anything → list

Examples:

indices([1,0,1,0],1) → [0,2]
indices([2,4,6],4) → [1]
indices([1,2,3],5) → []

distinct(x)¶

Return a copy of the list x with duplicates removed.

Definitions:

list → list

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:

range → list
set → list
vector → list - returns a list of number.
matrix → list - returns a list of lists representing the rows.

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, vRange)¶

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.

If the optional parameter vRange is given, then a variable vRange is defined in the given scope with that value.

Definitions:

dict of expression, range → dict

Example:

make_variables(["a": expression("3"), "b": expression("a^2")]) → ["a": 3, "b": 9]
make_variables(["a": expression("random(1..5)"), "b": expression("a^2")]) → ["a": 3, "b": 9] (other values can be produced)

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:

list, list, list, number → list

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:

list of number → number
vector → number - sum of the components

Example:

sum([1,2,3]) → 6
sum(vector(4,5,6)) → 15

prod(list)¶

Multiply a list of numbers together

Definitions:

list of number → number
vector → number - product of the components

Example:

prod([2,3,4]) → 24

product(list1, list2, ..., listN)¶

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:

multiple list → list
list, number → list

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:

multiple list → list

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:

list, number → list

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:

list, number → list

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:

list, number → list

Example:

permutations([1,2,3],2) → [ [1,2], [1,3], [2,1], [2,3], [3,1], [3,2] ]

frequencies(collection)¶

Count the number of times each distinct element of collection appears.

Returns a list of pairs [value, frequency], where value is a value from the list, and frequency is the number of times it appeared.

Definitions:

list → list

Examples:

frequencies([1,2,3,2,2,1]) → [ [1,2], [2,3], [3,1] ]
frequencies(["a","a","c","b","c","a"]) → [ ["a",3], ["c",2], ["b",1] ]

enumerate(collection)¶

Enumerate the elements of collection: this function returns a list containing, for each element v of collection, a new list of the form [i,v], where i is the index of the element in collection.

Definitions:

list → list

Example:

enumerate(["A","B","C"]) → [ [0,"A"], [1,"B"], [2,"C"] ]

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:

dict, string → unspecified

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:

dict, string, anything → unspecified

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:

multiple keypair → dict

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:

dict → list

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:

dict → list
dict, list of string → list

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:

dict → list

Example:

items(["a": 1, "b": 2, "c": 1]) → [ ["a",1], ["b",2], ["c",1] ]

Sets ¶

set(elements)

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

Definitions:

list → set
multiple anything → set

Examples:

set(1,2,3)
set([1,2,3])

union(a, b)¶

Union of sets a and b

Definitions:

set, set → set

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:

set, set → set

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:

range → number
list → unspecified
multiple anything → unspecified

Examples:

random(1..5)
random([1,2,4])
random(1,2,3)

weighted_random(x)¶

Pick random from a weighted list of items. Each element in the input list is a pair of the form [item, probability], where probability is a number value.

Items with negative weight are ignored.

Definitions:

list of [anything, number] → unspecified

Examples:

weighted_random([ ["a", 1], ["b", 2], ["c", 0.5] ])

deal(n)¶

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

Definitions:

number → list

Example:

deal(3) → [2,0,1] (other values can be produced)

reorder(list, order)¶

Reorder a list given a permutation. The i``th element of the output is the ``order[i]``th element of ``list.

Definitions:

list, list → list

Examples:

reorder([0,1,2,3],[3,2,0,1]) → [3,2,0,1]
reorder(["a","b","c","d"],[3,2,0,1]) → ["d","c","a","b"]

shuffle(x)¶

Random shuffling of list or range.

Definitions:

list → list

Examples:

shuffle(["a","b","c"]) → ["c","b","a"] (other values can be produced)
shuffle(0..4) → [2,3,0,4,1] (other values can be produced)

shuffle_together(lists)¶

Shuffle several lists together - each list has the same permutation of its elements applied. The lists must all be the same length, otherwise an error is thrown.

Definitions:

list → list

Example:

shuffle_together([ ["a","b","c","d"], [0,1,2,3] ]) → [ ["d","a","c","b"], [3,0,2,1] ] (other values can be produced)

random_integer_partition(n, k)¶

Produce a randomly-chosen partition of the integer n into k non-zero parts.

Definitions:

number, number → list

Examples:

random_integer_partition(6,3) → [1, 3, 2] (other values can be produced)

Control flow ¶

award(a, b)¶

Return a if b is true, else return 0.

Definitions:

number, boolean → number

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:

boolean, anything, anything → unspecified

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:

multiple boolean,anything, anything → unspecified

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:

boolean, anything → unspecified

Example:

assert(1 < 2, "oops") → false
assert(1 > 2, "oops") → "oops"
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:

anything, name, anything → unspecified

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:

string → html

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:

string → boolean

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:

list, list of list → html
list → html

Examples:

table([[0,1],[1,0]], ["Column A","Column B"])
table([[0,1],[1,0]])

image(url[, width][, height])¶

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.

The optional width and height parameters specify the size the image should be displayed at, in em units. If only the width is given, the height will be automatically set to maintain the image’s original proportions. 1 em is the width of the letter ‘m’.

If neither width nor height are given, the image is displayed at its original size.

Definitions:

string, optional number, optional number → html

Examples:

image('resources/images/picture.png')
image(chosenimage)
Question using randomly chosen images.

max_width(width, element)¶

Apply a CSS max-width attribute to the given element. You can use this to ensure that an image is not displayed too wide. The given width is in em units.

Definitions:

number, html → html

Example:

max_width(400,html("<p>Text</p>")) → html("<p style=\"max-width: 400em;\">a</p>")

max_height(width, element)¶

Apply a CSS max-height attribute to the given element. You can use this to ensure that an image is not displayed too long. The given height is in em units.

Definitions:

number, html → html

Example:

max_height(400,html("<p>Text</p>")) → html("<p style=\"max-height: 400em;\">a</p>")

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:

string → unspecified

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:

anything → string

Example:

json_encode([1,"a",true]) → "[1,\"a\",true]"

Sub-expressions ¶

The expression data type represents a JME expression. You can use it to store and manipulate expressions symbolically, substituting in other variables before evaluating or displaying to the student.

There are functions to construct sub-expressions from strings of code, or by joining other sub-expressions together as the arguments to operators or functions.

Once you’ve got a sub-expression, you can evaluate it to a normal JME data type, test if it matches a pattern, substitute values or other sub-expressions for free variables, rearrange using simplification rules, or test if it is equivalent to another sub-expression.

expression(string)

parse(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).

Warning

Note that the argument to expression is evaluated using the same rules as any other JME expression, so for example expression("2" + "x") is equivalent to expression("2x"), not expression("2 + x"). A good way to construct a randomised sub-expression is using substitute().

Definitions:

string → expression

Example:

A question using randomly chosen variable names.

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:

expression → unspecified
expression, dict → unspecified

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:

expression → list

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:

expression → string

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:

string → name

Example:

name("x") → x

op(name)

Construct an operator with the given name.

Definitions:

string → op

Example:

op("+") → +

function(name)

Construct a function token with the given name.

Definitions:

string → func

Example:

function("sin") → sin

exec(op, arguments)¶

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

Definitions:

op, list → expression

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:

expression → list

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:

dict, expression → expression

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:

expression, string → expression
expression, list → expression
string, string → expression

Examples:

simplify(expression("1*x+cos(pi)"),"unitfactor") → expression("x+cos(pi)")
simplify(expression("1*x+cos(pi)"),["basic","unitfactor","trig"]) → expression("x-1")

expand_juxtapositions(expression, options)¶

Expand juxtapositions in variable and function names for implicit multiplication of terms or composition of functions. This is to do with strings of letters with no spaces or operator symbols between them.

options is an optional dictionary of settings for the process. It can contain the following keys.

singleLetterVariables - Insist that all variable names consist of a single letter, interpreting longer strings of characters as implicit multiplication.
Greek letters are considered to be one letter long.
noUnknownFunctions - When a name appears before a bracket, but it’s not the name of a defined function, interpret it as a multiplication instead. This does not apply function applications with more than one argument.
implicitFunctionComposition - When several function names are juxtaposed together to form a string that is not the name of a defined function, or several function names are joined with the multiplication symbol *, interpret it as implicity composition of functions.

If options is not given, all of these are turned on.

Variable name annotations, subscripts and primes do not count towards the number of letters in a name.

Definition:

expression → expression
expression, dict → expression

Examples:

expand_juxtapositions(expression("xy")) → expression("x*y")
expand_juxtapositions(expression("x'y")) → expression("x\'*y")
expand_juxtapositions(expression("pizza")) → expression("pi*z*z*a")
expand_juxtapositions(expression("hat:abc")) → expression("hat:a*b*c")
expand_juxtapositions(expression("xcos(x)")) → expression("x*cos(x)")
expand_juxtapositions(expression("lnabs(x)")) → expression("ln(abs(x))")
expand_juxtapositions(expression("ln*abs(x)")) → expression("ln(abs(x))")
expand_juxtapositions(expression("xy"),["singleLetterVariables": false]) → expression("xy")
expand_juxtapositions(expression("x(x+1)")) → expression("x*(x+1)")
expand_juxtapositions(expression("x(x+1)"),["noUnknownFunctions": false]) → expression("x(x+1)")
expand_juxtapositions(expression("ln*abs(x)"),["implicitFunctionComposition": false, "singleLetterVariables": true, "noUnknownFunctions": true]) → expression("l*n*abs(x)")
expand_juxtapositions(expression("xy^z")) → expression("x*y^z")
expand_juxtapositions(expression("xy!")) → expression("x*y!")

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:

anything, anything → number

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:

expression, expression → boolean

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

scope_case_sensitive(expression[, case_sensitive])¶

Set the evaluation scope to be case-sensitive or not, depending on the value of case_sensitive, and then evaluate expression.

If case_sensitive is not given, it defaults to true.

Case-sensitivity affects variable and function names. The names x and X are considered equivalent when not in case-sensitive mode, but are considered to be different when in case-sensitive mode.

Definitions:

expression, boolean → unspecified

Example:

scope_case_sensitive(findvars(expression("x+X"))) → ["X","x"]
scope_case_sensitive(let(x,1,X,2,x+X), true) → 3

Calculus ¶

diff(expression, variable)¶

Differentiate the given expression with respect to the given variable name

Definitions:

expression, string → expression

Example:

diff(expression("x^2 + 2x + 4"), "x") → expression("2x + 2")
diff(expression("x * y + 3x + 2y"), "x") → expression("y + 3")
diff(expression("cos(x^2)"), "x") → expression("-2 * sin(x^2) * x")

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.

See the documentation on pattern-matching mathematical expressions.

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

Definitions:

expression, string → dict
expression, string, string → dict

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:

expression, string → boolean
expression, string, string → boolean

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:

string, string, expression → expression
string, string, expression, string → expression

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:

anything, string → boolean

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:

anything, string → given type

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:

expression → dict

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:

expression → string

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:

() → list

isset(name)¶

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

Definitions:

name → boolean

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:

dict, anything → unspecified

Numbas 7.0 documentation

JME¶

Syntax¶

Variable names¶

Variable name annotations¶

Literal values¶

Grouped terms¶

Function application¶

Operators¶

Relations¶

Collections¶

Indices¶

Implicit multiplication¶

Case-sensitivity¶

Synonymous keywords and characters¶

Data types¶

Automatic data type conversion¶

Function reference¶