# util

### Classes

Clock
Color
CountdownTimer
EventEmitter
PsychObject
MonotonicClock
Scheduler

### Mixins

ColorMixin

### Members

#### (static) mix

Source:
  - util/Util.js, line 24

Syntactic sugar for Mixins

This is heavily adapted from: http://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/

##### Example

    class BaseClass { ... }
    let Mixin1 = (superclass) => class extends superclass { ... }
    let Mixin2 = (superclass) => class extends superclass { ... }
    class NewClass extends mix(BaseClass).with(Mixin1, Mixin2) { ... }

#### (static, constant) TEXT_DIRECTION

Source:
  - util/Util.js, line 1410

Enum that stores possible text directions. Note that Arabic is the same as RTL but added here to support PsychoPy's languageStyle enum. Arabic reshaping is handled by the browser automatically.

### Methods

#### (static) addInfoFromUrl(info)

Source:
  - util/Util.js, line 711

Add info extracted from the URL to the given dictionary.

We exclude all URL parameters starting with a double underscore since those are reserved for client/server communication

##### Parameters:

Name | Type | Description
--- | --- | ---
`info` | Object | the dictionary

#### (static) average(input) → {number}

Source:
  - util/Util.js, line 1006

Calculate the average of the elements in the input array.

If 'input' is not an array, or if it is an empty array, then we return 0.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | an array of numbers, or of objects that can be cast into a number, e.g. ['1', 2.5, 3e1]

##### Returns:

the average of the elements in the array

Type
  number

#### (static) count(input, value)

Source:
  - util/Util.js, line 1220

Count the number of elements in the input array that match the given value.

Note: count is able to handle NaN, null, as well as any value convertible to a JSON string.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | the input array
`value` | Number | string | object | null | the matching value

##### Returns:

the number of matching elements

#### (static) detectBrowser() → {string}

Source:
  - util/Util.js, line 130

Detect the user's browser.

Note: since user agent is easily spoofed, we use a more sophisticated approach, as described here: https://stackoverflow.com/a/9851769

##### Returns:

the detected browser, one of 'Opera', 'Firefox', 'Safari', 'IE', 'Edge', 'EdgeChromium', 'Chrome', 'unknown'

Type
  string

#### (static) extensionFromMimeType(mimeType) → {string}

Source:
  - util/Util.js, line 1321

Return the file extension corresponding to an audio mime type. If the provided mimeType is not a string (e.g. null, undefined, an array) or unknown, then '.dat' is returned, instead of throwing an exception.

##### Parameters:

Name | Type | Description
--- | --- | ---
`mimeType` | string | the MIME type, e.g. 'audio/webm;codecs=opus'

##### Returns:

the corresponding file extension, e.g. '.webm'

Type
  string

#### (static) flattenArray(array) → {Array.<Object>}

Source:
  - util/Util.js, line 800

Recursively flatten an array of arrays.

##### Parameters:

Name | Type | Description
--- | --- | ---
`array` | Array.<Object> | the input array of arrays

##### Returns:

the flatten array

Type
  Array.<Object>

#### (static) getDownloadSpeed(psychoJS, nbDownloadsopt) → {number}

Source:
  - util/Util.js, line 1360

Get an estimate of the download speed, by repeatedly downloading an image file from a distant server.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`psychoJS` | PsychoJS |  |  | the instance of PsychoJS
`nbDownloads` | number | <optional> | `1` | the number of image downloads over which to average the download speed

##### Returns:

the download speed, in megabits per second

Type
  number

#### (static) getErrorStack() → {string}

Source:
  - util/Util.js, line 77

Get the error stack of the calling, exception-throwing function.

##### Returns:

the error stack as a string

Type
  string

#### (static) getPositionFromObject(object, units) → {Array.<number>}

Source:
  - util/Util.js, line 356

Get the position of the object, in pixel units

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | Object | the input object
`units` | string | the units

