JME — Numbas 9.0 documentation Yes Text
Repository
Suggest edit
.rst
JME
Contents
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
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_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
pi
and
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
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
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
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
, 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
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;
- the base of the natural logarithm;
- 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:
)(
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)
Anonymous functions
An anonymous function consists of a sequence of named arguments, in parentheses if necessary, followed by the symbol
->
, and then an expression in terms of the arguments.
It can be used like a named function, or passed as an argument on its own to some functions.
You can match elements of lists passed to an anonymous function with names by putting the names inside square brackets.
names
expression
Examples
(x
->
x+1)(2)
->
defines an anonymous function which adds one to its argument.
()
->
defines an anonymous function which always returns
((x,y)
->
sqrt(x^2
y^2))(3,
4)
(x,y)
->
sqrt(x^2
y^2)
defines an anonymous function which returns the hypotenuse of a right-angled triangle with sides
and
[a,
b]
->
defines an anonymous function which takes a single list argument, and adds the first two entries.
([a,b]
->
b)([1,2])
Operators
There are three kinds of operators:
Binary
A symbol written between two terms, for example
(”
\(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
a
b
<=
>=
<>
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
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,
x[3..7]
produces the fourth to the eighth elements of the list
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
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.
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
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
-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'
"""
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
th row of a matrix
, write
m[n]
. The row is returned as a
vector
value.
To retrieve the cell in row
and column
, 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!
and
lambda
An
anonymous function
Examples
->
2x
(x,y)
->
x+y
html
An HTML DOM node.
Examples
html("
See functions related to
HTML
Warning
Interactive HTML nodes can not be safely copied, so each HTML value should only be used once in a question.
You can mark an HTML node as non-interactive by adding the attribute
data-interactive="false"
to it.
Elements created using the built-in HTML functions are automatically marked as non-interactive.
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
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
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
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"
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])
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*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)
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
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
e^(pi
i)
-1
exp
\(e^x\)
- a synonym for
e^x
Definitions
number
number
Examples
exp(1)
Number operations
decimal
decimal
dec
Construct a
decimal
value.
Any string accepted by
Decimal.js
is accepted.
Definitions
number
decimal
string
decimal
rational
Convert
to a rational number, taking an approximation when necessary.
Definition
number
rational
Example
rational(pi)
355/113
int
Convert
to an integer, rounding to the nearest integer.
Definitions
number
integer
Example
int(3.0)
abs
len
length
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)
abs(3-4i)
abs("Hello")
abs([1,2,3])
len([1,2,3])
len(set([1,2,2]))
length(vector(3,4))
abs(vector(3,4,12))
13
len(["a":
1,
"b":
2,
"c":
1])
arg
Argument of a complex number.
Definitions
number
number
Example
arg(-1)
pi
re
Real part of a complex number.
Definitions
number
number
Example
re(1+2i)
im
Imaginary part of a complex number.
Definitions
number
number
Example
im(1+2i)
conj
Complex conjugate.
Definitions
number
number
Example
conj(1+i)
1-i
isint
Returns
true
if
is an integer - that is, it is real and has no fractional part.
Definitions
number
boolean
decimal
boolean
Example
isint(4.0)
true
iszero
Returns
true
when
is exactly 0.
Definitions
decimal
boolean
Examples
iszero(0)
true
iszero(1)
false
iszero(dec(0))
true
iszero(sin(pi/2)-1)
true
sqrt
sqr
Square root of a number.
Examples
sqrt(4)
sqrt(-1)
root
th
root of
Definitions
number
number
number
Example
root(8,3)
ln
Natural logarithm.
Definitions
number
number
decimal
decimal
Example
ln(e)
log
Logarithm with base
, or base 10 if
is not given.
Definitions
number
number
number
number
number
decimal
decimal
decimal
decimal
decimal
Example
log(100)
log(343,7)
degrees
Convert radians to degrees.
Definitions
number
number
Example
degrees(pi/2)
90
radians
Convert degrees to radians.
Example
radians(180)
pi
sign
sgn
Sign of a number.
Equivalent to
\(\frac{x}{|x|}\)
, or 0 when
is 0.
Definitions
number
number
Examples
sign(3)
sign(-3)
-1
max
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])
min
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)
min([1,2,3])
min(1/2,
2/3)
1/2
clamp
Return the point nearest to
in the interval
\([a,b]\)
Equivalent to
max(a,min(x,b))
Definitions
number
number
number
number
Example
clamp(1,0,2)
clamp(-1,0,2)
clamp(3,0,2)
precround
Round
to
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
Round
to
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)
with_precision
precision
precisionType
Add or remove a
number
value’s precision information.
This function is used in the attempt suspend data process; it’s unlikely you’d want to use it in another context.
Definition
with_precision(3.00,
2,
"dp")
imprecise
Remove a
number
value’s precision information.
Equivalent to
with_precision(n,
nothing,
nothing)
This function is used in the attempt suspend data process; it’s unlikely you’d want to use it in another context.
withintolerance
Returns
true
if
\(b-t \leq a \leq b+t\)
Definitions
number
number
number
boolean
Example
withintolerance(pi,22/7,0.1)
true
withintolerance(1
0.11i,
1/10
i,
0.02)
true
withintolerance(1
0.11i,
1/10
i,
0.02)
false
dpformat
style
Round
to
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
Assuming
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")
countdp("1")
countdp("not
number")
sigformat
style
Round
to
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
Assuming
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")
countsigfigs("100")
countsigfigs("1.0")
countsigfigs("not
number")
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
Round
to the nearest multiple of
Definitions
decimal
decimal
decimal
Example
tonearest(1.234,0.1)
1.2
formatnumber
style
Render the number
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
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
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("
102"))
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"
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
Write the given number in binary: base 2.
Definitions
integer
string
Example
tobinary(13)
"1101"
tooctal
Write the given number in octal: base 8.
Definitions
integer
string
Example
tooctal(13)
"15"
tohexadecimal
Write the given number in hexadecimal: base 16.
Definitions
integer
string
Example
tohexadecimal(44)
"2c"
tobase
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
Convert a string representing a number written in binary (base 2) to a
integer
value.
Definitions
string
integer
Example
frombinary("1010")
10
fromoctal
Convert a string representing a number written in octal (base 8) to a
integer
value.
Definitions
string
integer
Example
fromoctal("54")
44
fromhexadecimal
Convert a string representing a number written in hexadecimal (base 16) to a
integer
value.
Definitions
string
integer
Example
fromhexadecimal("b4")
180
frombase
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
Is
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
Sine.
Definitions
number
number
decimal
decimal
Examples
sin(0)
sin(pi/2)
cos
Cosine.
Definitions
number
number
decimal
decimal
Examples
cos(0)
cos(pi/2)
tan
Tangent:
\(\tan(x) = \frac{\sin(x)}{\cos(x)}\)
Definitions
number
number
decimal
decimal
Examples
tan(0)
tan(pi/4)
cosec
Cosecant:
\(\csc(x) = \frac{1}{sin(x)}\)
Definitions
number
number
Examples
cosec(pi/2)
cosec(pi/6)
sec
Secant:
\(\sec(x) = \frac{1}{cos(x)}\)
Definitions
number
number
Examples
sec(0)
sec(pi/3)
cot
Cotangent:
\(\cot(x) = \frac{1}{\tan(x)}\)
Definitions
number
number
Example
cot(pi/4)
arcsin
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)
arcsin(1)
1.5707963268
arccos
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)
arccos(0)
1.5707963268
arctan
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)
arctan(1)
0.7853981634
atan2
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)
atan2(sin(1),cos(1))
atan2(sin(pi/4),
cos(pi/4))
pi
0.25
atan2(sin(pi/4),
-cos(pi/4))
pi
0.75
sinh
Hyperbolic sine:
\(\sinh(x) = \frac{1}{2} \left( \mathrm{e}^x - \mathrm{e}^{-x} \right)\)
Definitions
number
number
decimal
decimal
Examples
sinh(0)
sinh(1)
1.1752011936
cosh
Hyperbolic cosine:
\(\cosh(x) = \frac{1}{2} \left( \mathrm{e}^x + \mathrm{e}^{-x} \right)\)
Definitions
number
number
decimal
decimal
Examples
cosh(0)
cosh(1)
1.5430806348
tanh
Hyperbolic tangent:
\(\tanh(x) = \frac{\sinh(x)}{\cosh(x)}\)
Definitions
number
number
decimal
decimal
Examples
tanh(0)
tanh(1)
0.761594156
cosech
Hyperbolic cosecant:
\(\operatorname{cosech}(x) = \frac{1}{\sinh(x)}\)
Definitions
number
number
Example
cosech(1)
0.8509181282
sech
Hyperbolic secant:
\(\operatorname{sech}(x) = \frac{1}{\cosh(x)}\)
Definitions
number
number
Examples
sech(0)
sech(1)
0.6480542737
coth
Hyperbolic cotangent:
\(\coth(x) = \frac{1}{\tanh(x)}\)
Definitions
number
number
Example
coth(1)
1.3130352855
arcsinh
Inverse of
sinh
Definitions
number
number
decimal
decimal
Examples
arcsinh(0)
arcsinh(1)
0.881373587
arccosh
Inverse of
cosh
Definitions
number
number
decimal
decimal
Examples
arccosh(1)
arccosh(2)
1.3169578969
arctanh
Inverse of
tanh
Definitions
number
number
decimal
decimal
Examples
arctanh(0)
arctanh(0.5)
0.5493061443
Number theory
fact
Factorial.
When
is not an integer,
\(\Gamma(x+1)\)
is used instead.
fact(x)
is a synonym for
x!
Definitions
number
number
Examples
fact(3)
3!
fact(5.5)
287.885277815
factorise
Factorise
Returns the exponents of the prime factorisation of
as a list.
Definitions
number
list
Examples
factorise(18)
[1,2]
factorise(70)
[1,0,1,1]
divisors
Returns the divisors of
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
Returns the proper divisors of
as a list: positive integers
\(d < n\)
such that
\(d \| n\)
That is, the divisors of
, excluding
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
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)
largest_square_factor(18)
largest_square_factor(144)
144
gamma
Gamma function.
Definitions
number
number
Examples
gamma(3)
gamma(1+i)
0.4980156681
0.1549498283i
ceil
Round up to the nearest integer.
When
is complex, each component is rounded separately.
Definitions
number
number
decimal
decimal
Examples
ceil(3.2)
ceil(-1.3+5.4i)
-1+6i
floor
Round down to the nearest integer.
When
is complex, each component is rounded separately.
Definitions
number
number
decimal
decimal
Example
floor(3.5)
round
Round to the nearest integer.
0.5
is rounded up.
Definitions
number
number
decimal
decimal
Examples
round(0.1)
round(0.9)
round(4.5)
round(-0.5)
trunc
Round towards zero: truncate the number
to the nearest integer or to
decimal places.
If
is positive, round down; if it is negative, round up.
Definitions
number
number
decimal
decimal
Example
trunc(3.3)
trunc(-3.3)
-3
trunc(9.8765,
2)
9.87
fract
Fractional part of a number.
Equivalent to
x-trunc(x)
Definitions
number
number
decimal
decimal
Example
fract(4.3)
0.3
rational_approximation
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
Modulo; remainder after integral division, i.e.
\(a \bmod b\)
Definitions
number
number
number
integer
integer
integer
decimal
decimal
decimal
Example
mod(5,3)
perm
Count permutations, i.e.
\(^n \kern-2pt P_k = \frac{n!}{(n-k)!}\)
Definitions
number
number
number
Example
perm(5,2)
20
comb
Count combinations, i.e.
\(^n \kern-2pt C_k = \frac{n!}{k!(n-k)!}\)
Definitions
number
number
number
Example
comb(5,2)
10
gcd
gcf
Greatest common divisor of integers
and
Can also write
gcf(a,b)
Definitions
number
number
number
Example
gcd(12,16)
gcd_without_pi_or_i
Take out factors of
\(\pi\)
or
\(i\)
from
and
before computing their greatest common denominator.
Definitions
number
number
number
Example
gcd_without_pi_or_i(6*pi,
9)
coprime
Are
and
coprime? True if their
gcd
is
\(1\)
, or if either of
or
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
Lowest common multiple of integers
and
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
divides
divides
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
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]))
numcolumns
matrix
The number of columns in the given matrix
Definitions
matrix
number
Example
numcolumns(matrix([1,2],[3,4],[5,6]))
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
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
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
Angle between vectors
and
, in radians.
Returns
if either
or
has length 0.
Definitions
vector
vector
number
Example
angle(vector(1,0),vector(0,1))
1.5707963268
is_zero
Returns
true
if every component of the vector
is zero.
Definitions
vector
boolean
Example
is_zero(vector(0,0,0))
true
is_scalar_multiple
rel_tol
abs_tol
Returns
true
if
is a scalar multiple of
That is, if
k*v
for some real number
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
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]))
transpose
Matrix transpose.
Definitions
vector
matrix
- returns a single-row matrix.
matrix
matrix
list
of
list
list
of
list
Examples
transpose(matrix([1,2],[3,4]))
matrix([1,3],[2,4])
transpose(vector(1,2,3))
matrix([1,2,3])
transpose([[1,2],
[3,4]])
[[1,3],
[2,4]]
sum_cells
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])
lu_decomposition
Perform LU-decomposition: decompose the given matrix into a lower-triangular matrix
\(L\)
and an upper-triangular matrix
\(U\)
, such that
\(m = LU\)
The matrix must be square.
Returns a list
[L,
U]
Definitions
matrix
list
Example
lu_decomposition(matrix([1,2,3],[4,5,6],[7,8,10]))
matrix([1,0,0],[4,-3,0],[7,-6,1]),
matrix([1,2,3],[0,1,2],[0,0,1])
gauss_jordan_elimination
Perform Gaussian elimination: given a
\(m \times n\)
matrix, where
\(n \geq m\)
, reduce the rows so that the leading coefficient in each row is
\(1\)
, and every column containing a leading coefficient has zeros in every other row.
Definitions
matrix
matrix
Example
gauss_jordan_elimination(matrix([1,2,3,5],[5,6,9,11],[6,9,12,15]))
matrix([1,0,0,-2],[0,1,0,-1],[0,0,1,3])
inverse
Find the inverse of the given square matrix.
If the matrix is not invertible, an error will be thrown.
Definitions
matrix
matrix
Example
inverse(matrix([1,2,3],[5,6,9],[4,8,14]))
matrix([-1.5,0.5,0],[4.25,-0.25,-0.75],[-2,0,0.5])
Strings
Get the Nth character of the string
Indices start at 0.
Example
"hello"[1]
"e"
..
Slice the string
- 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
Convert
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"
jme_string
Convert any jme type
to a string representation.
Definitions
anything
string
Example
jme_string(123)
"123"
jme_string(expression("x+y"))
"x
y"
jme_string(vector(1,2,3))
"vector(1,2,3)"
latex
Mark string
as containing raw LaTeX, so when it’s included in a mathmode environment it doesn’t get wrapped in a
\textrm
environment.
If
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
Mark string
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
values
Substitute variable values into the string
, 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
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"
])
This function is intended for use primarily in content areas.
capitalise
Capitalise the first letter of a string.
Definitions
string
string
Example
capitalise('hello
there')
"Hello
there"
pluralise
singular
plural
Return
singular
if
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
Convert string to upper-case.
Definitions
string
string
Example
upper('Hello
there')
"HELLO
THERE"
lower
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,
",",
*")
["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
aaa"
trim
str
Remove whitespace from the start and end of
str
Definitions
string
string
Example
trim("
string
")
"a
string"
currency
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
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
prefix
Add copies of
prefix
to the start of
str
until the result is at least
characters long.
Definitions
string
number
string
string
Example
lpad("3",
2,
"0")
"03"
rpad
str
suffix
Add copies of
suffix
to the end of
str
until the result is at least
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
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
Returns
true
if
is less than
Definitions
number
number
boolean
decimal
decimal
boolean
Examples
true
-4
-5
false
Returns
true
if
is greater than
Definitions
number
number
boolean
decimal
decimal
boolean
Examples
true
-5
-4
false
<=
Returns
true
if
is less than or equal to
Definitions
number
number
boolean
decimal
decimal
boolean
decimal
number
boolean
Examples
<=
true
<=
true
<=
false
>=
Returns
true
if
is greater than or equal to
Definitions
number
number
boolean
decimal
decimal
boolean
decimal
number
boolean
Examples
>=
false
>=
true
>=
true
<>
Returns
true
if
is not equal to
Returns
true
if
and
are not of the same data type.
Definitions
anything, anything →
boolean
Examples
'this
string'
<>
'that
string'
true
1<>2
true
'1'
<>
true
<>
false
Returns
true
if
is equal to
Returns
false
if
and
are not of the same data type.
Definitions
anything, anything →
boolean
Examples
vector(1,2)
vector(1,2,0)
true
4.0
true
1/3
0.3
false
isclose
rel_tol
abs_tol
Returns
true
if
is close to
The arguments
rel_tol
and
abs_tol
are optional, with default values of
\(10^{-15}\)
Equivalent to the following expression:
abs
<=
max
rel_tol
max
abs
),
abs
)),
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
checkingFunction
accuracy
Returns
true
if
and
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
and
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
and
&&
Logical AND.
Returns
true
if both
and
are true, otherwise returns
false
Evaluated lazily: if the left-hand argument is
true
, the right-hand argument is not evaluated.
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
Logical NOT.
Definitions
boolean
boolean
Examples
not
true
false
not
false
true
!true
false
or
||
Logical OR.
Returns
true
when at least one of
and
is true.
Returns false when both
and
are false.
Evaluated lazily: if the left-hand argument is
true
, the right-hand argument is not evaluated.
Definitions
boolean
boolean
boolean
set
set
set
- equivalent to
union(x,y)
Examples
true
or
false
true
false
or
false
false
true
||
false
true
xor
Logical XOR.
Returns
true
when at either
or
is true but not both.
Returns
false
when
and
are the same expression.
Definitions
boolean
boolean
boolean
Examples
true
XOR
false
true
true
XOR
true
false
false
XOR
false
false
nand
Logical NAND.
Equivalent to
not
(x
and
y)
Returns
true
when at most one of
or
is true.
Returns
false
when
and
are both true.
Evaluated lazily: if the left-hand argument is
false
, the right-hand argument is not evaluated.
Definitions
boolean
boolean
boolean
Examples
true
NAND
false
true
true
NAND
true
false
false
NAND
false
true
nor
Logical NOR.
Equivalent to
not
(x
or
y)
Returns
true
when neither
nor
is true.
Returns
false
when either of
or
is true.
Evaluated lazily: if the left-hand argument is
true
, the right-hand argument is not evaluated.
Definitions
boolean
boolean
boolean
Examples
true
NOR
false
false
true
NOR
true
false
false
NOR
false
true
implies
Logical implication.
If
is true and
is false, then the implication is false.
Otherwise, the implication is true.
Evaluated lazily: if the left-hand argument is
false
, the right-hand argument is not evaluated.
Definitions
boolean
boolean
boolean
Example
true
implies
true
true
true
implies
false
false
false
implies
true
true
false
implies
false
true
Collections
Get the
th
element of the collection
For matrices, the
th
row is returned.
For dictionaries, the value corresponding to the key
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]
vector(0,1,2)[2]
matrix([0,1,2],[3,4,5],[6,7,8])[0]
vector(0,1,2)
["a":
1,
"b":
2]["a"]
..
..
Slice the collection
- 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]
in
collection
Is element
in
collection
Definitions
number
range
boolean
string
dict
boolean
- returns
true
if the dictionary has a key
string
string
boolean
anything,
list
boolean
anything,
set
boolean
Examples
in
[1,2,3,4]
true
in
(set(1,2,3,4)
and
set(2,4,6,8))
false
"a"
in
["a":
1]
true
in
["a":
1]
throws an error because dictionary keys must be strings.
Ranges
..
Define a range.
Includes all integers between and including
and
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
0..1#0
except
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
[-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
Evaluate
expression
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
anonymous_function
map
expression,name[s],d
Apply a transformation to each item in a list, range, vector or matrix.
You can either give an
anonymous function
(the neater way), or give an expression followed by a name to refer to the item being transformed.
You can also give a list of names if each element of
is a list of values.
The Nth element of the list will be mapped to the Nth name.
Definitions
lambda
list
or
range
or
vector
or
matrix
list
or
vector
or
matrix
anything,
name
or
list
of
name
list
or
range
or
vector
or
matrix
list
or
vector
or
matrix
Examples
map(x
->
x+1,
1..3)
[2,3,4]
map(x+1,x,1..3)
[2,3,4]
map(s
->
capitalise(s),
["jim","bob"])
["Jim","Bob"]
map([x,y]
->
sqrt(x^2+y^2),
[3,4],
[5,12]
])
[5,13]
map(sqrt(x^2+y^2),
[x,y],
[3,4],
[5,12]
])
[5,13]
map(x
->
x+1,
id(2))
matrix([2,1],[1,2])
map(x
->
sqrt(x),
vector(1,4,9))
vector(1,2,3)
expression
for:
name
of
list
where:
condition
This is similar to
map
and
filter
, with different syntax.
Evaluate
expression
for each item in
list
, replacing variable
name
with the element from
list
each time.
You can also give a list of names if each element of
is a list of values.
The Nth element of the list will be mapped to the Nth name.
You can chain several
for:
...
of:
...
statements together to work over the Cartesian product of the given lists.
Variables assigned by earlier
for:
statements are available in later
for:
statements in the chain.
Note that with bracketing you can change the shape of the resulting list.
Each
for:
...
of:
...
statement can be followed by an optional
where:
condition
statement, restricting the values to be iterated over.
Only values which satisfy the condition will be used.
Examples
x^2
for:
of:
1..5
[1,
4,
9,
16,
25]
(square the numbers 1 to 5)
for:
of:
1..10
where:
mod(x,3)=0
[3,
6,
9]
(find multiples of 3 between 1 and 10)
log(x,b)
for:
[x,b]
of:
[[100,10],
[16,2]]
[2,
4]
(given pairs of numbers and bases, take the logarithm of each number with the corresponding base)
[a,b]
for:
[a,b]
of:
zip(1..3,
4..6)
[1,4],
[2,5],
[3,6]
(pair the numbers from the range
1..3
and numbers from the range
4..6
[a,b]
for:
of:
1..3
for:
of:
4..6
[1,4],
[1,5],
[1,6],
[2,4],
[2,5],
[2,6],
[3,4],
[3,5],
[3,6]
(produce all possible pairs of numbers from the ranges
1..3
and
4.6
mod(a,b)
for:
of:
1..5
for:
of:
[2,3]
[1,
1,
0,
2,
1,
0,
0,
1,
1,
2]
(mod(a,b)
for:
of:
1..5)
for:
of:
[2,3]
[1,0,1,0,1],
[1,2,0,1,2]
(mod(a,b)
for:
of:
[2,3])
for:
of:
1..5
[1,1],
[0,2],
[1,0],
[0,1],
[1,2]
[x,y]
for:
of:
1..3
for:
of:
1..x
[1,1],
[2,1]
,[2,2],
[3,1],
[3,2],
[3,3]
[x,y]
for:
of:
2..7
for:
of:
(x+1)..7
where:
gcd(x,y)=1
[2,3],
[2,5],
[2,7],
[3,4],
[3,5],
[3,7],
[4,5],
[4,7],
[5,6],
[5,7],
[6,7]
(find coprime pairs of numbers between 2 and 7)
[a,b,c]
for:
of:
1..20
for:
of:
1..20
for:
of:
1..20
where:
a
a^2+b^2
c^2
3,
4,
],
5,
12,
13
],
6,
8,
10
],
8,
15,
17
],
9,
12,
15
],
12,
16,
20
(find Pythagorean triples with side lengths up to 20)
[a,b,c]
for:
[a,b,c]
of:
product(1..20,
3)
where:
a
a^2+b^2
c^2
3,
4,
],
5,
12,
13
],
6,
8,
10
],
8,
15,
17
],
9,
12,
15
],
12,
16,
20
(the same as above, but written more concisely)
filter
anonymous_function
filter
expression
name
Filter each item in list or range
You can either give an
anonymous function
(the neater way), or give an expression followed by a name to refer to the item being considered.
The returned value is a list containing values for which the function or expression evaluated to
true
Definitions
lambda
list
list
anything,
name
, anything →
list
Example
filter(x
->
x>5,
[1,3,5,7,9])
[7,9]
filter(x>5,
x,
[1,3,5,7,9])
[7,9]
foldl
anonymous_function
first_value
foldl
expression
accumulator_name
item_name
first_value
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”.
You can either give an
anonymous function
(the neater way), or give an expression followed by names to refer to the accumulated value and the item from the collection.
For each item in the list, range, vector or matrix
the function or expression is evaluated along with the accumulated value so far, ending up with a single value which is returned.
At each iteration, the variable
item_name
is replaced with the corresponding value from
The variable
accumulator_name
is replaced with
first_value
for the first iteration, and the result of
expression
from the previous iteration subsequently.
Definitions
lambda
, anything, :data:list` → unspecified
anything,
name
name
, anything, anything → unspecified
Examples
foldl((total,
x)
->
total
x,
0,
[1,2,3])
foldl(total
x,
total,
x,
0,
[1,2,3])
foldl((longest,
x)
->
if(len(x)>len(longest),x,longest),
"",
["banana","pineapple","plum"])
"pineapple"
iterate
anonymous_function
initial
times
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 either give an
anonymous function
(the neater way), or give an expression followed by a name to refer to the current value.
Definitions
anything,
name
or
list
of
name
, anything,
number
list
Example
iterate(x
->
x+1,
0,
3)
[0,1,2,3]
iterate(x+1,
x,
0,
3)
[0,1,2,3]
iterate([a,b]
->
[b,a+b],
[1,1],
3)
[1,1],
[1,2],
[2,3],
[3,5]
iterate(l
->
l[1..len(l)]+[l[0]],
["a","b","c"],
3)
["a","b","c"],
["b","c","a"],
["c","a","b"],
["a","b","c"]
iterate_until
iteration_function
initial
condition_function
max_iterations
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 either give
anonymous functions
for the iteration function and condition, or give expressions and a name to use for the current value.
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
lambda
, anything,
lambda
number
list
anything,
name
or
list
of
name
, anything,
boolean
number
list
Example
iterate_until(x
->
if(mod(x,2)=0,x/2,3x+1),
5,
->
x=1)
5,
16,
8,
4,
2,
iterate_until(if(mod(x,2)=0,x/2,3x+1),
x,
5,
x=1)
5,
16,
8,
4,
2,
iterate_until([a,b]
->
[b,mod(a,b)],
[37,32],
[a,b]
->
b=0)
37,
32
],
32,
],
5,
],
2,
],
1,
take
condition_function
take
expression
name
Take the first
elements from list or range
which satisfy a condition.
You can either give an
anonymous function
or an expression representing a condition and a name used to refer to the item being considered.
This operation is lazy - once
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
lambda
list
list
number
, anything,
name
list
list
Example
take(3,
->
gcd(x,6)=1,
10..30)
[11,13,17]
take(3,gcd(x,6)=1,x,10..30)
[11,13,17]
separate
list
:data:`boolean`
Sort each of the values in
list
into one of two lists, depending on whether they satisfy the condition.
Values which satisfy the condition go into the first list; values which don’t satisfy it go in the second list.
Definitions
list
lambda
list
Example
separate(1..10,
->
3|x)
[3,
6,
9],
[1,
2,
4,
5,
7,
8,
10]
groups_of
list
size
Split a long list into smaller lists of the given size.
If the number of items in the list isn’t a mutliple of the required size, then the final group will have fewer items in it.
Definitions
number
list
list
Example
groups_of(0..5,
2)
[0,1],
[2,3],
[4,5]
groups_of(["A",
"B",
"C",
"D",
"E"],
3)
["A",
"B",
"C"],
["D",
"E"]
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)
let(["x":
1,
"y":
2],
x+y)
|>
|>
f()
is equivalent to
f(a)
This operator can be chained:
|>
f()
|>
g()
is equivalent to
g(f(a))
The “pipe” operator can be used to apply a sequence of transformations to a value.
The left-hand value
is inserted as the first argument of the right-hand function
If
takes more than one argument, you must give the others on the right-hand side.
Definitions
anything, anything → anything
Examples
|>
sqrt()
|>
siground(2)
1.4
["happy",
"birthday"]
|>
join("
")
|>
upper()
"HAPPY
BIRTHDAY"
sort
Sort list
Definitions
list
list
Example
sort([4,2,1,3])
[1,2,3,4]
sort_destinations
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
Reverse list
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
Return a copy of the list
with duplicates removed.
Definitions
list
list
Example
distinct([1,2,3,1,4,3])
[1,2,3,4]
list
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])
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
-th Cartesian power of the list is returned: the Cartesian product of
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
All ordered choices of
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
All ordered choices of
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
All choices of
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
of
collection
, a new list of the form
[i,v]
, where
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
If the key is not present in the dictionary, an error will be thrown.
Definitions
dict
string
→ unspecified
Example
["a":
1,
"b":
2]["a"]
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)
get(["a":1],
"b",
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]
merge
dict1
dict2
...
dictN
Given any number of dictionaries, merge them all into one.
Later dictionaries take precedence over earlier ones.
Definitions
multiple
dict
dict
list of
dict
dict
Example
merge(["a":
1,
"b":
1],
["b":
2,
"c":
2])
["a":
1,
"b":
2,
"c":
2]
merge(["a":
1],
["b":
2],
["c":
3])
["a":
1,
"b":
2,
"c":
3]
merge([
["a":
1],
["b":
2]
])
["a":
1,
"b":
2]
merge()
dict()
merge([])
dict()
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
Union of sets
and
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
Intersection of sets
and
, 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)
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
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)
random(0..1#0.01)
weighted_random
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
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
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
Produce a randomly-chosen partition of the integer
into
non-zero parts.
Definitions
number
number
list
Examples
random_integer_partition(6,3)
[1,
3,
2]
(other values can be produced)
seedrandom
seed
expression
Set the seed for the random number generator to the given value before evaluating the given expression.
The previous state of the random number generator is restored after evaluating the expression.
A randomised expression evaluated with the same seed will always produce the same value.
You can use
Exam variables
with this function to ensure that you get the same “random” values in different questions in the same exam.
Definitions
anything, anything → anything
Examples
seedrandom(0,
random(1..1000))
39
seedrandom("Numbas",
random(1..1000))
997
Control flow
award
Return
if
is
true
, else return
Definitions
number
boolean
number
Example
award(5,true)
if
If
is
true
, return
, else return
Only the returned value is evaluated.
Definitions
boolean
, anything, anything → unspecified
Example
if(false,1,0)
switch
p1
a1
p2
a2
...
pn
an
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)
switch(false,1,true,0,3)
switch(false,1,false,0,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+"
try(1+2,err,0)
Insert the left-hand value
as the first argument of the right-hand function
Several applications of this operator can be chained together, to make code that applies successive functions to a single value more readable.
When the right-hand function has more than one argument, the left-hand value is inserted before the arguments you give, so
|>
f(b,c)
is equivalent to
f(a,b,c)
Example
|>
sqrt()
|>
precround(2)
1.73
HTML
html
Parse string
as HTML.
Definitions
string
html
Example
html('
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("
true
isnonemptyhtml("")
false
table
data
table
data
headers
table
data
column_headers
row_headers
Create an HTML with cell contents defined by
data
, which should be a list of lists of data.
You can optionally give a list of column headers, or lists of both row and column headers.
Definitions
list
list
of
list
html
list
html
Examples
table([[0,1],[1,0]],
["Column
A",
"Column
B"],
["Row
1",
"Row
2"])
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/
, where
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("
html("
400em;\">a
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("
Text
"))html("
400em;\">a")
escape_html
text
Rewrite the given string, replacing characters that might be HTML code with the corresponding HTML entity escape codes, so the resulting string can be safely displayed as plain text.
Definitions
string
string
Example
escape_html("
Text
")"<p>Text</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"))
eval(expression("x+1"),
["x":1])
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")
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!")
normalise_subscripts
name
Normalise the subscripts in a variable name.
In
Mathematical expression
parts, variable names ending with a number are rewritten so that the number is alwasys preceded by an underscore, e.g.
x1
is rewritten to
x_1
This function can be used to perform the normalisation.
Definition
string
string
Example
normalise_subscripts("x1")
"x_1"
normalise_subscripts("x_1")
"x_1"
normalise_subscripts("xa")
"xa"
normalise_subscripts("x_a")
"x_a"
canonical_compare
expr1
expr2
Compare expressions
and
using the “canonical” ordering.
Returns
-1
if
should go before
if they are considered “equal”, and
if
should go after
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
and
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
and
are numbers and
is a variable name, go before anything else.
Function name: if
and
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
and
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))
canonical_compare(f(x),g(x))
-1
canonical_compare("a","b")
numerical_compare
Compare expression
and
by substituting random values in for the free variables.
Returns
true
if
and
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
and
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)
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
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
2*cos(0)")
Identifying data types
type
Returns the name of the
data type
of
Example
type(1)
"integer"
isa
type
Returns
true
if
is of the
data type
type
Definitions
anything,
string
boolean
Examples
isa
"number"
true
isa
"name"
true
(if
is not defined in this scope)
isa
"number"
true
(if
has a numerical value in this scope)
as
type
Convert
to the given data type, if possible.
If
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
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
Debugging tools
debug_log
label
Log the value of
to the browser’s console, prefixed with the given
label
, and return
The logged value is unwrapped to a plain JavaScript value, which is easier to read but might not fully reflect more specialised JME data types.
Definitions
anything,
string
→ unspecified
Contents