Jump to navigation

Namespace: util

Numbas.util

Source:

Members

(static) equalityTests

Functions to decide if two tokens of the same type are equal. Dictionary mapping token type name to function.

Source:
See:

(static) numberNotationStyles

Different styles of writing a decimal.

Objects of the form {re,format}, where re is a regex recognising numbers in this style, and format(integer,decimal) renders the number in this style.

Each regex matches the integer part in group 1, and the decimal part in group 2 - it should be safe to remove all non-digit characters in these and preserve meaning.

Source:
See:

(static) re_fraction :RegExp

Regular expression recognising a fraction.

Type:
Source:

Methods

(static) arraysEqual(a, b) → {boolean}

Are two arrays equal? True if their elements are all equal.

Parameters:
Name Type Description
a Array
b Array
Returns:
Type Description
boolean
Source:

(static) b64decode(encoded) → {ArrayBuffer}

Decode a base64 string to an ArrayBuffer.

Parameters:
Name Type Description
encoded string
Returns:
Type Description
ArrayBuffer
Source:

(static) b64encode(arrayBuffer) → {string}

Encode the contents of an ArrayBuffer in base64.

Parameters:
Name Type Description
arrayBuffer ArrayBuffer
Returns:
Type Description
string
Source:

(static) capitalise(str) → {string}

Make the first letter in the string a capital.

Parameters:
Name Type Description
str string
Returns:
Type Description
string
Source:

(static) cartesian_power(l, n) → {Array}

Cartesian product of list, repeated n times.

Parameters:
Name Type Description
l Array
n number
Returns:
Type Description
Array
Source:

(static) caselessCompare(a, b) → {boolean}

Compare two strings, ignoring differences in case. Does not ignore differences in accent, even where base characters are identical

Parameters:
Name Type Description
a string

reference string
b string

comparison string
Returns:
Type Description
boolean
Source:

(static) cleanNumber(s, styles, strictStyleopt) → {string}

Clean a string potentially representing a number. Remove space, and then try to identify a notation style.

If styles is given, s 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.

Parameters:
Name Type Attributes Description
s string

The string potentially representing a number.
styles string | Array.<string>

Styles of notation to allow, e.g. ['en','si-en'].
strictStyle boolean <optional>

If false or not given, strings which do not match any of the allowed styles but are valid JavaScript number literals will be allowed. If true, these strings will return 'NaN'.
Returns:
Type Description
string
Source:
See:

(static) combinations(list, r) → {Array.<Array>}

All combinations of r items from given array, without replacement.

Parameters:
Name Type Description
list Array
r number
Returns:
Type Description
Array.<Array>
Source:

(static) combinations_with_replacement(list, r) → {Array.<Array>}

All combinations of r items from given array, with replacement.

Parameters:
Name Type Description
list Array
r number
Returns:
Type Description
Array.<Array>
Source:

(static) contains(list, value, scope) → {boolean}

Is value in the list?

Parameters:
Name Type Description
list Array
value Numbas.jme.token
scope Numbas.jme.Scope

The scope to use for establishing equality of tokens.
Returns:
Type Description
boolean
Source:

(static) contentsplitbrackets(txt, re_end) → {Array.<string>}

Split a string up by TeX delimiters ($, \[, \])

bits.re_end stores the delimiter if the returned array has unfinished maths at the end.

Parameters:
Name Type Description
txt string

String to split up.
re_end RegExp

If tex is split across several strings (e.g. text nodes with
in the middle), this can be used to give the end delimiter for unfinished maths.
Returns:
Type Description
Array.<string>

bits - Stuff outside TeX, left delimiter, TeX, right delimiter, stuff outside TeX, ...
Example
contentsplitbrackets('hello $x+y$ and \[this\] etc')
// ['hello ','$','x+y','$',' and ','\[','this','\]']
Source:

(static) copyarray(arr, deep) → {Array}

Clone an array, with array elements copied too. Array.splice() will create a copy of an array, but the elements are the same objects, which can cause fruity bugs. This function clones the array elements as well, so there should be no side-effects when operating on the cloned array.

Parameters:
Name Type Description
arr Array
deep boolean

if true, do a deep copy of each element
Returns:
Type Description
Array
Source:
See:

(static) copyinto(src, dest)

Shallow copy an object into an already existing object - add all src's properties to dest.

Parameters:
Name Type Description
src object
dest object
Source:

(static) copyobj(obj, deep) → {object}