##### Returns:

the position of the object, in pixel units

Type
  Array.<number>

#### (static) getRequestError(jqXHR, textStatus, errorThrown)

Source:
  - util/Util.js, line 642

Get the most informative error from the server response from a jquery server request.

##### Parameters:

Name | Type | Description
--- | --- | ---
`jqXHR` |  |
`textStatus` |  |
`errorThrown` |  |

#### (static) getUrlParameters() → {URLSearchParams}

Source:
  - util/Util.js, line 691

Get the URL parameters.

##### Example

    const urlParameters = util.getUrlParameters();
    for (const [key, value] of urlParameters)
      console.log(key + ' = ' + value);

##### Returns:

the iterable URLSearchParams

Type
  URLSearchParams

#### (static) index(input, value)

Source:
  - util/Util.js, line 1283

Get the index in the input array of the first element that matches the given value.

Note: index is able to handle NaN, null, as well as any value convertible to a JSON string.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | the input array
`value` | Number | string | object | null | the matching value

##### Throws:

if the input array does not contain any matching element

##### Returns:

the index of the first element that matches the value

#### (static) isEmpty(x) → {boolean}

Source:
  - util/Util.js, line 99

Test if x is an 'empty' value.

##### Parameters:

Name | Type | Description
--- | --- | ---
`x` | Object | the value to test

##### Returns:

true if x is one of the following: undefined, [], [undefined]

Type
  boolean

#### (static) isInt(obj) → {boolean}

Source:
  - util/Util.js, line 669

Test whether an object is either an integer or the string representation of an integer.

This is adapted from: https://stackoverflow.com/a/14794066

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | Object | the input object

##### Returns:

whether or not the object is an integer or the string representation of an integer

Type
  boolean

#### (static) isNumeric(input) → {boolean}

Source:
  - util/Util.js, line 277

Check whether a value looks like a number

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | * | Some value

##### Returns:

Whether or not the value can be converted into a number

Type
  boolean

#### (static) IsPointInsidePolygon(point, vertices) → {boolean}

Source:
  - util/Util.js, line 290

Check whether a point lies within a polygon

We are using the algorithm described here: https://wrf.ecse.rpi.edu//Research/Short_Notes/pnpoly.html

##### Parameters:

Name | Type | Description
--- | --- | ---
`point` | Array.<number> | the point
`vertices` | Object | the vertices defining the polygon

##### Returns:

whether or not the point lies within the polygon

Type
  boolean

#### (static) makeUuid() → {string}

Source:
  - util/Util.js, line 63

Get a Universally Unique Identifier (RFC4122 version 4)

See details here: https://www.ietf.org/rfc/rfc4122.txt

##### Returns:

the uuid

Type
  string

#### (static) offerDataForDownload(filename, data, type)

Source:
  - util/Util.js, line 862

Offer data as download in the browser.

##### Parameters:

Name | Type | Description
--- | --- | ---
`filename` | string | the name of the file to be downloaded
`data` | * | the data
`type` | string | the MIME type of the data, e.g. 'text/csv' or 'application/json'

#### (static) pad(n, width) → {string}

Source:
  - util/Util.js, line 1260

Pad the given floating-point number with however many 0 needed at the start such that the padded integer part of the number is of the given width.

##### Parameters:

Name | Type | Description
--- | --- | ---
`n` |  | the input floating-point number
`width` |  | the desired width

##### Returns:

- the padded number, whose integer part has the given width

Type
  string

#### (static) promiseToTupple(promise) → {Array.<Object>}

Source:
  - util/Util.js, line 50

Convert the resulting value of a promise into a tupple.

##### Parameters:

Name | Type | Description
--- | --- | ---
`promise` | Promise | the promise

##### Returns:

the resulting value in the format [error, return data] where error is null if there was no error

Type
  Array.<Object>

#### (static) randchoice(array, randomNumberGeneratoropt) → {Array.<Object>}

Source:
  - util/Util.js, line 339

Pick a random value from an array, uses `util.shuffle` to shuffle the array and returns the last value.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`array` | Array.<Object> |  | the input 1-D array
`randomNumberGenerator` | function | <optional> | A function used to generated random numbers in the interal [0, 1). Defaults to Math.random

##### Returns:

a chosen value from the array

Type
  Array.<Object>

#### (static) randint(minopt, max) → {number}

Source:
  - util/Util.js, line 933

Generates random integers a-la NumPy's in the "half-open" interval [min, max). In other words, from min inclusive to max exclusive. When max is undefined, as is the case by default, results are chosen from [0, min). An error is thrown if max is less than min.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`min` | number | <optional> | `0` | lowest integer to be drawn, or highest plus one if max is undefined (default)
`max` | number |  |  | one above the largest integer to be drawn

##### Returns:

a random integer in the requested range (signed)

Type
  number

#### (static) range(startopt, stop, stepopt) → {Array.<Number>}

Source:
  - util/Util.js, line 1076

Create a sequence of integers.

The sequence is such that the integer at index i is: start + step * i, with i >= 0 and start + step * i < stop

Note: this is a JavaScript implement of the Python range function, which explains the unusual management of arguments.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`start` | Number | <optional> | `0` | the value of start
`stop` | Number |  |  | the value of stop
`step` | Number | <optional> | `1` | the value of step

##### Returns:

the range as an array of numbers

Type
  Array.<Number>

#### (static) round(input, places) → {number}

Source:
  - util/Util.js, line 966
See:
  - Stack Overflow

Round to a certain number of decimal places.

This is the Crib Sheet provided solution, but please note that as of 2020 the most popular SO answer is different.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | number | the number to be rounded
`places` | number | the max number of decimals desired

##### Returns:

input rounded to the specified number of decimal places at most

Type
  number

#### (static) selectFromArray(array, selection) → {Object|Array.<Object>}

Source:
  - util/Util.js, line 746

Select values from an array.

'selection' can be a single integer, an array of indices, or a string to be parsed, e.g.:

- 5
- [1,2,3,10]
- '1,5,10'
- '1:2:5'
- '5:'
- '-5:-2, 9, 11:5:22'

##### Parameters:

Name | Type | Description
--- | --- | ---
`array` | Array.<Object> | the input array
`selection` | number | Array.<number> | string | the selection

##### Returns:

the array of selected items

Type
  Object | Array.<Object>

#### (static) shuffle(array, randomNumberGeneratoropt) → {Array.<Object>}

Source:
  - util/Util.js, line 318

Shuffle an array in place using the Fisher-Yastes's modern algorithm

See details here: https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`array` | Array.<Object> |  | the input 1-D array
`randomNumberGenerator` | function | <optional> | A function used to generated random numbers in the interal [0, 1). Defaults to Math.random

##### Returns:

the shuffled array

Type
  Array.<Object>

#### (static) sliceArray(array, fromopt, toopt, stepopt) → {Array.<Object>}

Source:
  - util/Util.js, line 821

Slice an array.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`array` | Array.<Object> |  |  | the input array
`from` | number | <optional> | `NaN` | the start of the slice
`to` | number | <optional> | `NaN` | the end of the slice
`step` | number | <optional> | `NaN` | the step of the slice

##### Returns:

the array slice

Type
  Array.<Object>

#### (static) sort(input) → {array}

Source:
  - util/Util.js, line 1029

Sort the elements of the input array, in increasing alphabetical or numerical order.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | an array of numbers or of strings

##### Throws:

if 'input' is not an array, or if its elements are not consistent in types, or if they are not all either numbers or strings

##### Returns:

the sorted array

Type
  array

#### (static) sum(input, start) → {number}

Source:
  - util/Util.js, line 980

Calculate the sum of the elements in the input array.