Clone an object.

Parameters:
Name Type Description
obj object
deep boolean

if true, each property is cloned as well (recursively) so there should be no side-effects when operating on the cloned object.
Returns:
Type Description
object
Source:

(static) currency(n, prefix, suffix) → {string}

Format an amount of currency.

Parameters:
Name Type Description
n number
prefix string

Symbol to use in front of currency if abs(n) >= 1.
suffix string

Symbol to use after currency if abs(n) <= 1.
Returns:
Type Description
string
Example
currency(5.3,'£','p')
// £5.30
Source:

(static) debounce(frequency) → {function}

Debounce a function: run it no more than every frequency milliseconds.

Parameters:
Name Type Description
frequency number

Minimum gap between runs of the callback, in milliseconds.
Returns:
Type Description
function

Call with a callback that you want to run.
Source:

(static) deep_extend_object(destination) → {object}

Extend destination with all the properties from subsequent arguments, and recursively extend objects that both properties have under the same key.

Parameters:
Name Type Description
destination object
Returns:
Type Description
object
Source:

(static) distinct(list, scope) → {Array}

Return a copy of the input list with duplicates removed.

Parameters:
Name Type Description
list Array
scope Numbas.jme.Scope

The scope to use for establishing equality of tokens.
Returns:
Type Description
Array
Source:
See:

(static) eq(a, b, scope) → {boolean}

Generic equality test on Numbas.jme.tokens.

Parameters:
Name Type Description
a Numbas.jme.token
b Numbas.jme.token
scope Numbas.jme.Scope

The scope to use for normalising names.
Returns:
Type Description
boolean
Source:
See:

(static) escapeHTML(str) → {string}

Because XML doesn't like having ampersands hanging about, replace them with escape codes.

Parameters:
Name Type Description
str string

XML string.
Returns:
Type Description
string
Source:

(static) except(list, exclude, scope) → {Array}

Filter out values in exclude from list.

Parameters:
Name Type Description
list Numbas.jme.types.TList
exclude Numbas.jme.types.TList
scope Numbas.jme.Scope

The scope to use for establishing equality of tokens.
Returns:
Type Description
Array
Source:

(static) extend(a, b, extendMethods) → {function}

Derive type B from A (class inheritance, really)

B's prototype supercedes A's.

Parameters:
Name Type Description
a function

the constructor for the parent class
b function

a constructor to be called after a's constructor is done.
extendMethods boolean

if true, the methods of the new type are constructed so that the method from type A is applied, then the method from type B. Nothing is returned.
Returns:
Type Description
function

a constructor for the derived class
Source:

(static) extend_object(destination) → {object}

Extend destination with all the properties from subsequent arguments. undefined values are not copied over. Replacement for jQuery.extend. Modified from https://stackoverflow.com/a/11197343 Object.assign doesn't behave the same way - it copies over undefined.

Parameters:
Name Type Description
destination object
Returns:
Type Description
object
Source:

(static) formatNumberNotation(s, style, syntaxopt) → {string}

Format a string representing a number given in "plain" notation: an optional minus sign followed by digits, and optionally a dot and more digits.

Parameters:
Name Type Attributes Default Description
s string

The string representing a number.
style string

The style of notation to use.
syntax string <optional>
 "plain"

The syntax to use, either "plain" for plain text, or "latex", for LaTeX.
Returns:
Type Description
string
Source:

(static) formatString(str, …value) → {string}

Replace occurences of %s with the extra arguments of the function.

Parameters:
Name Type Attributes Description
str string
value string <repeatable>

String to substitute.
Returns:
Type Description
string
Example
formatString('hello %s %s','Mr.','Perfect') 
// 'hello Mr. Perfect'
Source:

(static) formatTime(t) → {string}

String representation of a time, in the format HH:MM:SS.

Parameters:
Name Type Description
t Date
Returns:
Type Description
string
Source:

(static) hashCode(str) → {string}

Hash a string into a string of digits.

From http://werxltd.com/wp/2010/05/13/javascript-implementation-of-javas-string-hashcode-method/.

Parameters:
Name Type Description
str string
Returns:
Type Description
string
Source:

(static) isBool(b) → {boolean}

Test if parameter is a boolean - that is: a boolean literal, or any of the strings 'false','true','yes','no', case-insensitive.

Parameters:
Name Type Description
b object
Returns:
Type Description
boolean
Source:

(static) isFloat(f) → {boolean}

Test if parameter is a float.