If 'input' is not an array, then we return start.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | an array of numbers, or of objects that can be cast into a number, e.g. ['1', 2.5, 3e1]
`start` | number | value added to the sum of numbers (a la Python)

##### Returns:

the sum of the elements in the array + start

Type
  number

#### (static) to_height(pos, posUnit, win) → {Array.<number>}

Source:
  - util/Util.js, line 472

Convert the position to height units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window

##### Returns:

the position in height units

Type
  Array.<number>

#### (static) to_norm(pos, posUnit, win) → {Array.<number>}

Source:
  - util/Util.js, line 443

Convert the position to norm units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window

##### Returns:

the position in norm units

Type
  Array.<number>

#### (static) to_pixiPoint(pos, posUnit, win, integerCoordinatesopt) → {Array.<number>}

Source:
  - util/Pixi.js, line 13

Convert a position to a PIXI Point.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`pos` | Array.<number> |  |  | the input position
`posUnit` | string |  |  | the position units
`win` | Window |  |  | the associated Window
`integerCoordinates` | boolean | <optional> | `false` | whether or not to round the PIXI Point coordinates.

##### Returns:

the position as a PIXI Point

Type
  Array.<number>

#### (static) to_px(pos, posUnit, win, integerCoordinatesopt) → {Array.<number>}

Source:
  - util/Util.js, line 398

Convert the position to pixel units.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`pos` | Array.<number> |  |  | the input position
`posUnit` | string |  |  | the position units
`win` | Window |  |  | the associated Window
`integerCoordinates` | boolean | <optional> | `false` | whether or not to round the position coordinates.

##### Returns:

the position in pixel units

Type
  Array.<number>

#### (static) to_unit(pos, posUnit, win, targetUnit) → {Array.<number>}

Source:
  - util/Util.js, line 541

Convert the position to given units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window
`targetUnit` | string | the target units

##### Returns:

the position in target units

Type
  Array.<number>

#### (static) to_win(pos, posUnit, win) → {Array.<number>}

Source:
  - util/Util.js, line 505

Convert the position to window units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window

##### Returns:

the position in window units

Type
  Array.<number>

#### (static) toNumerical(obj) → {number|Array.<number>}

Source:
  - util/Util.js, line 210

Convert obj to its numerical form.

- number -> number, e.g. 2 -> 2
- [number] -> [number], e.g. [1,2,3] -> [1,2,3]
- numeral string -> number, e.g. "8" -> 8
- [number | numeral string] -> [number], e.g. [1, 2, "3"] -> [1,2,3]

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | Object | the input object

##### Returns:

the numerical form of the input object

Type
  number | Array.<number>

#### (static) toString(object) → {string}

Source:
  - util/Util.js, line 576

Convert an object to its string representation, taking care of symbols.

Note: if the object is not already a string, we JSON stringify it and detect circularity.

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | Object | the input object

##### Returns:

a string representation of the object or 'Object (circular)'

Type
  string

#### (static) turnSquareBracketsIntoArrays(input, max) → {array}

Source:
  - util/Util.js, line 889

Convert a string representing a JSON array, e.g. "[1, 2]" into an array, e.g. ["1","2"]. This approach overcomes the built-in JSON parsing limitations when it comes to eg. floats missing the naught prefix, and is able to process several arrays, e.g. "[1,2][3,4]".

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | string | string potentially containing JSON arrays
`max` | string | how many matches to return, unwrap resulting array if less than two

##### Returns:

an array if arrays were found, undefined otherwise

Type
  array

#### (protected, inner) _match(value)

Source:
  - util/Util.js, line 1159

Create a boolean function that compares an input element to the given value.

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | Number | string | object | null | the matching value

##### Returns:

a function that compares an input element to the given value

### Classes

Clock
Color
CountdownTimer
EventEmitter
PsychObject
MonotonicClock
Scheduler

### Mixins

ColorMixin

### Members

#### (static) mix

Source:
  - util/Util.js, line 24

Syntactic sugar for Mixins

This is heavily adapted from: http://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/

##### Example

    class BaseClass { ... }
    let Mixin1 = (superclass) => class extends superclass { ... }
    let Mixin2 = (superclass) => class extends superclass { ... }
    class NewClass extends mix(BaseClass).with(Mixin1, Mixin2) { ... }

#### (static, constant) TEXT_DIRECTION

Source:
  - util/Util.js, line 1410

Enum that stores possible text directions. Note that Arabic is the same as RTL but added here to support PsychoPy's languageStyle enum. Arabic reshaping is handled by the browser automatically.

### Methods

#### (static) addInfoFromUrl(info)

Source:
  - util/Util.js, line 711

Add info extracted from the URL to the given dictionary.

We exclude all URL parameters starting with a double underscore since those are reserved for client/server communication

##### Parameters:

Name | Type | Description
--- | --- | ---
`info` | Object | the dictionary

#### (static) average(input) → {number}

Source:
  - util/Util.js, line 1006

Calculate the average of the elements in the input array.

If 'input' is not an array, or if it is an empty array, then we return 0.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | an array of numbers, or of objects that can be cast into a number, e.g. ['1', 2.5, 3e1]

##### Returns:

the average of the elements in the array

Type
  number

#### (static) count(input, value)

Source:
  - util/Util.js, line 1220

Count the number of elements in the input array that match the given value.

Note: count is able to handle NaN, null, as well as any value convertible to a JSON string.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | the input array
`value` | Number | string | object | null | the matching value

##### Returns:

the number of matching elements

#### (static) detectBrowser() → {string}

Source:
  - util/Util.js, line 130

Detect the user's browser.

Note: since user agent is easily spoofed, we use a more sophisticated approach, as described here: https://stackoverflow.com/a/9851769

##### Returns:

the detected browser, one of 'Opera', 'Firefox', 'Safari', 'IE', 'Edge', 'EdgeChromium', 'Chrome', 'unknown'

Type
  string

#### (static) extensionFromMimeType(mimeType) → {string}

Source:
  - util/Util.js, line 1321

Return the file extension corresponding to an audio mime type. If the provided mimeType is not a string (e.g. null, undefined, an array) or unknown, then '.dat' is returned, instead of throwing an exception.

##### Parameters:

Name | Type | Description
--- | --- | ---
`mimeType` | string | the MIME type, e.g. 'audio/webm;codecs=opus'

##### Returns:

the corresponding file extension, e.g. '.webm'

Type
  string

#### (static) flattenArray(array) → {Array.<Object>}

Source:
  - util/Util.js, line 800

Recursively flatten an array of arrays.

##### Parameters:

Name | Type | Description
--- | --- | ---
`array` | Array.<Object> | the input array of arrays

##### Returns:

the flatten array

Type
  Array.<Object>

#### (static) getDownloadSpeed(psychoJS, nbDownloadsopt) → {number}

Source:
  - util/Util.js, line 1360

Get an estimate of the download speed, by repeatedly downloading an image file from a distant server.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`psychoJS` | PsychoJS |  |  | the instance of PsychoJS
`nbDownloads` | number | <optional> | `1` | the number of image downloads over which to average the download speed

##### Returns:

the download speed, in megabits per second

Type
  number

#### (static) getErrorStack() → {string}

Source:
  - util/Util.js, line 77

Get the error stack of the calling, exception-throwing function.

##### Returns:

the error stack as a string

Type
  string

#### (static) getPositionFromObject(object, units) → {Array.<number>}

Source:
  - util/Util.js, line 356

Get the position of the object, in pixel units

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | Object | the input object
`units` | string | the units

##### Returns:

the position of the object, in pixel units

Type
  Array.<number>

#### (static) getRequestError(jqXHR, textStatus, errorThrown)

Source:
  - util/Util.js, line 642