Parameters:
Name Type Description
f object
Returns:
Type Description
boolean
Source:

(static) isFraction(s) → {boolean}

Test if parameter is a fraction.

Parameters:
Name Type Description
s string
Returns:
Type Description
boolean
Source:

(static) isInt(i) → {boolean}

Test if parameter is an integer.

Parameters:
Name Type Description
i object
Returns:
Type Description
boolean
Source:

(static) isNonemptyHTML(html) → {boolean}

Parse a string as HTML, and return true only if it contains non-whitespace text.

Parameters:
Name Type Description
html string
Returns:
Type Description
boolean
Source:

(static) isNumber(n, allowFractions, styles, strictStyle) → {boolean}

Is na number? i.e. !isNaN(n), or is n "infinity", or if allowFractions is true, is n a fraction?

If styles is given, try to put the number in standard form if it matches any of the given styles.

Parameters:
Name Type Description
n number | string
allowFractions boolean
styles string | Array.<string>

Styles of notation to allow.
strictStyle boolean

If false or not given, strings which do not match any of the allowed styles but are valid JavaScript number literals will be allowed. If true, these strings will return false.
Returns:
Type Description
boolean
Source:
See:

(static) letterOrdinal(n) → {string}

Get the letter format of an ordinal. e.g. the Nth element in the sequence a,b,c,...z,aa,ab,..,az,ba,...

Parameters:
Name Type Description
n number
Returns:
Type Description
string
Source:

(static) lpad(s, n, p) → {string}

Pad string s on the left with a character p until it is n characters long.

Parameters:
Name Type Description
s string
n number
p string
Returns:
Type Description
string
Source:

(static) matchNotationStyle(s, styles, strictStyleopt, mustMatchAllopt) → {object|null}

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 JavaScript number literal equivalent.

Parameters:
Name Type Attributes Description
s string

The string potentially representing a number.
styles string | Array.<string>

Styles of notation to allow, e.g. ['en','si-en'].
strictStyle boolean <optional>

If false or not given, strings which do not match any of the allowed styles but are valid JavaScript number literals will be allowed. If true, these strings will return 'NaN'.
mustMatchAll boolean <optional>

If true, then the string must contain only the matched number.
Returns:
Type Description
object | null
  • {matched, cleaned} or null
Source:
See:

(static) neq(a, b, scope) → {boolean}

Generic inequality test on Numbas.jme.tokens.

Parameters:
Name Type Description
a Numbas.jme.token
b Numbas.jme.token
scope Numbas.jme.Scope

The scope to use for normalising names.
Returns:
Type Description
boolean
Source:
See:

(static) nicePartName(path) → {string}

Get a human-sensible name of a part, given its path.

Parameters:
Name Type Description
path string
Returns:
Type Description
string
Source:

(static) objects_equal(a, b) → {boolean}

Are the given objects equal? False if they're of different types. If they're both arrays, uses Numbas.util.arraysEqual. If they're both objects, true if every key in b is also in a, and a[k] is equal to b[k] for every k in a. Otherwise, uses JavaScript's equality test.

Parameters:
Name Type Description
a *
b *
Returns:
Type Description
boolean
Source:

(static) parseBool(b) → {boolean}

Parse parameter as a boolean. The boolean value true and the strings 'true' and 'yes' are parsed as the value true, everything else is false.

Parameters:
Name Type Description
b object
Returns:
Type Description
boolean
Source:

(static) parseDecimal(s, allowFractions, styles, strictStyle) → {Decimal}

Parse a number - either as a Decimal, or parse a fraction.

Parameters:
Name Type Description
s string
allowFractions boolean

Are fractions of the form a/b (a and b integers without punctuation) allowed?
styles string | Array.<string>

Styles of notation to allow.
strictStyle boolean

If false or not given, strings which do not match any of the allowed styles but are valid JavaScript number literals will be allowed. If true, these strings will return NaN.
Returns:
Type Description
Decimal
Source:
See:

(static) parseFraction(s, mustMatchAllopt) → {fraction}

Parse a string representing an integer or fraction.

Parameters:
Name Type Attributes Description
s string
mustMatchAll boolean <optional>

If true, then the string must contain only the matched number.
Returns:
Type Description
fraction
Source:
See:

(static) parseInt(s, base) → {number}

Parse an integer in the given base. Unlike javascript's built-in parseInt, this returns NaN if an invalid character is present in the string. The digits are the numerals 0 to 9, then the letters of the English alphabet.