Get the most informative error from the server response from a jquery server request.

##### Parameters:

Name | Type | Description
--- | --- | ---
`jqXHR` |  |
`textStatus` |  |
`errorThrown` |  |

#### (static) getUrlParameters() → {URLSearchParams}

Source:
  - util/Util.js, line 691

Get the URL parameters.

##### Example

    const urlParameters = util.getUrlParameters();
    for (const [key, value] of urlParameters)
      console.log(key + ' = ' + value);

##### Returns:

the iterable URLSearchParams

Type
  URLSearchParams

#### (static) index(input, value)

Source:
  - util/Util.js, line 1283

Get the index in the input array of the first element that matches the given value.

Note: index is able to handle NaN, null, as well as any value convertible to a JSON string.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | the input array
`value` | Number | string | object | null | the matching value

##### Throws:

if the input array does not contain any matching element

##### Returns:

the index of the first element that matches the value

#### (static) isEmpty(x) → {boolean}

Source:
  - util/Util.js, line 99

Test if x is an 'empty' value.

##### Parameters:

Name | Type | Description
--- | --- | ---
`x` | Object | the value to test

##### Returns:

true if x is one of the following: undefined, [], [undefined]

Type
  boolean

#### (static) isInt(obj) → {boolean}

Source:
  - util/Util.js, line 669

Test whether an object is either an integer or the string representation of an integer.

This is adapted from: https://stackoverflow.com/a/14794066

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | Object | the input object

##### Returns:

whether or not the object is an integer or the string representation of an integer

Type
  boolean

#### (static) isNumeric(input) → {boolean}

Source:
  - util/Util.js, line 277

Check whether a value looks like a number

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | * | Some value

##### Returns:

Whether or not the value can be converted into a number

Type
  boolean

#### (static) IsPointInsidePolygon(point, vertices) → {boolean}

Source:
  - util/Util.js, line 290

Check whether a point lies within a polygon

We are using the algorithm described here: https://wrf.ecse.rpi.edu//Research/Short_Notes/pnpoly.html

##### Parameters:

Name | Type | Description
--- | --- | ---
`point` | Array.<number> | the point
`vertices` | Object | the vertices defining the polygon

##### Returns:

whether or not the point lies within the polygon

Type
  boolean

#### (static) makeUuid() → {string}

Source:
  - util/Util.js, line 63

Get a Universally Unique Identifier (RFC4122 version 4)

See details here: https://www.ietf.org/rfc/rfc4122.txt

##### Returns:

the uuid

Type
  string

#### (static) offerDataForDownload(filename, data, type)

Source:
  - util/Util.js, line 862

Offer data as download in the browser.

##### Parameters:

Name | Type | Description
--- | --- | ---
`filename` | string | the name of the file to be downloaded
`data` | * | the data
`type` | string | the MIME type of the data, e.g. 'text/csv' or 'application/json'

#### (static) pad(n, width) → {string}

Source:
  - util/Util.js, line 1260

Pad the given floating-point number with however many 0 needed at the start such that the padded integer part of the number is of the given width.

##### Parameters:

Name | Type | Description
--- | --- | ---
`n` |  | the input floating-point number
`width` |  | the desired width

##### Returns:

- the padded number, whose integer part has the given width

Type
  string

#### (static) promiseToTupple(promise) → {Array.<Object>}

Source:
  - util/Util.js, line 50

Convert the resulting value of a promise into a tupple.

##### Parameters:

Name | Type | Description
--- | --- | ---
`promise` | Promise | the promise

##### Returns:

the resulting value in the format [error, return data] where error is null if there was no error

Type
  Array.<Object>

#### (static) randchoice(array, randomNumberGeneratoropt) → {Array.<Object>}

Source:
  - util/Util.js, line 339

Pick a random value from an array, uses `util.shuffle` to shuffle the array and returns the last value.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`array` | Array.<Object> |  | the input 1-D array
`randomNumberGenerator` | function | <optional> | A function used to generated random numbers in the interal [0, 1). Defaults to Math.random

##### Returns:

a chosen value from the array

Type
  Array.<Object>

#### (static) randint(minopt, max) → {number}

Source:
  - util/Util.js, line 933

Generates random integers a-la NumPy's in the "half-open" interval [min, max). In other words, from min inclusive to max exclusive. When max is undefined, as is the case by default, results are chosen from [0, min). An error is thrown if max is less than min.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`min` | number | <optional> | `0` | lowest integer to be drawn, or highest plus one if max is undefined (default)
`max` | number |  |  | one above the largest integer to be drawn

##### Returns:

a random integer in the requested range (signed)

Type
  number

#### (static) range(startopt, stop, stepopt) → {Array.<Number>}

Source:
  - util/Util.js, line 1076

Create a sequence of integers.

The sequence is such that the integer at index i is: start + step * i, with i >= 0 and start + step * i < stop

Note: this is a JavaScript implement of the Python range function, which explains the unusual management of arguments.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`start` | Number | <optional> | `0` | the value of start
`stop` | Number |  |  | the value of stop
`step` | Number | <optional> | `1` | the value of step

##### Returns:

the range as an array of numbers

Type
  Array.<Number>

#### (static) round(input, places) → {number}

Source:
  - util/Util.js, line 966
See:
  - Stack Overflow

Round to a certain number of decimal places.

This is the Crib Sheet provided solution, but please note that as of 2020 the most popular SO answer is different.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | number | the number to be rounded
`places` | number | the max number of decimals desired

##### Returns:

input rounded to the specified number of decimal places at most

Type
  number

#### (static) selectFromArray(array, selection) → {Object|Array.<Object>}

Source:
  - util/Util.js, line 746

Select values from an array.

'selection' can be a single integer, an array of indices, or a string to be parsed, e.g.:

- 5
- [1,2,3,10]
- '1,5,10'
- '1:2:5'
- '5:'
- '-5:-2, 9, 11:5:22'

##### Parameters:

Name | Type | Description
--- | --- | ---
`array` | Array.<Object> | the input array
`selection` | number | Array.<number> | string | the selection

##### Returns:

the array of selected items

Type
  Object | Array.<Object>

#### (static) shuffle(array, randomNumberGeneratoropt) → {Array.<Object>}

Source:
  - util/Util.js, line 318

Shuffle an array in place using the Fisher-Yastes's modern algorithm

See details here: https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`array` | Array.<Object> |  | the input 1-D array
`randomNumberGenerator` | function | <optional> | A function used to generated random numbers in the interal [0, 1). Defaults to Math.random

##### Returns:

the shuffled array

Type
  Array.<Object>

#### (static) sliceArray(array, fromopt, toopt, stepopt) → {Array.<Object>}

Source:
  - util/Util.js, line 821

Slice an array.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`array` | Array.<Object> |  |  | the input array
`from` | number | <optional> | `NaN` | the start of the slice
`to` | number | <optional> | `NaN` | the end of the slice
`step` | number | <optional> | `NaN` | the step of the slice

##### Returns:

the array slice

Type
  Array.<Object>

#### (static) sort(input) → {array}

Source:
  - util/Util.js, line 1029

Sort the elements of the input array, in increasing alphabetical or numerical order.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | an array of numbers or of strings

##### Throws:

if 'input' is not an array, or if its elements are not consistent in types, or if they are not all either numbers or strings

##### Returns:

the sorted array

Type
  array

#### (static) sum(input, start) → {number}

Source:
  - util/Util.js, line 980

Calculate the sum of the elements in the input array.

If 'input' is not an array, then we return start.

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | array | an array of numbers, or of objects that can be cast into a number, e.g. ['1', 2.5, 3e1]
`start` | number | value added to the sum of numbers (a la Python)

##### Returns:

the sum of the elements in the array + start

Type
  number

#### (static) to_height(pos, posUnit, win) → {Array.<number>}

Source:
  - util/Util.js, line 472

Convert the position to height units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window

##### Returns:

the position in height units

Type
  Array.<number>

#### (static) to_norm(pos, posUnit, win) → {Array.<number>}

Source:
  - util/Util.js, line 443

Convert the position to norm units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window

##### Returns:

the position in norm units

Type
  Array.<number>

#### (static) to_pixiPoint(pos, posUnit, win, integerCoordinatesopt) → {Array.<number>}

Source:
  - util/Pixi.js, line 13

Convert a position to a PIXI Point.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`pos` | Array.<number> |  |  | the input position
`posUnit` | string |  |  | the position units
`win` | Window |  |  | the associated Window
`integerCoordinates` | boolean | <optional> | `false` | whether or not to round the PIXI Point coordinates.

##### Returns:

the position as a PIXI Point

Type
  Array.<number>

#### (static) to_px(pos, posUnit, win, integerCoordinatesopt) → {Array.<number>}

Source:
  - util/Util.js, line 398

Convert the position to pixel units.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`pos` | Array.<number> |  |  | the input position
`posUnit` | string |  |  | the position units
`win` | Window |  |  | the associated Window
`integerCoordinates` | boolean | <optional> | `false` | whether or not to round the position coordinates.

##### Returns:

the position in pixel units

Type
  Array.<number>

#### (static) to_unit(pos, posUnit, win, targetUnit) → {Array.<number>}

Source:
  - util/Util.js, line 541

Convert the position to given units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window
`targetUnit` | string | the target units

##### Returns:

the position in target units

Type
  Array.<number>

#### (static) to_win(pos, posUnit, win) → {Array.<number>}

Source:
  - util/Util.js, line 505

Convert the position to window units.

##### Parameters:

Name | Type | Description
--- | --- | ---
`pos` | Array.<number> | the input position
`posUnit` | string | the position units
`win` | Window | the associated Window

##### Returns:

the position in window units

Type
  Array.<number>

#### (static) toNumerical(obj) → {number|Array.<number>}

Source:
  - util/Util.js, line 210

Convert obj to its numerical form.

- number -> number, e.g. 2 -> 2
- [number] -> [number], e.g. [1,2,3] -> [1,2,3]
- numeral string -> number, e.g. "8" -> 8
- [number | numeral string] -> [number], e.g. [1, 2, "3"] -> [1,2,3]

##### Parameters:

Name | Type | Description
--- | --- | ---
`obj` | Object | the input object

##### Returns:

the numerical form of the input object

Type
  number | Array.<number>

#### (static) toString(object) → {string}

Source:
  - util/Util.js, line 576

Convert an object to its string representation, taking care of symbols.

Note: if the object is not already a string, we JSON stringify it and detect circularity.

##### Parameters:

Name | Type | Description
--- | --- | ---
`object` | Object | the input object

##### Returns:

a string representation of the object or 'Object (circular)'

Type
  string

#### (static) turnSquareBracketsIntoArrays(input, max) → {array}

Source:
  - util/Util.js, line 889

Convert a string representing a JSON array, e.g. "[1, 2]" into an array, e.g. ["1","2"]. This approach overcomes the built-in JSON parsing limitations when it comes to eg. floats missing the naught prefix, and is able to process several arrays, e.g. "[1,2][3,4]".

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | string | string potentially containing JSON arrays
`max` | string | how many matches to return, unwrap resulting array if less than two

##### Returns:

an array if arrays were found, undefined otherwise

Type
  array

#### (protected, inner) _match(value)

Source:
  - util/Util.js, line 1159

Create a boolean function that compares an input element to the given value.

##### Parameters:

Name | Type | Description
--- | --- | ---
`value` | Number | string | object | null | the matching value

##### Returns:

a function that compares an input element to the given value