Parameters:
Name Type Description
s string

a representation of a number.
base number

the base of the number's representation.
Returns:
Type Description
number
Source:

(static) parseNumber(s, allowFractions, styles, strictStyle) → {number}

Parse a number - either parseFloat, or parse a fraction.

Parameters:
Name Type Description
s string
allowFractions boolean

Are fractions of the form a/b (a and b integers without punctuation) allowed?
styles string | Array.<string>

Styles of notation to allow.
strictStyle boolean

If false or not given, strings which do not match any of the allowed styles but are valid JavaScript number literals will be allowed. If true, these strings will return NaN.
Returns:
Type Description
number
Source:
See:

(static) permutations(list, r) → {Array.<Array>}

All permutations of all choices of r elements from list.

Inspired by the algorithm in Python's itertools library.

Parameters:
Name Type Description
list Array

Elements to choose and permute.
r number

Number of elements to choose.
Returns:
Type Description
Array.<Array>
Source:

(static) pluralise(n, singular, plural) → {string}

Pluralise a word.

If n is not unity, return plural, else return singular.

Parameters:
Name Type Description
n number
singular string

String to return if n is +1 or -1.
plural string

String to returns if n is not +1 or -1.
Returns:
Type Description
string
Source:

(static) prefix_css_selectors(sheet, prefix)

Prefix every selector in the given CSS stylesheet with the given selector.

Parameters:
Name Type Description
sheet StyleElement
prefix string

A CSS selector.
Source:

(static) product(lists) → {Array}

Cartesian product of one or more lists.

Parameters:
Name Type Description
lists Array

list of arrays
Returns:
Type Description
Array
Source:

(static) rpad(s, n, p) → {string}

Pad string s on the right with a character p until it is n characters long.

Parameters:
Name Type Description
s string
n number
p string
Returns:
Type Description
string
Source:

(static) separateThousands(n, separator) → {string}

Write a number with every three digits separated by the given separator character.

Parameters:
Name Type Description
n number
separator string
Returns:
Type Description
string
Example
separateThousands(1234567.1234,',') 
// '1,234,567.1234'
Source:

(static) slugify(str) → {string}

Transform the given string to one containing only letters, digits and hyphens.

Parameters:
Name Type Description
str string
Returns:
Type Description
string
Source:

(static) sortBy(props) → {function}

Create a comparison function which sorts objects by a particular property.

Parameters:
Name Type Description
props Array.<string> | string

Name of the property (or list of names of properties) to sort by.
Returns:
Type Description
function
Source:

(static) splitbrackets(str, lb, rb, nestlbopt, nestrbopt) → {Array.<string>}

Split a string up according to brackets.

Strips out nested brackets.

Parameters:
Name Type Attributes Default Description
str string

String to split.
lb string

Left bracket string.
rb string

Right bracket string.
nestlb string <optional>
 ""

String to replace nested left brackets with.
nestrb string <optional>
 ""

String to repalce nested right brackets with.
Returns:
Type Description
Array.<string>
  • Alternating strings in brackets and strings outside: odd-numbered indices are inside brackets.
Example
splitbrackets('a{{b}}c','{','}') 
// ['a','b','c']
Source:

(static) standardNumberFormatter(thousands, decimal_mark, separate_decimalopt) → {function}

Create a function (integer,decimal) -> string which formats a number according to the given punctuation.

Parameters:
Name Type Attributes Default Description
thousands string

The string used to separate powers of 1000.
decimal_mark string

The decimal mark character.
separate_decimal boolean <optional>
 false

Should the thousands separator be used to separate negative powers of 1000 (that is, groups of 3 digits after the decimal point)?
Returns:
Type Description
function
Source:

(static) unPercent(s) → {number}

Get rid of the % on the end of percentages and parse as float, then divide by 100.

Parameters:
Name Type Description
s string
Returns:
Type Description
number
Examples
unPercent('50%') 
// 0.5
unPercent('50') 
// 0.5
Source:

(static) wrapListIndex(n, size) → {number}

Wrap a list index so -1 maps to length-1.

Parameters:
Name Type Description
n number
size number
Returns:
Type Description
number
Source:

(static) zip(lists) → {Array}

Zip lists together: given lists [a,b,c,...], [x,y,z,...], return [[a,x],[b,y],[c,z], ...].

Parameters:
Name Type Description
lists Array

list of arrays
Returns:
Type Description
Array
Source: